AI AGENT SYSTEMS · 03

构建真正能完成任务的
Agent Loop

从一次性生成，走向可观察、可评估、会停止的任务执行系统

理论 Observe / Act / Evaluate / Stop 实战 Python Basic + Advanced
学习目标

Agent 的价值不是“自主”，而是有边界地完成任务

核心结论：一个可交付 Agent 必须知道当前状态、下一步动作、成功标准、剩余预算和停止条件。

Loop Contract定义 Observe、Plan、Act、Evaluate 和 Stop 的输入输出。
State & Checkpoint让长任务可以恢复、审计和人工接管。
Action Safety控制文件范围、工具权限、副作用和最小修改。
Task Eval以外部测试和验收标准判断任务是否真的完成。
失败现场

“Agent 已修复问题”，测试却仍然失败

核心结论：没有 Observe 和 Evaluate 的 Agent，本质上只是多次调用模型。

输入
Review
total() 忽略 quantity，请修复并运行测试目标、范围和验收标准都很明确
Agent
动作
重写整个模块，并增加无关 TODO没有先复现失败，也没有查看相关测试
结果
声称
“修复完成”，但实际测试仍失败模型自评代替了外部验证
方法论主线

Agent Loop 是一个有状态的控制系统

观察Observe读取任务、环境、失败证据和可用工具
决策Plan选择最小下一步，而不是一次规划全部未来
执行Act调用受控工具并记录结构化结果
验证Evaluate用测试、规则或环境反馈判断进展
控制Stop / Handoff成功、预算耗尽、风险过高或无进展时停止
工程落地每轮只执行一个可验证动作，每轮结束都重新判断是否继续。
Loop Contract

循环开始前，必须先定义成功与停止

核心结论：如果 Agent 不知道什么叫完成，它就只能把“继续行动”误当成进展。

Success Criteria哪些测试、状态或交付物全部满足，任务才算完成。
Iteration Budget最大步骤、最长时间、Token 与费用上限。
Progress Signal每轮必须改善哪个可观察指标，如何识别重复动作。
Stop & Handoff预算耗尽、权限不足、风险过高和无进展时如何退出。
工程落地把这些字段作为任务配置传给 Runtime，而不是散落在 Prompt 的自然语言里。
理论 01

Observe 必须先于 Act

核心结论：Agent 在不了解环境状态时生成动作，等同于在未知数据库和未知权限下直接执行脚本。

task用户目标与非目标
environment仓库、分支、依赖和权限
evidence失败测试、日志、Review 意见
constraints文件范围、时间和成本预算
available_tools当前允许的观察与执行能力
checkpoint上次完成步骤和未解决问题
Bad → Good 01

不要在没有失败证据时开始改代码

看到 “quantity bug” 就搜索并替换整个仓库。

  • 没有复现测试
  • 不知道真实函数签名
  • 无法证明补丁相关
read review comment
→ locate target + tests
→ run failing test
→ explain failure
→ propose minimal patch
观察结果进入下一步计划
Plan Contract

计划不是长篇推理，而是可验证的下一步

核心结论：高质量计划应该说明动作、依据、预期结果和失败后的分支。

动作修改 total() 中的计算表达式，不重写文件。
依据失败测试显示 expected 35, actual 15，差异来自 quantity 未参与计算。
预期目标测试从失败变为通过，其他测试保持不变。
失败分支若仍失败，重新观察数据结构，不连续叠加猜测补丁。
Action Boundary

Agent 能做什么，由系统策略决定

低风险动作读取文件和测试搜索符号与依赖生成未应用 diff运行限定测试
高风险动作删除或批量重写文件修改依赖与迁移数据访问密钥或外部系统发布、部署和合并代码
工程落地高风险动作必须缩小范围、增加确认，或转人工；Prompt 中的“请小心”不是权限控制。
Basic Python

Bounded Code Repair Loop

核心结论：基础项目用一个 quantity bug 展示完整闭环，而不是展示模型能生成多少代码。

projects/lesson-03/basicmain.pysrc/loop.pytests/test_loop.py
01 observe复现 expected / actual
02 act应用最小表达式修改
03 stop测试通过立即停止
python3 main.py compare
Basic Trace

每一步都应该留下结构化证据

