AI Agent 开发入门：从工具调用到可测试的执行循环
第一次开发 Agent，建议先做一个只能查询、最多执行 4 轮的小程序。你需要看清模型提出什么动作、程序是否允许执行，以及失败时如何停止，再增加记忆和多智能体协作。
本手册从 Python 工具调用实验开始，随后连接 MCP、RAG 与评测。公开教程可以直接阅读；课程的学习权限以具体课程页面为准。
#AI Agent 与普通聊天有什么区别？
聊天模型输出文本。工具调用 Agent 还会提出一个结构化动作，例如 lookup_order({"order_id":"DEMO-1001"})。应用检查工具名和参数，执行查询，把结果交回模型，由模型决定回答还是继续调用工具。
模型提出动作，程序掌握执行权。 工具调用参数不是可直接执行的代码，不能交给 eval() 或 shell。
text用户问题 → 模型提出工具调用 → 工具白名单与参数校验 ↓ 最终回答 ← 模型读取工具结果 ← 查询结果 / 明确错误 ↓ 未完成则继续，达到轮次上限就停止
#第一个实验：查询一条模拟订单
打开完整的 Python 工具调用实验。示例只使用 Python 标准库，默认不连接模型、不消耗 API 额度。它用脚本化模型替身验证执行循环，订单数据明确标记为 synthetic_fixture。
下载 tool_agent.py↗ 和 test_tool_agent.py↗，放在同一个文件夹，运行：
bashpython3 tool_agent.py python3 -m unittest -v test_tool_agent.py
默认运行输出：
json{"mode": "fixture", "answer": "DEMO-1001: shipped (synthetic_fixture)", "steps": 2}
这证明了“请求工具 → 返回结果 → 结束”的程序流程，不代表真实模型的准确率或生产可用性。实验页也提供真实模型接入步骤及验证边界。
#AI Agent 开发架构：一次工具调用经过哪些环节？
上面的订单实验把模型和业务系统隔开。fixture_model() 只模拟模型返回；真正决定能否查询的是 run_agent() 和 execute_tool()。把这两层拆开，才能分别测试模型的选择与程序的权限判断。
- 输入与当前状态：
question与逐轮追加的history。工具结果必须在下一轮仍可见，错误不能被丢掉。 - 选择下一步：模型返回
function_call，或直接返回回答。没有工具调用时，回答必须非空。 - 工具边界：
execute_tool()只接受lookup_order和字符串order_id；delete_order、额外参数和无效 JSON 均被拒绝。 - 观察结果：程序把查询结果作为
function_call_output放回历史。不存在的订单返回order_not_found，不能编造状态。 - 停止条件：每轮最多一次调用，最多四轮。重复调用达到上限时明确失败，不无限循环。
这是一条可测试的执行循环，不等于“模型可以自由执行命令”。如果下一步要加入文件写入、邮件或退款工具，应为每个工具单独规定授权范围、输入校验和人工确认点，而不是把模型输出交给 eval() 或 shell。
#规划、记忆和环境信息什么时候加？
先判断任务是否真的需要跨步骤决策。查询一个订单只需“调用工具 → 检查结果 → 回答”，不需要长期记忆或多 Agent。若要处理“检查一组订单异常并起草处理建议”，才可能需要以下状态：已检查的订单 ID、每次查询的原始结果、失败原因、尚待人工复核的建议。状态记录事实；计划描述下一步；两者不能代替工具返回值。
在当前实验中，history 只在一次 run_agent() 调用期间存在。程序退出后它不会自动恢复，所以不要把它称为跨会话记忆。需要暂停后继续的业务流程，要明确保存哪些状态、谁可以读取、何时删除，并在恢复时重新检查工具权限。LangGraph 的状态与持久化示例↗展示了把步骤、共享状态和人工复核分开的做法；这只是可选实现，不是做 Agent 的前提。
#从演示到可交付功能的验收顺序
- 先跑离线循环：执行上面的两个命令，确认模拟订单返回
shipped (synthetic_fixture)且九项单元测试通过；不要把这个结果当作真实订单或真实模型的准确率。 - 再测失败路径：用测试里的不存在订单、未知工具、无效 JSON、重复调用和空回答案例，确认程序给出明确错误而不是猜答案。
- 最后接真实服务：在获准的测试环境中另行验证认证、超时、费用、日志脱敏和人工确认。本站提供的默认实验不发起模型请求；是否启用真实模式由运行者自行决定，并遵守其所在环境的权限与费用规则。
这样开发者可以先证明应用层的执行边界，再评估模型是否适合任务。把更多工具和“记忆”同时加进首个原型，会让失败难以定位。
#先决定：工作流、RAG，还是 Agent？
| 任务 | 先采用 | 原因 |
|---|---|---|
| 输入格式和步骤固定，如校验表单后生成文件 | 普通程序或固定工作流 | 无需让模型重新决定执行顺序 |
| 根据指定资料回答问题并给出出处 | RAG | 主要问题是找准证据，而非自主执行 |
| 根据中间结果选择不同工具、补充信息 | 有边界的 Agent | 下一步依赖实际观察结果 |
| 多个独立专业角色确实需要协作 | 验证单 Agent 后再考虑多 Agent | 需要额外处理交接、重试和结果冲突 |
这是工程选型建议。不要为了使用 Agent，把已经稳定的固定流程改成不可预测的循环。
#四个必须能解释的边界
- 工具权限：这个实验只读模拟订单；退款、发邮件和修改数据库不在工具列表里。
- 数据来源：查询失败返回
order_not_found，不能生成一个看似合理的物流状态。 - 运行上限：每轮最多 1 次工具调用，最多 4 轮；真实模型请求另设 20 秒超时。
- 验证范围：离线测试覆盖程序行为；接入模型后还要验证模型选择、回答正确性和成本。
#实践复盘：工具调用必须先通过程序检查
这个可下载实验由 JR Academy 作为教学示例发布，订单和模型回复均为预设数据。以下是 2026-10-26 本地实际运行结果；它展示执行边界的设计，不作为 Lightman 的商业项目或真实客户成果。
| 输入或故障 | 实际结果 | 设计取舍 |
|---|---|---|
调用 delete_order | unknown_tool | 只允许已登记的查询工具；模型不能自行扩充权限 |
查询不存在的 MISSING 订单 | order_not_found | 明确暴露查无记录，不能编造物流状态 |
工具参数只有 { | invalid_json | 解析失败就返回错误，不猜测用户意图修补参数 |
订单查询夹带 delete: true | invalid_arguments | 即使工具名正确，额外字段也会被拒绝 |
| 模型替身持续调用工具，限制设为 2 轮 | step_limit_reached | 有界停止便于检查失败；需要长任务时应显式调整预算 |
实现上，execute_tool 先检查工具名，再解析 JSON、检查字段和字段类型，最后读取订单。run_agent 每轮只接受一次工具调用，并保存调用与返回结果。单次调用限制牺牲并行吞吐，换取这个入门实验中更容易观察和测试的顺序。
默认正常路径经过两步后输出 DEMO-1001: shipped (synthetic_fixture)。测试覆盖上述拒绝分支、空回答、多次工具调用及模型异常，共 9 项通过。打开本次测试回执、具体输出与源文件 SHA-256。下载回执和两份 Python 文件后，可以对照散列确认自己运行的是同一版本。
本次补充的制作方式： AI 辅助整理，使用本地 Python 运行离线测试。没有调用真实模型，没有测量生产准确率、并发性能或真实业务效果；人工专业审校尚未登记。
#MCP 在哪一层？
MCP 连接 AI 应用与提供工具或上下文的服务。它不规定你必须使用哪个模型，也不自动处理你业务里的权限和正确性判断。先理解工具执行，再学习 MCP 协议与接入，更容易分清应用、客户端、服务端的责任。MCP 官方架构说明↗
#接下来学什么？
- 现在动手：完成工具调用实验，再故意输入一个不存在的订单。
- 扩展知识检索：RAG 知识库实验，检查答案能否对应到原文。
- 验证可靠性：评估与测试，将失败案例保留为回归用例。
- 系统学习：查看 AI Engineer Bootcamp 的课程安排与试学信息，再判断项目内容和先修要求是否适合自己。
技术依据：OpenAI 工具调用流程↗、MCP 架构↗。原指南核验记录：2026-09-07。本次实践补充与离线回归：2026-10-26，9 项测试通过，具体输出与源文件散列见上方回执；未运行真实模型模式。
