Agent 工程教程
从一次 LLM 调用，到一个能改代码的 Agent。
本书参考 Pi Agent 的架构设计，把成熟系统里的协议层、运行时、会话日志、工具、安全边界和扩展机制，拆成可以逐章实现的工程知识。
源自真实系统
内容提炼自 Pi 这样真实运行的 coding agent 的分层架构，讲的是经过验证的通用设计。
每章有检查点
每章都回答一个具体工程问题，并给出读者能验证的输出或状态。
以失败模式驱动
先看朴素做法哪里会坏，再引入协议、日志、压缩、权限和扩展边界。
目录
一条从协议到产品化的学习路径。
如果你已经会调用一次大模型 API，你拥有的是一个“会回答问题的函数”。Coding Agent 要解决的是另一类问题：用户给出一个目标，系统需要反复观察环境、调用工具、解释结果、修正计划、保存进度，并在中途被用户插话…
01 一次工具调用的完整协议Agent 的第一块地基是 tool calling。很多教程把它讲成“给模型一个函数列表，模型会选择函数”。这句话没有错，但太粗糙。真正需要理解的是：工具调用是一种消息协议。模型并没有直接执行函数，它只是在…
02 最小 Agent Loop理解了工具协议之后，Agent 的核心就是 loop。它不是 while true 地让模型说话，而是由模型返回的 stop reason…
03 工具设计基础工具是 Agent 接触外部世界的唯一通道。工具设计不好，模型就会学到错误行为；工具输出不稳定，loop 就难以测试；工具权限过大，安全边界会变成装饰。一个可用的 Coding…
04 Provider 抽象与统一消息协议当 Agent 只有一个模型时，你可能会直接把厂商 SDK 的类型传遍整个系统。这样做起步快，但很快会把运行时绑死在某个 provider 的语义上。不同厂商对 tool call、流式…
05 流式输出与事件模型没有流式输出的 Agent 会显得迟钝。用户提交任务后，模型可能先思考数秒，再请求工具，工具又运行数秒。如果界面只在最终结果出现时刷新，用户无法判断系统是在工作、卡住还是已经失败。流式事件不是视觉优化，而是 Agent…
06 Agent 内核与生命周期到目前为止，你已经有了消息协议、provider、工具和流式事件。下一步是把它们组织成 Agent 内核。内核不是产品界面，也不是某个 provider 的包装器。它的职责是维护运行状态、推进…
07 中断、插话与后续任务真实用户不会等 Agent 完成后才说话。他们会在模型输出时补充信息，在工具执行时发现方向错了，或者在当前任务快结束时追加下一件事。Agent 需要区分三类输入：停止、插话和后续任务。把它们都当成新的 user…
08 会话日志与恢复Agent 运行时的事实源应该是会话日志，而不是内存里的 messages 数组。内存会丢，UI 会刷新，进程会崩溃，用户会明天回来继续。只要日志足够完整，你就能重建上下文、显示历史、审计工具调用、恢复未完成任务，甚至从…
09 上下文工程与压缩上下文窗口再大也会被 Agent 用完。Coding Agent 会读文件、跑命令、输出 diff、遇到错误、接收用户插话。真正的问题不是“如何塞更多…
10 Coding 工具：read、edit、write、bashCoding Agent 和普通工具 Agent 的差异，集中体现在写操作。读文件和搜索让模型观察世界；edit、write、bash…
11 系统提示词与项目上下文工具和 loop 决定 Agent 能做什么，系统提示词决定它应该怎样做。Coding Agent 的系统提示词不是一段“你是一个有用助手”。它要把项目规则、工具使用纪律、安全要求、输出风格和当前运行模式组合起来。组合顺…
12 安全边界与权限模型Coding Agent 能读写文件、运行命令、访问网络和调用模型。只要它运行在你的机器上，它就拥有进程权限范围内的能力。安全设计的第一步是诚实：不要把 prompt 当权限系统，不要把“模型应该不会这么做”当隔离边界。
13 一份内核，多种运行壳Agent 内核完成后，你会想加更多入口：交互式 CLI、一次性 print 模式、JSON 事件模式、SDK、RPC、TUI。不要为每个入口写一套…
14 扩展系统当 Agent 开始被不同团队使用，你会不断收到定制需求：加一个内部搜索工具，拦截危险命令，改系统提示词，给状态栏显示 token 成本，保存任务完成后的报告。把这些需求都合并进核心代码，会让内核膨胀。扩展系统的目标是把…
15 评测、调试与最终项目Agent 开发最大的错觉是“刚才那次看起来能跑，所以它是对的”。模型输出不稳定，真实仓库复杂，工具和上下文状态很多。如果没有评测和调试体系，你会在每次改 prompt…