Guide · 使用教程
Inspect AI Python 教程：Agent 工具调用轨迹、评分与执行限额
使用固定版本与官方模拟模型，验证工具名、参数、返回关联和最终答案，设置执行限额并解释评分与费用边界。
作者：Li Xuan·更新于 2026年10月16日
一个 Agent 回答“订单已送达”，并不能证明它查询了正确订单。本教程用 Inspect AI 建立只读订单 fixture，把工具名、参数、结果和最终答案一起评分，再给执行设置限额。示例使用固定版本和官方 mock 模型，先确认评估器会区分正确与错误轨迹。
验证日期为 2026-10-17，固定 inspect-ai==0.3.281。本地通过八组规则测试和五条真实框架内的模拟轨迹；没有调用付费模型、真实订单服务或写接口。模拟模型输出由代码预设，因此这些结果验证评估管线，不证明真实 Agent 的能力。
1. 明确每个样本的通过条件
本例要求只调用一次 lookup_order，订单号必须是 1001；工具返回必须与调用 ID 关联，且没有执行错误；最终答案必须是与结果一致的严格 JSON。下面这种“最后一句正确、过程没查询”的情况应判失败。
| 轨迹 | 应有结果 |
|---|---|
| 查询 1001 成功后返回对应 JSON | 通过 |
| 未查询，直接猜中 delivered | 失败 |
| 查询 1002，却回答 1001 已送达 | 失败 |
| 工具返回错误后仍肯定回答 | 失败 |
| 额外查询其他订单 | 失败 |
这里只测试一条允许路径。真实业务允许重试、多条有效顺序或缓存时，应显式改写规则和 reference，再验证判分器。不能把“只调用一次”推广成所有 Agent 的标准答案。
2. 安装固定版本
在新的项目目录运行，保留两个 Python 文件与日志目录。示例不需要 API Key。
bash
python3 -m venv .venv
.venv/bin/pip install 'inspect-ai==0.3.281'
Inspect Task 组合数据集、执行与 scorer；Python 工具通过 @tool 注册，再由 use_tools 和 generate 参与模型循环。工具参数类型与说明用于生成工具契约。官方工具文档
3. 实现工具、轨迹检查与 scorer
保存为 tool_eval.py。两个订单状态均为合成 fixture，1003 专门模拟工具故障。没有生产身份、账户授权或订单读取能力；正式接入仍应由服务端落实身份和对象权限。
python
json
inspect_ai Task, task
inspect_ai.dataset Sample
inspect_ai.model ChatMessageAssistant, ChatMessageTool
inspect_ai.scorer CORRECT, INCORRECT, Score, accuracy, scorer
inspect_ai.solver TaskState, generate, use_tools
inspect_ai.tool ToolError, tool
():
() -> :
order_id == :
ToolError()
orders = {: , : }
order_id orders:
ToolError()
json.dumps({: order_id, : orders[order_id]})
execute
():
calls = [c m messages (m, ChatMessageAssistant) c (m.tool_calls [])]
results = [m m messages (m, ChatMessageTool)]
expected = {: order_id, : status}
flags = {: , : , : }
(calls) == :
call = calls[]
flags[] = (call.function == call.arguments == {: order_id} call.parse_error)
(results) == :
result = results[]
:
flags[] = (result.tool_call_id == call. result.function == result.error json.loads(result.text) == expected)
(TypeError, ValueError):
:
flags[] = json.loads(completion) == expected
(TypeError, ValueError):
flags
():
():
flags = judge_trace(state.messages, state.output.completion, state.metadata[], target.text)
Score(value=CORRECT (flags.values()) INCORRECT,
answer=state.output.completion, metadata=flags,
explanation=json.dumps(flags))
score
():
Task(
dataset=[Sample(=, =, target=, metadata={: })],
solver=[use_tools(lookup_order()), generate()],
scorer=trajectory_check(),
message_limit=, turn_limit=, token_limit=, time_limit=,
)
常见问题
- 教程会调用付费模型或真实订单吗？
- 不会。示例固定官方 mock 模型和合成只读 fixture，验证评估管线，不证明真实 Agent 的能力。
- 为什么答案正确还可能判失败？
- 如果没有查询、查询错对象、工具失败或有额外动作，就不满足该任务要求，不能只看最终文本。
- 这个 scorer 能直接用于所有 Agent 吗？
- 不能。它只允许一条只读查询路径；真实重试、多路径、缓存和权限规则需另行定义并验证。
- 消息、轮次、token 和时间限制是账单硬上限吗？
- 不是。模型、并发、在途请求和外部工具费用需分别控制，真实 cost_limit 也需要完整模型价格配置。
- 八组规则测试和五条轨迹分别验证什么？
- 规则测试验证正反例判分，五条官方框架模拟轨迹验证工具循环与 scorer 接入。未作真实模型能力或生产安全基准。
- 评分错误和错误答案能一起算吗？
- 应区分。错误答案是被测行为 verdict；scorer 故障与无法评分属于测量问题，需同时报告错误、覆盖和分母。