从并发基础到生产上线：一份能跑、能测、每天更新的 AI Agent 工程师学习路线。
用 Go / TypeScript 写 Agent 运行时，用 Python 读懂模型生态。
每一课都有课件、可运行练习、测试和参考答案。
市面上的 Agent 教程大多停在“调一下 API、套一个框架”。真正把 Agent 做进生产，难点在别处：
- 用户关掉页面，上游模型调用和工具有没有真的停下来？
- 三个工具并行，一个卡住 5 秒，整轮会不会被拖死？
- 模型给的 JSON 参数是错的，程序崩溃还是把错误回传给模型自我修正？
- 怎么证明 Agent“做完了”，而不是“说做完了”？
这个仓库按工程师的视角，把这些问题拆成 84 个知识点、14 个模块，外加一条贯穿全程的主线项目，每个知识点都要求有代码、有测试、能跑通才算完成。
| 代码先行 | 每课配一个可运行目录，go test -race / vitest / pytest 全绿才勾选 |
| 三语对照 | 同一个问题（并行工具、超时、取消、流式）分别用 Go、TS、Python 实现并对比 |
| 逐行讲解 | 课件里每段核心代码后都有逐行解读、设计取舍和常见坑 |
| 附参考答案 | 每课都有练习、自测题、参考实现和详细解释 |
| 公开进度 | 每天一份日志，ROADMAP 勾选即进度，主页同步展示 |
| # | 主题 | 核心内容 | 课件 | 练习 | 状态 |
|---|---|---|---|---|---|
| 0.1 | Go 基础与并发 | 模块、错误处理、接口、JSON、表驱动测试；goroutine、channel、context、errgroup、可取消 SSE | 课件 | 00-stream-proxy |
✅ 完成 |
| 0.2 | TypeScript | 可辨识联合、Zod、AsyncGenerator、AbortController | 课件 | 01-ts-agent-core |
✅ 完成 |
| 0.3 | Python | uv、Pydantic、asyncio TaskGroup、异步生成器 | 课件 | 02-py-agent-core |
✅ 完成 |
| 0.4 | 流式协议 | HTTP 分块与 Flush、SSE 解析器、断线续传、中间层缓冲、WebSocket 双向打断 | 课件 | 03-streaming |
✅ 完成 |
| 0.5 | 工程基础 | Git 工作流、Linux 信号与排查、多阶段 Docker、健康检查、优雅退出、CI | 课件 | 04-ship |
✅ 完成 |
| 0.6 | 数据库与缓存 | Postgres 建模、索引与键集分页、隔离级别与写偏斜、幂等键、SKIP LOCKED 队列、迁移；Redis 缓存与限流 | 课件 | 05-store |
✅ 完成 |
| # | 主题 | 核心内容 | 课件 | 练习 | 状态 |
|---|---|---|---|---|---|
| 1.1 | Transformer、Tokenizer、采样 | 字节级 BPE、流式 UTF-8 解码、注意力与因果掩码、KV Cache、temperature / top-p / min-p / 惩罚、API 采样参数现状 | 课件 | 06-llm-basics |
✅ 完成 |
| 1.2 | 主流模型 API | OpenAI Responses、Anthropic Messages、Gemini Interactions 的消息结构、工具调用、流式事件、用量口径；推理块回传；同家无损、跨家降级的 Go 统一客户端与工具循环 | 课件 | 07-llm-api |
✅ 完成 |
| 1.3 | 结构化输出 | 提示词 / JSON mode / strict 三个层次；约束解码原理与手写前缀检查器；分布扭曲与字段顺序；三家 schema 子集、规则检查与转换；校验驱动的重试循环 | 课件 | 08-structured-output |
✅ 完成 |
| 1.4 | 推理模型 | 推理 token 的四个特点；三家 effort / thinking / thinking_level 的写法与 400 组合；用量口径与两种截断；思考块签名绑定模型与前缀、只追加不修改；逐级升级、多数投票与“每个正确答案的 token” | 课件 | 09-reasoning |
✅ 完成 |
| 1.5 | Prompt Caching | KV 前缀复用与累计哈希；Anthropic 自动缓存 / 显式断点 / 20 块回看、OpenAI implicit 与 explicit、Gemini 隐式与 cachedContents；读写倍率统一、最小长度盈亏平衡、TTL 选择；按变化频率放断点、只追加不修改、分叉诊断 | 课件 | 10-prompt-cache |
✅ 完成 |
| 1.6 | 上下文工程 | 什么算进窗口与超窗口的两种结果；长度退化与位置效应、全塞与检索的取舍；预算内组装、去重、稳定在前、工具输出保留头尾；清理 / 笔记 / 压缩与缓存的权衡；提示词结构与回归评测 | 课件 | 11-context |
✅ 完成 |
| # | 主题 | 核心内容 | 课件 | 练习 | 状态 |
|---|---|---|---|---|---|
| 2.1 | Function Calling / Tool Use | 五步流程；两家的定义、调用与结果格式（arguments 字符串 vs input 对象、call_id vs tool_use_id）；strict 与 tool_choice；并行调用的回传规则；只读并发、去重、副作用串行失败即停；错误变结果；流式参数按 index 拼接；工具设计 | 课件 | 12-tools |
✅ 完成 |
| 2.2 | MCP（Model Context Protocol） | Host / Client / Server 与 Function Calling 的分工；Tools / Resources / Prompts 由谁控制；2026-07-28 无状态设计（每请求 _meta、server/discover、显式句柄）；协议错误 vs 工具执行错误；多轮请求与 requestState 签名；stdio 与 Streamable HTTP（镜像头、Origin）；多 Server 聚合与安全 |
课件 | 13-mcp |
✅ 完成 |
| 2.3 | A2A（Agent-to-Agent）协议 | 与 MCP、Function Calling 的分层；Agent Card 发现与接口选择；任务状态机（终态 / 中断态）；contextId 与 taskId 规则、input-required 多轮；messageId 幂等；阻塞、returnImmediately、SSE 流、推送；版本头；把远程 Agent 包装成工具 | 课件 | 14-a2a |
✅ 完成 |
| 2.4 | Computer Use / Browser Use 代理 | API、可访问性树、截图坐标、代码执行四条路线的取舍；三家接口（Anthropic 工具集、OpenAI computer_call、Gemini computer_use）；截图缩放与坐标换算；批量动作顺序执行与中止；每个动作执行前检查（布局移动）；网址白名单与隐藏文字注入；元素引用生命周期；截图历史修剪与缓存；步数上限与结果核验 | 课件 | 15-computer-use |
✅ 完成 |
| 2.5 | Code Execution 沙箱（E2B、Docker、gVisor） | 三家自带代码执行（Anthropic code_execution、OpenAI code_interpreter、Gemini code_execution）与 E2B 的取舍；威胁模型；进程、容器、gVisor、微虚拟机四层隔离；加固 docker run 与危险参数；出站白名单规则；进程组超时、环境变量白名单、CPU / 文件大小限制与 set -e；输出保留头尾、产物只收普通文件；代码错误与环境失败分开回给模型；沙箱续期、暂停与销毁 | 课件 | 16-sandbox |
✅ 完成 |
| # | 主题 | 核心内容 | 课件 | 练习 | 状态 |
|---|---|---|---|---|---|
| 3.1 | ReAct、Plan-and-Execute、Reflexion | Workflow 与 Agent 的区分；ReAct 循环（取消、调用与结果配对、工具错误变观察、步数上限）与文本格式的坑；Plan-and-Solve、ReWOO 的 #E 引用、LLMCompiler 并行；计划校验、按依赖分波、失败重规划不重跑；Reflexion 的反思记忆与评估信号；三种模式的取舍与组合 | 课件 | 17-patterns |
✅ 完成 |
| 3.2 | Agent Loop 设计：停止条件、预算、重试 | Anthropic stop_reason 与 OpenAI incomplete_details 归一成 7 种；截断续写与半截工具调用、pause_turn 原样发回、拒绝与窗口满；步数 / 工具次数 / token / 费用 / 墙钟五维预算、整数计费、收尾调用；可重试错误分类与额度类 429、全抖动退避、retry-after 下限、总等待上限、SDK 重试叠加；工具超时 | 课件 | 18-loop |
✅ 完成 |
| 3.3 | 多智能体：Supervisor、Handoff、Swarm | 何时值得用多智能体（约 15 倍 token、Anthropic 研究系统 +90.2%）；agents as tools：上下文隔离、任务描述四要素、禁止转交、嵌套深度、并行子 agent；Handoff：transfer_to_ 工具、历史过滤 remove_all_tools、只认第一个转交、来回转交上限；Swarm 活跃 agent 跨轮保留；共享预算与按 agent 记账 | 课件 | 19-multiagent |
✅ 完成 |
| 3.4 | 长任务 Agent：检查点、可恢复执行、Human-in-the-loop | 三种“长”：进程崩溃、等人、跨上下文窗口；检查点存什么、何时存、seq 乐观锁与认领；三个崩溃时刻与账本 + 幂等键；LangGraph interrupt / OpenAI needs_approval + RunState / Genkit Go 1.14 可恢复工具；fail closed、拒绝即工具结果、部分决定、过期按拒绝、版本；Anthropic 进度文件 + JSON 功能清单 | 课件 | 20-longrun |
📖 学习中 |
| 3.5 | Agent 状态与数据模型：会话、消息、run、step、工具调用，事件溯源与完整重放 | 消息数组、快照、事件日志三种存法；会话 / run / step / 工具调用 / 消息的划分，消息由事件推出（加密 reasoning 例外）；只追加事件流与 expect 乐观锁、UNIQUE(run_id, seq)；tool_started / tool_finished 与幂等键；投影、全局位置追赶、读自己的写；快照即缓存；upcasting 读时升级；录像替身完整重放与请求指纹分叉检测，对比 LangGraph replay；OpenAI Conversations / previous_response_id / store:false 与 LangGraph checkpoints + writes、DeltaChannel；Postgres 表结构与删除策略 | 课件 | 21-state |
📖 学习中 |
| 3.6 | Coding Agent 架构（Claude Code / Codex / SWE-agent 拆解） | agentic harness：收集上下文、行动、验证；Claude Code 五类工具、Edit 三条检查、每命令独立进程、文件检查点、权限模式、按需加载；Codex 的 instructions / tools / input、AGENTS.md 分层 32 KiB、只沙箱 shell、无状态与 ZDR、精确前缀与 cache miss、追加而非修改、compaction；SWE-agent ACI 与消融（100 行窗口、50 条上限、linter、最近 5 条观察）；mini-swe-agent 只用 bash 的反转；编辑格式取舍、权限判断顺序、折叠与缓存冲突、harness 强制验证 | 课件 | 22-coding |
📖 学习中 |
| 3.7 | Deep Research Agent 架构 | 静态检索 vs 多步动态搜索；Anthropic Research：主研究员 + 并行子代理 + CitationAgent、计划存 Memory、token 用量解释 80% 差异、按复杂度分配预算、先宽后窄、LLM 评委五项细则、断点恢复与彩虹部署；OpenAI 专用模型 2026-07-23 关闭，现用推理模型 + web_search + 后台模式；Gemini Deep Research agent：后台执行、流式续传、协作式计划；压缩与工件引用、缺口驱动迭代、引用核对、注入隔离 | 课件 | 23-research |
📖 学习中 |
| # | 主题 | 核心内容 | 课件 | 练习 | 状态 |
|---|---|---|---|---|---|
| 4.1 | LangGraph（状态图、持久化、interrupt） | 通道与 reducer（覆盖、追加、add_messages、Overwrite）；节点、静态边、条件边、Send 扇出、Command；Pregel super-step（并行看同一快照、步末合并、LastValue 冲突、递归上限）；checkpointer 与 store、每步一个 checkpoint、pending writes、四种继续方式、三种 durability 与首个 checkpoint；interrupt 的抛出 + 从头重跑 + 按序号匹配及四条规则、按 ID 恢复多个 interrupt；time travel、update_state、图迁移；节点 / task / 子图的划分 | 课件 | 24-langgraph |
📖 学习中 |
四个阶段：A 打地基 → B 能做出来 → C 上生产 → D 深入与实战。阶段 C 是 Demo 和生产系统的分水岭：Eval 回答“有多准”，Tracing 回答“哪里坏了”，高可用回答“挂了怎么办”，性能与成本回答“为什么慢、为什么贵”。
| 阶段 | 模块 | 内容 | 进度 |
|---|---|---|---|
| A | 00 基础功底 | Go / TS / Python、流式协议、工程基础、数据库与缓存 | ██████ 6/6 |
| A | 01 LLM 原理与使用 | Transformer、主流 API、结构化输出、推理模型、Prompt Caching | ██████ 6/6 |
| A | 02 工具调用与协议 | Function Calling、MCP、A2A、Computer Use、代码沙箱 | █████ 5/5 |
| B | 03 Agent 架构 | ReAct、Agent Loop、多智能体、长任务、状态与数据模型、Coding / Deep Research Agent | ███░░░░ 3/7 |
| B | 04 框架与 SDK | LangGraph、OpenAI / Claude Agent SDK、Eino、Vercel AI SDK、Mastra | ░░░░░░ 0/6（4.1 学习中） |
| B | 05 记忆与检索 | 向量库、混合检索、Rerank、GraphRAG、记忆、检索评测 | ░░░░░ 0/5 |
| C | 06 评测体系 | 测试工程、任务集构造、pass^k、LLM-as-Judge 校准、SWE-bench / τ²-bench、CI 门禁、模型版本迁移、A/B | ░░░░░░░░░ 0/9 |
| C | 07 可观测性 | OpenTelemetry GenAI、Langfuse、TTFT / P99 / 成本指标、会话回放、SLO | ░░░░░ 0/5 |
| C | 08 高可用与可靠性 | 超时重试幂等、熔断限流、多供应商容灾、Temporal 断点恢复、后台任务、故障演练 | ░░░░░░░ 0/7 |
| C | 09 高性能与成本 | 首 token 延迟、缓存、压测与 pprof、vLLM / SGLang、模型路由、成本治理 | ░░░░░░ 0/6 |
| C | 10 安全与治理 | Prompt Injection、权限沙箱、身份凭证与多租户、Guardrails、Reward Hacking、PII 与审计、内容安全合规 | ░░░░░░░ 0/7 |
| C | 11 工程化与部署 | Go / Node 服务、流式前端、模型网关、K8s、Prompt 版本化、灰度回滚 | ░░░░░░ 0/6 |
| D | 12 模型侧前沿 | LoRA、DPO / GRPO、Agentic RL、合成数据、量化部署 | ░░░░ 0/4 |
| D | 13 项目实战 | MCP 助理、生产级 RAG、Coding Agent、高可用网关、上线运营 | ░░░░░ 0/5 |
主线项目 agent-platform：以 0.5 的 04-ship 为起点，每个模块结束时给同一个系统加一层（模型接入 → 工具 → Agent Loop → RAG → Eval → Tracing → 容灾 → 压测 → 安全 → 上线），最后真实部署并写事故复盘。详见 ROADMAP。
完整清单和生产就绪检查清单见 ROADMAP.md。
git clone https://github.com/Duang777/ai-agent-fullstack-roadmap.git
cd ai-agent-fullstack-roadmap运行任意一课的练习：
# 0.1 Go
cd projects/00-stream-proxy && go test -race -count=1 ./...
# 0.2 TypeScript
cd projects/01-ts-agent-core && npm install && npm run typecheck && npm test
# 0.4 流式协议
cd projects/02-py-agent-core && uv sync && uv run pytest -q # 0.3 Python
cd projects/03-streaming && npm install && npm run typecheck && npm test
# 0.5 工程基础
cd projects/04-ship && make test # 有 Docker 的话再 make docker-build docker-run
# 0.6 数据库与缓存（需要 Docker 起 Postgres + Redis）
cd projects/05-store && make up && make test
# 1.1 Transformer、Tokenizer、采样
cd projects/06-llm-basics && make test # make tokens 用 tiktoken 对比真实分词器
# 1.2 主流模型 API
cd projects/07-llm-api && make test # go run ./cmd/chat -p anthropic -m <模型> "..." 用真实 Key 试
# 1.3 结构化输出
cd projects/08-structured-output && make test
# 1.4 推理模型
cd projects/09-reasoning && make test
# 1.5 Prompt Caching
cd projects/10-prompt-cache && make test
# 1.6 上下文工程
cd projects/11-context && make test
# 2.1 Function Calling
cd projects/12-tools && make test
# 2.2 MCP
cd projects/13-mcp && make test
# 2.3 A2A
cd projects/14-a2a && make test
# 2.4 Computer Use
cd projects/15-computer-use && make test
# 2.5 代码执行沙箱
cd projects/16-sandbox && make test
# 3.1 ReAct / Plan-and-Execute / Reflexion
cd projects/17-patterns && make test
# 3.2 Agent Loop：停止条件、预算、重试
cd projects/18-loop && make test
# 3.3 多智能体：Supervisor、Handoff、Swarm
cd projects/19-multiagent && make test
# 3.4 长任务 Agent：检查点、可恢复执行、Human-in-the-loop
cd projects/20-longrun && make test
# 3.5 Agent 状态与数据模型：事件溯源与完整重放
cd projects/21-state && make test
# 3.6 Coding Agent 架构：拆解 Claude Code、Codex、SWE-agent
cd projects/22-coding && make test
# 3.7 Deep Research Agent 架构：拆解 Anthropic Research、OpenAI、Gemini
cd projects/23-research && make test
# 4.1 LangGraph：状态图、持久化与 interrupt（Go 重写运行时核心）
cd projects/24-langgraph && make test推荐学习方式：先读课件 → 关掉参考答案自己写练习 → 跑测试 → 再对照参考实现。
.
├── ROADMAP.md # 84 个知识点 + 主线项目 + 生产就绪检查清单
├── notes/ # 课件，按模块分目录
│ └── 00-foundations/
│ ├── 01-go.md
│ ├── 02-typescript.md
│ ├── 03-python.md
│ ├── 04-streaming.md
│ ├── 05-engineering.md
│ └── 06-database-cache.md
├── projects/ # 每课一个可运行的练习目录
│ ├── 00-stream-proxy/ # Go：fanIn、并行工具、可取消 SSE
│ ├── 01-ts-agent-core/ # TS：Zod 事件、可取消 sleep、并行工具、SSE
│ ├── 02-py-agent-core/ # Python：Pydantic 事件、TaskGroup 并行工具、SSE
│ ├── 03-streaming/ # TS：SSE 解析器、SSE 服务端、续传与断开即停
│ ├── 04-ship/ # Go：健康检查、优雅退出、多阶段 Dockerfile
│ └── 05-store/ # Go：Postgres 会话/消息/任务队列、迁移、Redis 缓存与限流
├── .github/workflows/ci.yml # 每次 push：Go -race（含 Postgres/Redis 集成测试）、TS、Python、镜像冒烟测试
├── logs/ # 每日学习日志
└── docs/ # GitHub Pages 主页
为什么学这个 → 核心概念（Go / TS / Python 对照） → 逐行讲解的代码
→ 常见坑 → 练习 → 自测题 → 参考答案与详解
- 觉得有用，点个 Star 方便追更，每天都会有新内容。
- 发现错误或有更好的写法，欢迎提 Issue 或 PR。
- 想一起打卡：Fork 这个仓库，用
logs/TEMPLATE.md写你自己的日志。
- 代码（
projects/及其他源码）：MIT - 课件与文档（
notes/、logs/、ROADMAP.md）：CC BY-NC-SA 4.0，转载请注明出处，禁止商用，改编需以相同协议共享
由 @duang777 持续更新