端到端编码 Agent:缝合整条赛道

端到端编码 Agent:缝合整条赛道

本节摘要:Agent Harness 赛道的回报。本节把门链、沙箱、评估套件、OTel span 缝成一个能修真实(小、夹具规模)bug 的多文件 Python 项目编码 Agent。Agent 是确定性策略而非 LLM——这个替换让本节可复现,并证明外壳一直是有趣的部分。契约一致:真模型在策略缝处插进去。多数 Agent demo 各自孤立工作(沙箱单跑、评估单跑、span 单跑),看着都行,一组合缝就露:门链说 ALLOW 但沙箱因链没预料的原因拒绝;评估记 pass 但 OTel span 说门拒了 Agent 声称用过的工具;计数器该 +1 却 +2。本节是整条赛道的集成测试。

对应原课程:Phase 19 · Lesson 29 · end-to-end-coding-task-demo(原英文 phases/19-capstone-projects/29-end-to-end-coding-task-demo/docs/en.md)。本节属「Agent Harness 深度构建赛道」第十节(收官)。

学习目标

阅读完本节,你应当能够:

1. 把门链、沙箱、评估套件、span 构建器组合成单个 Agent 循环。
2. 实现用 read_file、run_tests、write_file 修夹具 bug 的确定性策略。
3. 在端到端运行上强制全局步预算加观察 token 预算。
4. 为整次运行发完整 OTel GenAI trace 与 Prometheus 指标。
5. 验证 Agent 在 12 步内解出夹具,且对合法工具零门触发。

一、问题与直觉

多数 Agent demo 各自孤立工作:沙箱单跑、评估单跑、span 发射器单跑,看着都行。一组合缝就露。门链说 ALLOW 但沙箱因链没预料的原因拒绝。评估记 pass 但 OTel span 说门拒了 Agent 声称用过的工具。Prometheus 计数器该 +1 却 +2。观察预算超了但 Agent 继续跑,因为预算在链里跟踪、沙箱不知道。

本节是整条赛道的集成测试。Agent 得按序做四件:读项目、跑测试、从测试失败认 bug、写修复、重跑测试、停。每个操作经门链,每个工具执行经沙箱,每步包进 span,评估套件末尾给整件事打分。

二、从零实现

Agent 策略是状态机,五态。SURVEY:读项目清单,下一态 RUN_TESTS。RUN_TESTS:跑测试命令,过了则成功停,否则下一态 INSPECT。INSPECT:读失败源文件,下一态 FIX。FIX:写修正文件,下一态 VERIFY。VERIFY:再跑测试命令,过了成功停,否则失败停。每态对应一次工具调用,每次工具调用经门链;被拒则 Agent 在 trace 里报拒绝并停。

class CodingAgentPolicy:
    STATES = ["SURVEY", "RUN_TESTS", "INSPECT", "FIX", "VERIFY"]
    def next_action(self, state, observation):
        if state == "SURVEY":    return read_file("src/fizz.py")
        if state == "RUN_TESTS": return run_tests()
        if state == "INSPECT":   return read_file("src/fizz.py")
        if state == "FIX":       return write_file("src/fizz.py", FIXED)
        if state == "VERIFY":    return run_tests()
​

夹具 bug 是 fizz.py 的差一。确定性策略经测试失败消息的正则认出 bug,发修正文件。把策略换成 LLM 不改外壳契约。

本节自包含。每个前节原语在 main.py 里以最小规模重实现(门、沙箱、账本、span),这样本节无需 import 兄弟节。名字与第 25~28 节完全一致,概念映射无歧义。

三、为何策略不是 LLM

真 LLM 需要 API key、网络调用、不可验证的随机性。外壳是本节在乎的部分。替成确定性策略让本节在任意开发者笔记本上零外部依赖运行,让测试套件能断言精确步数。本节策略是 LLM Agent 所做的严格子集:读仓库、看失败测试、认行、发修复。LLM 走同一循环、同一外壳契约,簿记一模一样。

四、可复用产物

main.py 发:最小外壳原语(名字同第 25~28 节:GateChain、Sandbox、ObservationLedger、SpanBuilder、MetricsRegistry)、CodingAgentPolicy(五态状态机)、Repo 助手(备捆绑 buggy 夹具的 scratch 目录)、AgentRun(驱动策略、经外壳派发、返回 AgentRunReport)、捆绑夹具 fixture_repo/(src/fizz.py、tests/test_fizz.py、expected/ 树)。demo 端到端跑策略,打逐步 trace,断言 pass,打指标。夹具形状同第 27 节:buggy 文件 + tests 文件,测试失败消息含够多信息让确定性策略认出修复。

五、demo 断言什么

端到端 demo 在退出时断言五件事,测试套件编程再断言:

• 策略在 12 步内解出夹具。
• 观察预算从未超。
• 对合法工具零门拒绝触发(Agent 从未发明被拒工具名)。
• 每步在 traces.jsonl 里有对应 span。
• Prometheus 呈现含 tools_called_total{tool="read_file"} 条目与 tool_latency_ms 直方图。

cd phases/19-capstone-projects/29-end-to-end-coding-task-demo
python3 code/main.py        # 打逐步 trace + 最终 eval 报告 + Prometheus 呈现
python3 -m pytest code/tests/ -v
​

六、练习

1. 门拒绝路径:让策略发明一个 dangerous_tool 名,确认门链拒绝、span 标 ERROR、Agent 停。
2. 步预算:把全局步预算设 3,确认 Agent 在 SURVEY+RUN_TESTS+INSPECT 后被预算抓住,返回失败。
3. 换 LLM:在策略缝处插一个真模型调用(哪怕 mock),确认契约不变、簿记一致。
4. 观察预算:把观察预算设极小,确认 read_file 触预算、Agent 停。
5. 缝的一致性:故意让沙箱与门链对同一工具判断不一致(门 ALLOW、沙箱拒),确认 span 同时记 ALLOW 与拒绝,可被集成测试抓住。

本节要点回顾

1. 集成测试:门链/沙箱/评估/可观测性合一个系统,缝才显形。
2. 五态状态机:SURVEY/RUN_TESTS/INSPECT/FIX/VERIFY,每态一工具调用经门链。
3. 策略是确定性替身:零外部依赖、可断言精确步数;LLM 在策略缝处插入,契约不变。
4. 双预算:全局步预算 + 观察 token 预算,跨端到端强制。
5. 五断言:< 12 步、观察预算未超、零合法工具门拒绝、每步有 span、Prometheus 含 read_file 条目。
6. 真 Agent 从此延伸:换策略为模型、换夹具为真仓库任务、换 JSONL 为 OTLP。

以上 Agent Harness 深度构建赛道十节完成。下一节起,我们进入第三条赛道——「从零构建 GPT」,从 BPE 分词器开始,逐层搭出一个能训练的 GPT。