系统学习 AI Agent
一套结合基础理论、源码精读、可运行代码 的完整学习路径，贯通 LangChain、LangGraph 两大框架，并以 OpenCode 这个生产级开源 Agent 产品落地实践。
每一章都遵循 四个递进层次：
- 基础理论 —— 用图解讲清概念（不依赖任何库）
- 源码精读 —— 标注
文件路径:行号，直接对照真实源码 - 可运行代码 —— 完整可复制的示例，本地就能跑
- 生产对照 —— 把框架概念和 OpenCode 的工业级实现两两对照
建议严格按顺序学习：先理论打地基，再 LangChain 学积木，再用 LangGraph 把积木拼成有状态的 Agent，最后用 OpenCode 看真实产品怎么做。
建立统一术语和心智模型。这 3 章不依赖任何框架，但为后面所有源码学习提供"锚点"。
什么是 Agent
从 LLM 到 Agent 的演进；Agent 的三个核心能力；与普通 LLM 应用的本质区别。
🧠LLM 调用解剖
Token、Prompt、Context Window、工具调用（function calling）的底层原理与时序。
🔁Agent 循环理论 ★
ReAct 范式、思考-行动-观察循环、状态机三阶段模型。这是贯穿全教程的核心图。
系统学习 LangChain 的积木式组件。按依赖链组织：
消息 → 提示 → 模型 → 解析 → LCEL → 工具 → Schema → Agent。
源码精读 libs/core/langchain_core/。
消息体系
BaseMessage 及 Human/AI/System/Tool 五种消息类型，tool_calls 字段的意义。
📝提示词模板
ChatPromptTemplate.from_messages、MessagesPlaceholder 注入历史消息。
🔌语言模型抽象
BaseChatModel、bind_tools（工具调用）、with_structured_output（结构化输出）。
🔧输出解析器
BaseOutputParser、StrOutputParser、PydanticOutputParser 把 LLM 输出变结构化数据。
⚙️LCEL 核心原理 ★
Runnable 抽象、管道 | 组合、RunnablePassthrough——LangChain 的灵魂转折章。
🛠️工具体系
BaseTool、@tool 装饰器，把普通函数变成 LLM 可调用的工具。
📐Agent 数据模型
AgentAction / AgentFinish / AgentStep，两态判定的 Agent 循环 Schema。
🎯Agent 实战 ★
create_tool_calling_agent + AgentExecutor，把前 7 章串成可运行 Agent。
把 LangChain 的积木升级为有状态、可循环、可中断、可恢复的图。
源码精读 libs/langgraph/langgraph/。引擎部分讲到概念入门级。
StateGraph 基础 ★
add_node / add_edge / compile，5 行代码定义一个状态图。LangGraph 入门第一课。
🔄状态与 Reducer
Annotated[T, reducer]、add_messages、状态如何被聚合；通道概念入门。
🔀条件边与 Send
add_conditional_edges 动态路由；Send 实现 map-reduce 并行扇出。
📜Functional API
@entrypoint / @task 装饰器，命令式写法也能享受图的能力。
⚙️Pregel 引擎概念 ★
BSP 三阶段模型、Channel 通道机制、StateGraph 如何编译成 Pregel（概念入门级）。
💾检查点与人在回路
Checkpointer 持久化、interrupt 中断、Command 恢复——让 Agent 可被打断和接管。
📡流式输出
7 种 StreamMode、StreamWriter 自定义流，实时呈现 Agent 思考过程。
🏗️预构建 Agent ★
create_react_agent + ToolNode，一行代码得到完整的 ReAct Agent。
拆解一个真实开源的生产级 AI 编码 Agent 产品，看工业界如何把理论落地。 TypeScript 实现，重点呈现「概念对照」与「工程实践拆解」双价值。
整体架构
Agent 循环数据流全景：从用户输入到 LLM 调用到工具执行到返回的完整链路。
🔁runLoop 主循环 ★
逐段拆解 prompt.ts:1081 的 while(true) 循环，对照 Agent 循环理论图。
🛠️工具系统
Tool.define 统一工具模式、registry 动态加载，从 46 行的 todo.ts 起步。
🔐权限系统
三层权限合并（默认/配置/用户）、ctx.ask 人在回路、doom_loop 防死循环。
🧩上下文工程
compaction 上下文压缩、子 Agent 派生、system prompt 动态注入等工程实践。
🗺️概念对照表 ★
大表格：LangGraph 节点循环 ↔ runLoop、Checkpointer ↔ Session 持久化……
从"会用框架"走向"精通原理与生产工程"。这一阶段逐行精读源码 + 接近生产的复杂实战， 覆盖四大进阶主题：多 Agent 协作、高级 RAG、记忆系统、可观测与生产化。
🤝 多 Agent 协作
Supervisor 编排 ★
三种多 Agent 拓扑对比、create_agent 的 middleware 系统、Command.PARENT 父子通信，手写 Supervisor 图。
🌳层级树 + Handoff
层级 Agent 团队、控制权移交 vs 结果回流，精读 OpenCode task 工具派生机制与防递归。
📚 高级 RAG
检索策略 ★
多查询/混合检索 RRF/父子文档/Cross-encoder 重排/MMR，精读四种文档合并策略，构建完整高级 RAG 管道。
🧠Agentic RAG
CRAG/Self-RAG/Adaptive RAG 三种自我反思范式，精读官方 notebook，从零实现 Corrective RAG。
💾 记忆系统深度
短期记忆深度
BaseCheckpointSaver 四方法精读、thread_id 语义、时间旅行调试、状态分支、消息裁剪策略对比。
🧬长期记忆 Store ★
BaseStore + 语义搜索 IndexConfig、namespace 分层、跨会话用户画像记忆，对比 OpenCode 文件式记忆。
🏗️ 可观测 · 评估 · 生产
可观测与追踪
Callbacks 三层体系、LangSmith 集成、stream_mode=debug、OpenTelemetry，自定义 callback 做 token 成本监控。
🛡️容错与韧性 ★
重试/降级/限流/超时/死循环检测，精读 RetryPolicy 与 OpenCode provider 级重试，构建完整容错 Agent。
🌐持久化与部署
PostgresSaver 生产持久化、RemoteGraph 连接 Server、把 Agent 部署成 API 服务，对比 OpenCode server 架构。
✅评估与测试
Agent 为何难评估、EvaluatorCallbackHandler 运行时评估、标准化测试套件、LLM-as-judge 实战。
| 库 | 本地路径 | 语言 | 在本教程中的角色 |
|---|---|---|---|
| langchain | Downloads/langchain-master/ |
Python | 第二阶段系统精读，重点 libs/core/langchain_core/ |
| langgraph | Downloads/langgraph-main/ |
Python | 第三阶段系统精读，重点 libs/langgraph/langgraph/ |
| opencode | Downloads/opencode-dev/ |
TypeScript | 第四阶段生产实践，重点 packages/opencode/src/ |
本教程所有 Python 示例需要 pip install langchain langgraph；右侧悬浮按钮可切换深浅主题；每章末尾勾选「我已学完」可自动记录进度到浏览器本地存储。
准备好了吗？从 「什么是 Agent」 开始吧。