用 Go 造一个 Agent 运行时：全系列 51 章目录

本文是《从 0 写 Agent》系列的总目录：51 章 + 4 篇附录已全部上线，每章独立可读，案例代码基于开源项目 agents-go。

一个 51 章、4 篇附录的系列，从一个最简循环开始，一步步带你造出一个能跑进生产的 Agent 运行时。

案例代码基于开源项目 agents-go（OpenAI Agents SDK 的 Go 移植版，约 9000 行核心代码 + 6 个子包 + 一个完整的单二进制 Agent 平台）。

这本系列是写给谁的

写给所有想真正理解 AI Agent 的开发者，不满足于"会调用框架"，想知道框架内部到底怎么转的人。

• 你用过 LangChain / CrewAI / Claude Code，但说不出"Agent 循环"具体是什么
• 你想自己写一个 Agent，却不知道从哪里下手
• 你是 Go 开发者，被 Python 绑架得不舒服，想看 Go 能做到什么程度
• 你做架构，需要判断一个 Agent 系统能不能进生产

原理部分语言无关（用伪代码和大白话讲），实现部分用 Go（agents-go 源码为案例）。不写 Go 的人也能读懂原理，写 Go 的人能照着实现。

为什么"从 0 写"而不是"学框架"

直接学框架有三个问题：

1. 框架把核心藏起来了。 LangChain 用 agent.invoke() 一行搞定所有事，但你不知道这一行里发生了什么，循环怎么转、工具怎么调、错误怎么处理、状态怎么恢复。
2. 框架的设计取舍你看不见。 为什么 Claude Code 的上下文到 30 万 token 要开新会话？为什么 OpenAI 的 SDK 要把 Agent 当工具用？这些决策背后的理由，框架文档不会讲。
3. 框架出问题你修不了。 当 Agent 在生产环境卡住、死循环、状态丢失，你只能祈祷框架作者修，自己看不懂代码。

从 0 写一遍，这些问题全消失。 因为每一行都是你自己写的，每一个决策都是你自己做的，每一个 bug 你都能定位。

这不是让你真去生产环境重造轮子，而是，理解了运行时，你才能真正用好任何框架。

为什么选 Go

Agent 框架几乎是 Python 的天下（LangChain、AutoGen、CrewAI、openai-agents-python）。但 Go 有三个对 Agent 运行时特别友好的特性：

• 并发模型天然适合多工具并行，goroutine + channel，Agent 同时调多个工具几乎零成本；Python 要 asyncio async/await 满天飞
• 强类型让状态流转清晰，编译期就检查工具参数类型；Python 靠运行时炸
• 单二进制部署，编译出一个文件，扔到任何机器就跑；Python 要管虚拟环境、依赖、打包

agents-go 这个项目证明了一件事，Go 做 Agent 不但不吃亏，在生产部署上还有真实优势。 它把 OpenAI 的 Python Agents SDK 用地道的 Go API 重新实现了一遍，行为对齐，9000 行核心代码，单二进制跑起一个完整 Agent 平台。

系列地图

全部章节（51 章 + 4 附录）

Part I · 最小可用 Agent

• 第1章 Agent 到底在循环什么：30 行代码看穿运行时
• 第2章 屏蔽一切大模型差异：Model 接口抽象
• 第3章 Tool 设计：让 Agent 真正“干活”
• 第4章 一次工具调用的完整生命周期
• 第5章 并发跑工具，Go 的天然优势
• 第6章 从阻塞到事件流：流式输出怎么做
• 第7章 七章走完，你有了一个能跑的 Agent 内核

Part II · 状态记忆与控制

• 第8章 让 Agent 记住对话：Session 接口设计
• 第9章 崩溃安全的会话持久化：JSONL 方案
• 第10章 会话进数据库：SQLite 与 Postgres 后端
• 第11章 会话分叉与压缩：上下文装不下了怎么办
• 第12章 让人来审批工具调用：HITL 怎么做
• 第13章 RunState：跨进程审批的序列化
• 第14章 输入输出都要有安全护栏：Guardrails

Part III · 多 Agent 协作

