第 1 章 Agent 核心循环、任务目标与停止条件
1.1 Agent 与 Workflow
Workflow 预先规定每一步;Agent 根据中间结果选择下一步,但只能在允许的工具与权限范围里行动。
正确理解
- Workflow 是固定的 A → B → C。上传文件后固定做 OCR、入库,就属于工作流。
- 定位未知 Bug 时要反复读代码、修改、验证,下一步取决于上一步的结果,更适合 Agent。
1.2 Agent Loop
一次循环:用户目标 → 构建 Context → 模型提出回答或 Tool Call → 程序校验并执行 → 工具结果返回 Context → 模型继续或结束。
我踩过的坑
- 以为模型提出了 Tool Call,就等于工具已经执行成功。
正确理解
- 工具 Schema 只定义模型怎样提出请求。实际执行、权限检查、异常处理和结果回传都由程序负责。
- 状态机控制的是回合推进,不等于必须同步阻塞整个线程。模型可能返回工具请求、纯文本、受限制的输出或异常中断,程序要校验停止原因和实际调用状态,再决定执行工具、继续生成还是结束。
- 等待网络模型时,仍应按实现使用异步 I/O、超时和取消。不能把旧 SyncStateMachine 教材里的“阻塞态”理解成 Python 事件循环必须一直卡住。
1.3 可验证目标与停止条件
Loop 要有程序或独立验收者能检查的终态;循环不断运行不等于持续进步。
我踩过的坑
- Loop Engineering 练习里,我把“按照目标自主执行”理解成主观能动性,甚至把“让用户满意”“代码质量要好”直接当停止条件。
正确理解
- “让界面好看点”没有停止边界;“指定视口无横向溢出、测试通过”才能检查是否完成。
- 每轮都看与目标还差什么。成功凭证据停止;失败在时间、轮次、Token 或工具预算用尽时停止;不确定或高风险升级给人。
- 终态要能被检查,例如指定视口不溢出、关键测试通过、输出符合业务约束。评估者可以是测试代码、人工核验或独立模型调用,不一定非要另建一个 Subagent。评估无法量化时要停下来补标准,不能无限循环。
- 声明式目标也不等于发一次通知,循环要不断检查差距,直到完成或预算用尽。
- 链式任务可以分阶段验收,但失败必须有界。 例如先定义接口契约,再生成测试,最后实现业务逻辑,每阶段产物经过确定性的格式或业务约束检查再进入下一步。验收失败优先局部修正,仍要限制轮数、时间和副作用;“一直重试到通过”可能变成无穷循环。阶段门禁也不能只看 JSON 语法合法,就断言业务需求完整。
- Loop 护栏可以识别“没有进展”,但不要把重复调用都当死循环。 值得监测的信号有三种:同一工具和参数反复失败、参数不同但失败同类、只读工具多次返回同样数据。任务如果确实需要轮询等待、分页或重试,重复也可能合理。可以分别配置提醒、暂停和上报,结合实际任务状态和剩余预算判断,不把旧稿的 2/5/8 次阈值写成通用正确值。
1.4 生成、执行与验证分工
Agent 可以生成代码或 SQL,但执行层负责权限、资源限制和副作用,完成与否靠验证证据判断。
正确理解
- 完成后靠测试、实际页面和真实数据验证,不能因为模型说“完成”就判定成功。
- 约束完全确定时,可以让更便宜的模型执行,用确定性测试守住验收;但不能认为 CI 能挡住所有运行时风险。
1.5 长任务卡住
Agent“卡住”不一定是线程死锁。多轮无进展、请求挂起、历史裁剪后无法恢复,是不同的故障。
正确理解
- 要分辨:多轮动作无进展、流式模型请求长时间没有 Chunk、消息压缩后工具调用与结果不再配对。
- 重复查询也可能是合法的轮询或分页,所以要同时看目标是否前进、有没有新证据、剩余预算和工具副作用。
| 现象 | 首先核对 | 应保留的退出证据 |
|---|---|---|
| 多轮同类调用、无进展 | 可测目标、参数变化、返回数据和重试预算 | 重复轨迹、未完成项与停止原因 |
| 一次模型/工具流不返回 | 请求 ID、首字与空闲时间、连接与下游状态 | 最后 Chunk、取消时刻和结果 |
| 历史裁剪后无法恢复 | ToolCall/ToolResult 配对、最近有效快照 | 断点、摘要与可重放片段 |
- 超时取消的是客户端等待,不保证远端任务或已发生的写操作也被撤销。 已经付款、写库、发消息的动作,要先查业务状态和幂等键,再决定能否重试。
- 旧 Wiki 提到的 2000 字、10 轮、120 秒只是历史设计阈值,没有针对当前模型和任务做过误杀测试。
- 结束状态至少区分成功、预算用尽、无进展、依赖异常;不能把“熔断成功”写成“任务达标”。
Pi 只思考不说话、pi-goal 重复工具结果导致 400 的具体故障,见附录 A.1.1、A.1.2。
来源
旧 Wiki 10-wiki/personal/wiki/concepts/agent死锁检测与熔断.md、Agent注意力漂移.md。这是设计素材,不是当前产品已部署的 Watchdog。
1.6 模块化单体先复用用例,再区分入口
HTTP、流式接口和消息消费者可以共用同一个聊天用例;多个进程入口不等于每个 Agent 都是微服务。
原文记录(2026-11-05 的缓存代码快照):普通请求先保存用户消息,再做命令分发、资料与上下文构建、分类、一个具体 Agent 的工具循环,最后统一输出并保存助手结果。长耗时模型调用放在消息持久化事务之外,不能把整轮对话锁在一个数据库事务里,也不能机械说系统总共只有两个事务。
判断:确定性命令适合先短路,模糊问题再路由;命令分支中的某个子用例仍可能调用模型。分类器只选一个 Agent,也不等于多个专家并行讨论。回答已生成、结果已保存、渠道已投递分别留证据。
架构、上下文与记忆的细节。职责与面试复盘见《个人档案》第5章。