从一次 LLM 调用，到一个能改代码的 Agent。

如果你已经会调用一次大模型 API，你拥有的是一个“会回答问题的函数”。Coding Agent 要解决的是另一类问题：用户给出一个目标，系统需要反复观察环境、调用工具、解释结果、修正计划、保存进度，并在中途被用户插话、终止或恢复后继续工作

Agent 的第一块地基是 tool calling。很多教程把它讲成“给模型一个函数列表，模型会选择函数”。这句话没有错，但太粗糙。真正需要理解的是：工具调用是一种消息协议。模型并没有直接执行函数，它只是在 assistant 消息里声明

理解了工具协议之后，Agent 的核心就是 loop。它不是 `while true` 地让模型说话，而是由模型返回的 stop reason 驱动状态转移。模型说需要工具，运行时执行工具；模型说完成，运行时结束；模型超长或被中止，运行时把

工具是 Agent 接触外部世界的唯一通道。工具设计不好，模型就会学到错误行为；工具输出不稳定，loop 就难以测试；工具权限过大，安全边界会变成装饰。一个可用的 Coding Agent，工具层要同时服务模型、用户界面、日志和安全策略。

当 Agent 只有一个模型时，你可能会直接把厂商 SDK 的类型传遍整个系统。这样做起步快，但很快会把运行时绑死在某个 provider 的语义上。不同厂商对 tool call、流式 delta、错误、usage、停止原因、系统提示词和

没有流式输出的 Agent 会显得迟钝。用户提交任务后，模型可能先思考数秒，再请求工具，工具又运行数秒。如果界面只在最终结果出现时刷新，用户无法判断系统是在工作、卡住还是已经失败。流式事件不是视觉优化，而是 Agent 的可观察性基础。

到目前为止，你已经有了消息协议、provider、工具和流式事件。下一步是把它们组织成 Agent 内核。内核不是产品界面，也不是某个 provider 的包装器。它的职责是维护运行状态、推进 turn、执行工具、发出事件，并把可定制点暴露

真实用户不会等 Agent 完成后才说话。他们会在模型输出时补充信息，在工具执行时发现方向错了，或者在当前任务快结束时追加下一件事。Agent 需要区分三类输入：停止、插话和后续任务。把它们都当成新的 user prompt，会破坏运行时状

Agent 运行时的事实源应该是会话日志，而不是内存里的 messages 数组。内存会丢，UI 会刷新，进程会崩溃，用户会明天回来继续。只要日志足够完整，你就能重建上下文、显示历史、审计工具调用、恢复未完成任务，甚至从某个中间节点分叉。

上下文窗口再大也会被 Agent 用完。Coding Agent 会读文件、跑命令、输出 diff、遇到错误、接收用户插话。真正的问题不是“如何塞更多 token”，而是“如何保留继续工作的必要状态”。压缩是把旧上下文投影成可继续执行的摘要

Coding Agent 和普通工具 Agent 的差异，集中体现在写操作。读文件和搜索让模型观察世界；`edit`、`write`、`bash` 让模型改变世界并验证结果。这里的风险也最高：误改文件、覆盖用户改动、执行危险命令、输出过长、

工具和 loop 决定 Agent 能做什么，系统提示词决定它应该怎样做。Coding Agent 的系统提示词不是一段“你是一个有用助手”。它要把项目规则、工具使用纪律、安全要求、输出风格和当前运行模式组合起来。组合顺序和冲突处理会直接影

Coding Agent 能读写文件、运行命令、访问网络和调用模型。只要它运行在你的机器上，它就拥有进程权限范围内的能力。安全设计的第一步是诚实：不要把 prompt 当权限系统，不要把“模型应该不会这么做”当隔离边界。

Agent 内核完成后，你会想加更多入口：交互式 CLI、一次性 print 模式、JSON 事件模式、SDK、RPC、TUI。不要为每个入口写一套 Agent。所有运行壳都应该订阅同一个内核事件流，只在输入输出协议上不同。

当 Agent 开始被不同团队使用，你会不断收到定制需求：加一个内部搜索工具，拦截危险命令，改系统提示词，给状态栏显示 token 成本，保存任务完成后的报告。把这些需求都合并进核心代码，会让内核膨胀。扩展系统的目标是把可定制点产品化。

Agent 开发最大的错觉是“刚才那次看起来能跑，所以它是对的”。模型输出不稳定，真实仓库复杂，工具和上下文状态很多。如果没有评测和调试体系，你会在每次改 prompt 或工具描述后重新手工试一遍，而且无法判断退化来自哪里。