• 第15章 Agent 之间的交接棒：Handoff 模式
• 第16章 交接之后历史怎么算：双列表与 InputFilter
• 第17章 折叠长对话，别让摘要的摘要爆炸
• 第18章 把 Agent 当工具用：嵌套调用
• 第19章 运行时的事件钩子：Lifecycle Hooks
• 第20章 多 Agent 的拓扑，以及怎么权衡

Part IV · 模型工程与可观测

• 第21章 模型工厂与路由：ModelProvider
• 第22章 重试别只加 sleep：指数退避与 equal jitter
• 第23章 主模型挂了怎么办：模型降级链
• 第24章 三个装饰器，任意组合出韧性
• 第25章 从 0 造一套 Agent 可观测系统
• 第26章 异步流水线工程：BatchProcessor
• 第27章 把 trace 送出去：Exporter 的活儿

Part V · 工具生态

• 第28章 连接外部工具的统一标准：MCP 协议
• 第29章 OAuth、多模态、错误策略：MCP 进阶三件事
• 第30章 渐进式披露：Skills 怎么组织 Agent 能力
• 第31章 目录囚禁：Go 1.24 的 os.Root
• 第32章 让 Agent 跑不可信代码：Sandbox 抽象
• 第33章 Docker 沙箱纵深防御，一张清单

Part VI · 完整应用

• 第34章 单二进制 Agent 平台：agents-server 总览
• 第35章 数据库怎么设计：10 张表与 JSON 扩展列
• 第36章 WebSocket 流式的三层架构
• 第37章 HITL 审批：从请求到放行的端到端实现
• 第38章 go:embed：零构建前端打进单二进制
• 第39章 ChatGPT OAuth：让订阅额度跑自建 Agent

Part VII · 结语

• 第40章 40 章走完，你已经能从 0 写 Agent 了

Part VIII · 原理深化

• 第41章 Agent 为什么有效：ReAct 的认知科学基础
• 第42章 给不确定性加边界：概率性系统工程哲学
• 第43章 LLM 当大脑：凭什么做 Agent 的决策核心
• 第44章 评估难题：怎么知道 Agent 好不好

Part IX · 实战案例

• 第45章 实战一：从 0 写一个客服 Agent
• 第46章 DataAgent：让 Agent 替你跑数据分析
• 第47章 实战三：写一个代码助手 Agent
• 第48章 实战四：搭一个多 Agent 客服中心
• 第49章 实战五：公司内部 AI 平台长什么样

Part X · 对比与选型

• 第50章 agents-go 对比 LangChain：两种框架哲学
• 第51章 Agent 框架选型指南：一张决策清单

附录

• 附录：agents-go 源码地图
• 从教学项目到生产环境，还差这几步
• 附录：写 Agent 最常踩的坑
• 附录：Agent 运行时术语表

三条阅读路径

路径 A：完整系统学习（推荐），从第 1 章顺序读到第 51 章，相当于一本技术书的体量。

路径 B：只想理解 Agent 循环，读 Part 0 + Part I（第1-7章），2 万多字。读完你就知道 Agent 内核是什么。

路径 C：带着具体问题跳读，

• 想懂多 Agent → 直接看 Part III
• 想懂可观测性 → 直接看 Part IV 第 25-27 章
• 想懂 MCP/沙箱 → 直接看 Part V
• 想懂完整平台 → 直接看 Part VI

每章独立可读，跳读时章首有足够的上下文回顾。

每章怎么写

固定的五个模块：

1. 引子，一个痛点或场景，告诉你这章要解决什么
2. 原理，语言无关地讲"为什么这样设计"，配简化教学代码
3. 源码对照，agents-go 怎么实现的，关键片段 + 文件:行号 + 注释
4. 设计权衡，这样做的代价是什么、有什么坑、有什么替代方案
5. 小结，这章你学会了什么 + 下一篇预告

关于代码版本

agents-go 基于 openai-agents-python v0.17.4 的 Go 移植，MIT 协议。引用的源码片段基于本系列写作时的版本，行号可能随上游更新变化，遇到对不上的，按函数名/类型名去仓库里搜，别死扣行号。

源码仓库：https://github.com/zzir/agents-go

---

好了，准备工作做完。翻到第 1 章，我们从一个 30 行的循环开始。

---

系列仍在更新，本文目录随章节上线同步维护。agents-go 仓库：https://github.com/zzir/agents-go （Go，2026-06 创建）。