Python 工具调用 Agent 实战：可运行脚本、错误处理与测试

先把执行循环测清楚，再接真实模型。这个实验提供两个可以下载的文件，查询的是一条模拟订单；默认运行不需要 API Key。它适合已经会运行 Python 脚本、理解函数和 JSON 的学习者。

#1. 下载与运行

要求 Python 3.10 或以上，无需安装第三方依赖。将 tool_agent.py↗ 与 test_tool_agent.py↗ 保存到同一文件夹，然后在该文件夹运行：

bash
python3 tool_agent.py
python3 -m unittest -v test_tool_agent.py

2026-09-07 的离线运行结果：

json
{"mode": "fixture", "answer": "DEMO-1001: shipped (synthetic_fixture)", "steps": 2}

9 项测试覆盖正常闭环、未知订单、未注册工具、非法 JSON、参数结构错误、重复调用上限、批量工具调用、空回答和模型层超时。fixture 是脚本化模型替身；这些结果验证执行程序，不能作为 LLM 推理能力或真实接口可用性的证明。

函数	输入 → 输出	责任
`execute_tool(name, arguments)`	工具名与 JSON → 结构化结果	只允许 `lookup_order`；严格检查字段和类型
`run_agent(model, question)`	模型适配函数与问题 → 回答、轮次、历史	保留模型返回项，执行工具，按 `call_id` 回传结果，限制轮次
`fixture_model` / `live_model`	历史 → 模型输出项	前者提供确定性测试；后者调用真实 Responses API

程序没有执行任意 Python 或 shell 的入口。即使模型请求 delete_order，也只会得到 unknown_tool。

模型适配函数返回工具调用：

json
{"type":"function_call","call_id":"demo-call-1","name":"lookup_order","arguments":"{\"order_id\":\"DEMO-1001\"}"}

程序校验后生成结果，再把它作为 function_call_output 放回历史；call_id 必须与请求一致。结果正文是 JSON 字符串：

json
{"ok":true,"order_id":"DEMO-1001","status":"shipped","source":"synthetic_fixture"}

下一轮模型看到结果，才生成最终回答。脚本保留完整的 output 项，包括接口返回的 reasoning 项，而不是只摘出函数名称后丢掉其他上下文。工具调用官方说明↗

在同一个文件夹运行：

bash
python3 -c 'from tool_agent import execute_tool; print(execute_tool("lookup_order", "{\"order_id\":\"MISSING\"}"))'

返回 {'ok': False, 'error': 'order_not_found'}。这与“订单尚未发货”不同：前者没有查到记录，后者需要有记录支持。错误必须保留为错误，不能用默认状态补齐。

将测试里的模型替身改为一直请求工具时，程序在上限处抛出 step_limit_reached；空回答则抛出 model_returned_no_answer。失败不打印成“任务成功”。

脚本的 --live 路径使用标准库发送 HTTPS 请求到 OpenAI Responses API。先通过自己的安全环境配置设置 OPENAI_API_KEY 和 OPENAI_MODEL；模型需要在你的账号中可用且支持工具调用。不要把密钥写进教程、源码或分享截图。

bash
python3 tool_agent.py --live --question 'Look up DEMO-1001. Do not guess its status.'

此模式会产生实际模型请求和费用。本轮仅核对官方接口文档，未使用真实模型运行；账户权限、模型支持情况、实际输出和费用需要你运行后确认。工具仍读取模拟订单，不会连接真实客户数据库。默认离线模式的 --question 不会改变脚本化选择，只用于观察历史传递。

真实接口设 20 秒超时；认证失败、限流和网络错误直接抛出，不自动无限重试。工程项目中应进一步增加总耗时预算、请求取消、日志脱敏及调用成本限制。