Agent X-Ray

阶段 4 实践 — 手写一个最小 Agent Loop

约 4 分钟 · 更新于 2026-09-01

阶段 4 实践 — 手写一个最小 Agent Loop

本实践的产出 ⭐ 最小产出：不使用任何 Agent Framework，手写一个最小 Agent Loop 并记录完整轨迹完整产出：最小 Loop + 轨迹记录 + 故障注入实验 + 预算与确认点改造

预计投入：6～10 小时。这是整条学习路线里唯一必须自己写代码的实践——不用写得好，但必须自己写，因为只有自己写过 Loop，后面读四份 Harness 教程才是“对照”而不是“阅读”。

为什么不能用框架 用了框架，loop 就是黑盒；黑盒里的东西你永远只能背结论。目标不是产出可用代码，是亲手感受"模型只吐意图、执行全靠你"这件事。150 行以内足够。

实践 1 · 最小 Loop（⭐ 必做）

硬性约束

不用 LangChain / Agents SDK / Claude Agent SDK / 任何 agent 框架
只允许用模型厂商的基础 HTTP 调用或最薄的 SDK（只用它发消息，不用它的 agent 层）
全部代码 ≤ 150 行
放 ai-output/temporary/scripts/，用本仓 .venv

要实现的骨架

text

while True:
    resp = call_model(messages, tools)
    记录一条 step 日志
    if resp 无工具调用:
        break（stop_reason = completed）
    for 每个 tool_call:
        校验参数
        执行
        把结果作为 tool 消息追加进 messages
    检查停止条件（步数 / token / 超时）

工具集（3 个就够，且要有意设计成有区分度）

工具	类型	设计意图
search_flights(origin, dest, date)	只读	正常路径
get_fare_rule(flight_no, cabin)	只读	需要前一步的结果作为参数（考验状态传递）
hold_seat(flight_no, passengers)	有副作用	后面用来加确认点和幂等键

数据可以是假的（写死几条），重点在契约不在数据。

任务

给它一个需要至少 3 步的任务，例如：

"帮我看看 8 月 30 号上海到东京有什么航班，最便宜那班的经济舱能不能改签，可以的话先占个座。"

实践 2 · 完整轨迹记录

每一步都要落盘，字段至少包含：

字段	说明
step_index	第几步
messages_in_tokens	本次请求的输入 token
model_output	模型原始输出（含思考块，如果有）
tool_calls[]	名称 + 参数原文
tool_results[]	结果 + 是否成功 + 耗时
transition_reason	本步之后为何进入下一圈：正常推进 / 恢复 / 等待确认等
withheld_error	是否有可恢复错误被暂存、未直接暴露给下游
terminal_reason	最终为什么停止；非终止步骤为空
usage	输入/输出/缓存 token
wall_clock_ms	本步耗时

产出：一份完整任务的轨迹 JSON + 一段人读的时序说明。

要回答的问题：

这个任务一共走了几步？其中几步是"有效推进"，几步是"确认/复述"？
输入 token 是怎么增长的？画一条曲线（这条曲线就是阶段 3 上下文压缩的动机）
哪一步的耗时最长？是模型还是工具？

实践 3 · 故障注入：Agent 能恢复吗

依次注入四种故障，各跑 3 次，记录行为：

注入	具体做法	观察什么
A · 参数错误	工具返回 {"error":"invalid_date_format"}，不给更多信息	它会怎么改？还是原样重试？
B · 指令性错误	同上，但返回 {"error":"depart_date must be ISO 8601, got '8月30号'"}	改善多少？
C · 空结果	search_flights 返回空列表	会追问用户，还是编一个航班？
D · 持续失败	某工具永远返回 500	几步之后放弃？还是无限重试？

记录表：

注入	第一次反应	3 次内是否恢复	最终停止原因	有没有把中间结果交出来

要看到的现象（这是本实践最有价值的部分）：

B 明显好于 A ——工具错误信息的措辞，是 Agent 可靠性最便宜的杠杆
C 情况下，如果它编了一个航班号，说明工具的"空结果"语义没写清楚
D 情况下，如果它无限重试，说明缺停止条件；如果它直接崩掉，说明缺"带中间结果退出"

产出：一份《工具错误信息写作规范》草稿，至少包含：错误码 / 人读原因 / 可执行的下一步建议 / 是否可重试。这份规范在阶段 5 会直接变成工具契约的一部分。

实践 4 · 加上预算与确认点

在最小 Loop 上追加四样东西：

最大步数（建议 8）：到达上限时返回已完成的部分 + 说明差什么
Token 预算：累计输入+输出超过阈值就停
超时：整任务墙钟时间上限
人工确认点：hold_seat 调用前必须暂停，打印"即将执行：占座 MU5101 / 2 成人 / 8-30，确认？"并等待输入

额外要求：

给 hold_seat 加幂等键（例如任务ID + 航班 + 乘客的哈希），并写一个测试：连续调两次，第二次应返回"已存在"而不是占两个座
确认点被拒绝时，Agent 应当优雅收尾（说明未执行、给出替代建议），而不是报错退出

验收：

三种停止条件都能触发一次，且每次都有可读的结果
幂等测试通过

实践 5 · 与四份 Harness 对照

跑完自己的 Loop，回头读这四章，逐项对照：

问题	我的实现	Codex	Claude Code
循环层级怎么分	只有一层	Task/Turn/Step	单循环 + 显式 Transition
工具执行前有没有权限层
上下文超了怎么办
中途能不能插话
停止原因有几种
可恢复错误何时对外可见
一次运行如何被观察

对照来源：Pi 第 3 章、dsh 第 5 章、Codex 第 4 章、Claude Code 第 3 章。

验收：能说出至少三件“我的 150 行没做、但生产级 Harness 必须处理”的事，并解释各自解决什么问题；其中至少一件来自 Claude Code 的 Transition、错误暂存或投机执行作废语义。

自测

维度	阶段 4 的问法
解释	给传统产品经理讲清"为什么 Agent 的行为不可预测"
画图	画出自己 loop 的状态机，标出四个产品可介入的关口
比较	同一个任务用 Workflow 写 vs 用 Agent 写，各自的代码量、可测性、覆盖面
实践	Loop 跑通 + 四种故障注入有记录
评测	定义"这次任务成功"的判据——是否包含轨迹合理性？
产品化	《工具错误信息写作规范》能拿去评审
迁移	换一个业务任务（支付对账），这个 loop 骨架要改什么？

通过标志 能对着自己的轨迹 JSON，指出每一步失败该归给谁（模型/上下文/工具/Harness）。做不到就重跑故障注入。

阶段 4 讲义
阶段 5 实践
阶段 10 讲义
学习路线

本章目录

实践 1 · 最小 Loop（⭐ 必做）实践 2 · 完整轨迹记录实践 3 · 故障注入：Agent 能恢复吗实践 4 · 加上预算与确认点实践 5 · 与四份 Harness 对照自测 Related Documents