lesson-03/basic · run
iteration=1 phase=observe passed=false
detail="expected=35 actual=15"
iteration=1 phase=plan detail="include quantity"
iteration=1 phase=act detail="minimal replacement"
iteration=2 phase=observe passed=true
iteration=2 phase=stop reason="tests_passed"
2迭代次数
1最小修改
3/3测试通过
理论 02

Evaluate 必须使用外部信号

核心结论：让模型评价自己的答案，不能替代测试、编译器、规则、数据库状态或人工审批。

确定性自动测试单元测试、类型检查、lint、schema 和状态断言。
半确定性规则与 Rubric最小 diff、文件范围、风险字段和引用完整性。
模型评审辅助判断用于风格、覆盖度和开放问题，不能单独批准高风险动作。
人工判断业务验收需求取舍、合规边界、发布和不可逆动作。
Stop Contract

会停止，才是真正可控的 Agent

成功停止验收条件全部满足。输出结果与证据
预算停止迭代、时间或成本达到上限。保存 checkpoint
无进展停止连续步骤没有改善指标。报告阻塞原因
风险停止需要高权限或不可逆动作。请求人工确认
Bad → Good 02

“再试一次”不是恢复策略

核心结论：无条件重试会重复同一错误；恢复必须基于 checkpoint、错误分类和新的观察。

测试失败后重复生成更大的补丁。

  • 没有保留最后稳定状态
  • 错误上下文不断累积
  • 无法人工接管
save checkpoint
classify failure
restore stable state
collect new evidence
resume or handoff
恢复从确定状态开始
Checkpoint

长任务需要可恢复的状态，而不是超长对话

task_id稳定任务标识
iteration当前循环位置
working_state文件、分支和临时结果
completed_steps已验证动作
open_issues未解决问题与风险
next_action恢复后的候选动作
Bad → Good 03

代码 Agent 应提交最小补丁，不是重写作品

核心结论：补丁越大，验证成本和回归风险越高；Agent 必须证明每一处修改都与任务相关。

REVIEWtotal() 忽略 quantity
OBSERVE唯一失败来自乘法缺失
错误重写模块扩大影响面
正确一行 diff测试证明修复
Advanced Python

Repository Maintenance Patch Agent

核心结论：进阶项目把 review comment、测试证据、最小补丁、checkpoint 和停止条件组合为可交付流程。

Review CommentRepositoryTests
AGENT LOOPObservePlan + PatchEvaluateCheckpoint
Minimal DiffTest EvidenceRisk Report
python3 main.py compare
Agent Eval

任务成功率之外，还要评估过程质量

指标
防止的问题
验收
门禁
Task success
没有真正修复
测试通过
PASS
Patch size
无关重写
最小 diff
PASS
Tool policy
越权动作
白名单内
PASS
Stop quality
无限循环
成功即停止
PASS
常见陷阱

Agent 失败往往不是模型不够强

状态不清任务、环境和已完成步骤混在对话文本里，恢复后无法确定当前状态。
动作过大一次修改多个模块，任何失败都难以定位原因。
验证过弱只让模型总结“应该没问题”，没有外部测试。
停止缺失成功后继续优化，或失败后无限重试。
权限过宽开发便利性演变为生产环境的不可控副作用。
Human Handoff

人工接管是流程状态，不是 Agent 失败

核心结论：高质量 handoff 应让人直接继续工作，而不是重新阅读全部对话。

current_state任务现在处于哪一步
attempted_actions已经做过什么
evidence测试、日志和 diff
blocking_reason为什么不能继续
risk继续自动化的风险
recommended_action人工下一步建议
课堂实战

从失败测试走到可审查补丁

20 minBasic

运行失败、观察 trace、修改停止预算。

35 minAdvanced

加入第二个 review comment，生成最小补丁与 checkpoint。

15 minReview

检查 diff 范围、测试证据和 handoff 信息。

验收

上线前，检查八个 Agent Loop 问题

01 是否先观察再行动？
02 状态是否结构化保存？
03 每步是否最小可验证？
04 动作权限是否受控？
05 是否使用外部成功信号？
06 是否有迭代和成本预算？
07 是否支持 checkpoint 恢复？
08 人工能否直接接管？
Lesson 03 · Takeaway

Agent 不是“能一直做事”的模型。
Agent 是知道何时行动、验证和停止的系统。

NEXT · Lesson 04　Memory 与多 Agent 协作