Agent 架构与设计学习路线

主线：先手写，再用框架；先单 Agent，再多 Agent；先能跑，再能评估、能上线。

这篇文章不是“框架清单”，而是一条从基础能力到生产系统的学习路线。Agent 最容易学偏的地方，是一上来就追 LangGraph、CrewAI、AutoGen 这些名字，结果只学会了调 API，却没有真正理解一个 Agent 为什么会失控、为什么会幻觉、为什么工具调用会失败、为什么上线后必须做评估和观测。

所以更推荐把 Agent 当成一个工程系统来学：模型只是大脑，工具是手脚，状态是记忆，评估和观测是仪表盘，权限控制是刹车。没有仪表盘和刹车的智能体，看起来很酷，但一上路就容易漂移。

0. 总体认知

Agent 不是简单 prompt，也不是几个角色互相聊天，更不是某个框架的 API 速通。一个靠谱 Agent 系统通常包含：

• Model：负责理解、推理、生成。
• Tools：搜索、数据库、代码执行、文件读写、业务 API。
• State：任务状态、对话状态、执行历史、checkpoint。
• Memory/RAG：外部知识、长期记忆、检索策略。
• Planner/Router：决定下一步做什么、用哪个工具、是否拆任务。
• Executor：真实执行工具调用。
• Evaluator：判断结果是否正确。
• Observer：记录 trace、日志、token、成本、错误。
• Human-in-the-loop：高风险动作前让人审批。

从知乎文章中最值得借鉴的一点是：不要把 Agent 学成调 API。 Agent 的核心难点在系统设计、工具边界、状态管理、评估、调试、稳定性和成本控制。

下面这张图可以作为 Agent 系统的总览。学习时不要只盯着 Model，而要观察 Model 如何和工具、状态、知识库、评估系统一起组成闭环。

flowchart TD U[用户请求] --> R[Planner / Router
理解任务并决定下一步] R --> M[Model
推理与生成] M --> T[Tools
搜索 / 数据库 / 代码 / 业务 API] T --> O[Observation
工具执行结果] O --> S[State
任务状态 / 对话历史 / checkpoint] S --> M M --> K[Memory / RAG
外部知识与长期记忆] K --> M M --> E[Evaluator
结果校验] E -->|通过| A[Final Answer] E -->|不通过| R R --> H{高风险动作?} H -->|是| P[Human Approval] H -->|否| T P --> T M --> L[Observer
trace / token / cost / error] T --> L

可以把 Agent 的核心问题拆成三类：

• 决策问题：下一步做什么？该不该调用工具？调用哪个工具？
• 执行问题：工具入参是否正确？失败后如何重试？副作用是否可控？
• 可信问题：结果是否有证据？能否复现？上线后如何知道它变好了还是变坏了？

1. 学习路径总览

建议按 7 个阶段推进：

1. LLM 应用基础
2. 手写 RAG
3. 手写最小 Agent
4. 学轻量 Agent 框架
5. 学状态图与工作流 Agent
6. 学真实开源 Agent 系统
7. 做生产级 Agent 项目

路线可以用这张图理解：前 3 阶段是在练“手感”，第 4-5 阶段是在学习成熟抽象，第 6-7 阶段是在进入真实工程复杂度。

flowchart LR A[1. LLM 应用基础
结构化输出 / 工具调用] --> B[2. 手写 RAG
检索 / 引用 / 解释错误] B --> C[3. 手写最小 Agent
ReAct / tools / trace] C --> D[4. 轻量框架
Pydantic AI / smolagents] D --> E[5. 状态图 Agent
LangGraph / checkpoint / HITL] E --> F[6. 阅读真实系统
OpenHands / SWE-agent] F --> G[7. 生产化项目
eval / trace / cost / deployment]

每个阶段都建议遵循同一个节奏：先做一个能跑的最小项目，再补日志、错误处理、测试和评估。不要等“理论完全懂了”再动手，Agent 的很多坑只有跑起来才会露出牙齿。

2. 第 1 阶段：LLM 应用基础

建议周期：1-2 周

目标

对 LLM 的能力边界建立体感，知道模型什么时候可靠，什么时候必须约束、校验和回退。

要掌握

• Prompt Engineering
• Few-shot
• Chain-of-Thought / reasoning prompt
• Structured Output
• Function Calling / Tool Calling
• Token、上下文窗口、temperature、top_p
• 幻觉、指令冲突、提示注入
• 流式输出
• 模型选择和成本控制

练习项目

1. 结构化信息抽取器

输入一段客服对话，输出结构化 JSON：

{
  "user_question": "...",
  "intent": "...",
  "urgency": "low|medium|high",
  "need_human": true
}

2. 工具调用 Demo

让模型根据用户问题决定调用：

• calculator
• search_local_file
• get_current_time
• final_answer

验收标准

• 知道什么时候该用自然语言输出，什么时候必须用结构化输出。
• 知道模型输出不可信，必须校验。
• 知道 tool schema 设计不好，Agent 会非常不稳定。

这一阶段的关键直觉

LLM 应用基础不是学一些 prompt 技巧，而是建立一个意识：模型输出默认只是候选答案，不是事实本身。 只要输出会进入系统流程，比如写数据库、生成客服回复、触发退款、调用外部 API，就必须尽量结构化、可校验、可回退。

工具调用尤其要重视 schema 设计。比如 search(query: string) 看起来简单，但如果没有说明搜索范围、返回数量、失败语义和是否允许模糊匹配，模型就会自己“脑补工具能力”。很多 Agent 不稳定，不是模型笨，而是工具边界太暧昧。

推荐资料

• ChatGPT Prompt Engineering for Developers
• Building Systems with the ChatGPT API
• OpenAI Agents SDK - Quickstart
• OpenAI Agents SDK - Agents
• Pydantic AI - Agents
• Pydantic AI - Structured Output

3. 第 2 阶段：RAG 基础

建议周期：2-3 周

目标

能独立做一个不用框架的 RAG 问答系统，并能解释为什么回答错。

要掌握

• 文档加载
• 文本切分
• Embedding
• 向量数据库
• Top-k 检索
• Hybrid Search
• Rerank
• Query rewrite
• Context compression
• Citation / 引用来源
• 过期文档、冲突文档处理

练习项目

做一个个人知识库问答系统：

• 支持 Markdown / PDF / txt 文档导入。
• 文档切 chunk。
• 存入 FAISS、Chroma 或 SQLite 向量扩展。
• 用户提问时检索相关 chunk。
• 回答时必须带引用来源。
• 如果检索不到，必须说“不知道”，不能瞎编。

RAG 的流程可以先按最朴素版本实现，不急着堆复杂框架：

flowchart TD D[原始文档
Markdown / PDF / txt] --> C[切分 Chunk] C --> EM[Embedding] EM --> V[(向量库)] Q[用户问题] --> QR[Query Rewrite
可选] QR --> RET[Top-k Retrieval] V --> RET RET --> RR[Rerank
可选] RR --> CTX[组装上下文
带来源] CTX --> LLM[LLM 生成回答] LLM --> ANS[答案 + 引用] ANS --> EV[评估
命中率 / 忠实度 / 相关性]

验收标准

你能解释一次错误回答的原因属于哪一类：

• 文档没收录。
• chunk 切坏了。
• embedding 召回差。
• rerank 排错了。
• prompt 没约束住。
• 模型幻觉了。

常见坑

• chunk 太大：召回内容冗余，模型抓不到重点。
• chunk 太小：上下文断裂，答案缺少必要条件。
• 只做向量召回：关键词、编号、订单号、错误码这类问题可能召回很差。
• 不做引用：回答看起来顺滑，但无法判断证据来自哪里。
• 没有“不知道”机制：检索不到时模型会自然补全，越会写越危险。

推荐资料

• LlamaIndex: RAG 简介
• LangChain RAG Tutorial
• RAGAS Docs
• RAGAS GitHub

4. 第 3 阶段：手写最小 Agent

建议周期：2 周

目标

不依赖框架，自己写出 Agent 主循环。

要掌握

• ReAct 循环
• Tool registry
• Tool schema
• Observation
• Retry
• Max steps
• Stop condition
• Error handling
• Tool result summarization
• Tool permission

最小主循环

while step < max_steps:
    response = call_llm(messages, tools)

    if response.type == "final":
        return response.answer

    if response.type == "tool_call":
        result = run_tool(response.tool_name, response.arguments)
        messages.append(tool_observation(result))

更完整一点，最小 Agent 主循环其实是这个闭环：

flowchart TD START[接收任务] --> THINK[LLM 思考下一步] THINK --> DECIDE{需要工具?} DECIDE -->|否| FINAL[输出最终答案] DECIDE -->|是| SCHEMA[校验工具名和参数] SCHEMA --> EXEC[执行工具] EXEC --> OBS[记录 Observation] OBS --> TRACE[写入 Trace] TRACE --> LIMIT{超过 max steps?} LIMIT -->|否| THINK LIMIT -->|是| STOP[停止并说明未完成原因] EXEC --> ERR{工具失败?} ERR -->|可恢复| OBS ERR -->|不可恢复| STOP

练习项目

做一个本地文件研究 Agent：

• 搜索目录。
• 读取文件。
• 总结文件。
• 根据多个文件回答问题。
• 遇到不确定时继续搜索。
• 最多执行 10 步，防止无限循环。

验收标准

• 能完整打印每一步 trace。
• 能限制最大步数。
• 能处理工具报错。
• 能让 Agent 在没有证据时停止瞎猜。

实现时建议额外记录的日志

最小 Agent 不只是能跑，还要能复盘。每一步至少记录：

• step 编号。
• 模型本次输入摘要。
• 模型选择的动作。
• 工具名和参数。
• 工具返回摘要。
• 本次 token 和耗时。
• 是否触发重试、停止或回退。

这些 trace 在学习阶段看起来有点啰嗦，但它会让你第一次真正“看见”Agent 如何思考、如何跑偏。没有 trace 的 Agent 调试，就像黑灯瞎火修发动机。

推荐资料

• Lilian Weng: LLM Powered Autonomous Agents
• ReAct: Synergizing Reasoning and Acting in Language Models
• Tree of Thoughts
• Reflexion

5. 第 4 阶段：轻量 Agent 框架

建议周期：2-3 周

目标

理解成熟框架如何抽象 Agent、Tool、Output、Dependency、Usage。

推荐项目

smolagents

• smolagents GitHub
• smolagents Docs
• smolagents Guided Tour

重点看：

• CodeAgent
• ToolCallingAgent
• Tool
• Model wrapper
• Execution loop

Pydantic AI

• Pydantic AI GitHub
• Pydantic AI - Agents
• Pydantic AI - Toolsets
• Pydantic AI - Capabilities

重点看：

• Agent 如何定义。
• Tools 如何注册。
• Tool arguments 如何校验。
• Output 如何结构化。
• Usage / token 如何统计。
• Toolset 如何组合。
• 测试时如何 mock 工具。

练习项目

用 Pydantic AI 或 smolagents 重写第 3 阶段的本地文件 Agent。

验收标准

• 所有工具入参都有类型。
• 最终输出是结构化模型。
• 能 mock 工具做单元测试。
• 能记录每次 run 的 usage。

框架学习的正确姿势

学框架时不要只看 quickstart，要反过来问：

• 它如何表达 Agent？
• 它如何描述工具？
• 它如何校验工具入参？
• 它如何处理模型输出不符合 schema？
• 它如何记录 usage？
• 它如何 mock 模型和工具？
• 它如何把一次 run 的中间过程暴露出来？

如果一个框架让 demo 很快，但隐藏了状态、错误和 trace，那它适合原型，不一定适合生产。学习框架最有价值的部分，不是“少写几行代码”，而是理解它替你做了哪些抽象，以及这些抽象在什么场景下会漏。

6. 第 5 阶段：LangGraph 与状态图

建议周期：3-4 周

目标

从“Agent 循环”升级到“Agent 工作流系统”。

真实 Agent 很少只是一个 while loop，它更像一张状态图：

理解任务 -> 检索知识 -> 判断是否需要工具 -> 执行工具
-> 验证结果 -> 需要人工审批？ -> 生成最终结果

对应到状态图，大致会长这样：

flowchart TD A[理解任务] --> B[检索知识] B --> C{是否需要工具?} C -->|否| F[生成草稿] C -->|是| D[执行工具] D --> E[验证工具结果] E -->|失败| B E -->|通过| F F --> G{是否高风险?} G -->|是| H[人工审批
Interrupt] H --> I[恢复执行
Resume] G -->|否| J[最终答复] I --> J J --> K[保存 checkpoint / trace]

要掌握

• State
• Node
• Edge
• Conditional Edge
• Checkpoint
• Interrupt
• Resume
• Human-in-the-loop
• Subgraph
• Durable execution

推荐资料

• LangGraph GitHub
• LangGraph Reference
• LangGraph Human-in-the-loop
• LangGraph Persistence

练习项目

做一个工单处理 Agent：

用户问题
 -> 意图识别
 -> 检索知识库
 -> 判断是否能自动回答
 -> 生成草稿
 -> 如果涉及退款/赔偿/敏感操作，则人工审批
 -> 输出最终答复

验收标准

• 每一步都有明确 state。
• 任意节点失败可以重试。
• 高风险工具调用前可以暂停。
• 人工审批后可以恢复执行。
• 每次执行都能回放 trace。

为什么要学状态图

普通 while loop 适合学习 Agent 的最小机制，但真实业务通常需要更明确的流程控制。比如客服工单、报表生成、退款审核、代码修复，这些任务都有确定阶段：先识别意图，再检索，再判断风险，再执行，再审批，再输出。

状态图的好处是把“下一步去哪”显式表达出来。这样失败重试、人工审批、断点恢复、并行分支、子任务复用都会更清楚。你不再只是让模型自由发挥，而是在给模型一条可控的轨道。

7. 第 6 阶段：真实开源 Agent 系统

建议周期：4-6 周

目标

看真实项目如何处理复杂性：shell、文件系统、sandbox、事件流、前后端、错误恢复、权限边界。

阅读顺序

1. smolagents

• smolagents GitHub

适合理解最小 Agent 抽象。

2. Pydantic AI

• Pydantic AI GitHub

适合学习类型化 Agent 工程实践。

3. LangGraph

• LangGraph GitHub

适合学习状态、流程、checkpoint、human-in-the-loop。

4. OpenHands

• OpenHands GitHub
• OpenHands Agents Docs

重点看：

• CodeActAgent
• Agent runtime
• Shell 执行
• 文件修改
• sandbox
• event stream
• planner
• error recovery
• frontend/backend 如何交互

5. SWE-agent

• SWE-agent GitHub
• SWE-agent Paper

重点看 Agent-Computer Interface，也就是如何设计 Agent 与代码库、shell、测试系统交互的接口。

6. CrewAI

• CrewAI GitHub

适合学习角色型多 Agent：

• Agent role
• Task
• Crew
• Process
• Tool

7. AutoGen

• AutoGen GitHub

适合作为经典多 Agent 案例阅读，重点看 conversational agents、group chat、multi-agent runtime。

阅读开源项目时看什么

建议不要按文件从头读到尾，而是带着问题读：

• 入口在哪里？一次用户请求如何变成 Agent run？
• 工具是如何注册、隔离和执行的？
• shell、文件系统、网络这些危险能力如何做权限控制？
• 中间事件如何流向前端？
• 失败后如何恢复？是否会重新规划？
• trace 保存在哪里？能不能复现一次失败？
• prompt、工具、状态三者之间如何组织？

真实系统的价值不在于“代码更多”，而在于你能看到工程妥协：哪些地方必须安全，哪些地方为了体验做了简化，哪些地方为了可观测性牺牲了实现优雅。

8. 第 7 阶段：生产化能力

建议周期：长期练习

Evaluation

Agent 没有评估集，就没有迭代方向。

你要建立：

• Golden dataset
• 用户真实问题集
• 标准答案
• 检索命中率
• Answer relevancy
• Faithfulness
• Context recall
• Tool success rate
• Human escalation rate

推荐资料：

• RAGAS Docs
• DeepEval GitHub

生产化 Agent 的迭代闭环可以这样理解：

flowchart LR Q[真实用户问题] --> G[Golden Dataset
标准问题集] G --> RUN[Agent Run] RUN --> T[Trace
每一步执行过程] RUN --> M[Metrics
命中率 / 工具成功率 / 成本] T --> ERR[错误归因] M --> ERR ERR --> IMP[改进 Prompt / Tool / RAG / Workflow] IMP --> RUN RUN --> PROD[线上发布] PROD --> Q

Observability

你要能回答：

• Agent 每一步做了什么？
• 调了哪些工具？
• 每次 LLM 输入输出是什么？
• 哪一步开始跑偏？
• token 花在哪？
• 延迟主要在哪？

推荐资料：

• OpenAI Agents SDK - Tracing
• LangSmith

Safety

重点能力：

• 工具白名单
• 参数校验
• SQL 防护
• 文件读写限制
• 用户确认
• 敏感信息脱敏
• prompt injection 防御
• 高风险动作审批

推荐资料：

• OpenAI Agents SDK - Guardrails

Stability

重点能力：

• max iterations
• timeout
• retry
• circuit breaker
• fallback model
• cost budget
• tool idempotency
• partial failure recovery

生产化检查清单

能力	要回答的问题	最小做法
Evaluation	改完后到底有没有变好？	准备 30-100 条真实问题和标准答案
Observability	Agent 是在哪一步跑偏的？	保存每一步模型输入、工具调用、输出摘要
Safety	哪些动作不能让模型直接执行？	工具白名单 + 高风险动作人工审批
Stability	卡住、超时、失败怎么办？	max steps、timeout、retry、fallback
Cost	一次 run 花多少钱？	记录 token、模型、工具耗时和调用次数

9. 一年学习计划

第 1 个月：LLM + Prompt + Structured Output

产出：

• 信息抽取器
• 工具调用 demo
• JSON 输出校验器

第 2 个月：RAG

产出：

• 本地知识库问答
• 带引用回答
• 简单评估集

第 3 个月：手写 Agent

产出：

• 本地文件 Agent
• ReAct loop
• 工具注册系统
• trace 日志

第 4 个月：Pydantic AI / smolagents

产出：

• 类型化 Agent
• toolset
• structured final output
• mock tool tests

第 5-6 个月：LangGraph

产出：

• 工单 Agent
• human-in-the-loop
• checkpoint/resume
• 状态图可视化

第 7-8 个月：OpenHands / Coding Agent

产出：

• 简易代码修复 Agent
• 能读 repo、改文件、跑测试
• 失败后重新规划

第 9-10 个月：多 Agent

产出：

• Researcher + Writer + Reviewer 协作 Agent
• 或客服场景：Router + RAG Agent + Escalation Agent

第 11-12 个月：生产化项目

做一个完整项目，例如：

• 企业知识库客服 Agent
• 代码库问答 + 修复 Agent
• 工单转知识库 Agent
• 数据分析 Agent
• 运营日报 Agent

必须包含：

• RAG
• tool calling
• LangGraph workflow
• human approval
• eval dataset
• trace
• cost tracking
• deployment
• README
• demo cases

10. 最推荐的 5 个开源项目

1. smolagents
   轻，适合理解 Agent 最小实现。

2. Pydantic AI
   工程味强，适合学类型化 Agent。

3. LangGraph
   最适合学状态、流程、checkpoint、human-in-the-loop。

4. OpenHands
   真实复杂 coding agent，值得反复读。

5. CrewAI
   学多 Agent 角色和任务编排。

11. 最小实战组合

如果时间有限，至少完成这 4 个项目：

1. 本地文件搜索 Agent：练 ReAct + tools。
2. 个人知识库 RAG：练 chunk、embedding、retrieval、citation。
3. 工单处理 Agent：练 LangGraph、状态流、人工审批。
4. 代码修复 Agent：练 sandbox、shell、patch、测试、失败恢复。

12. 最终能力地图

学完之后，你应该能独立设计这种架构：

flowchart TD U[User Request] --> IR[Intent Router] IR --> SC[Safety Check] SC --> PL[Planner] PL --> RAG[RAG Retriever] PL --> TE[Tool Executor] RAG --> RV[Result Verifier] TE --> RV RV --> HA{Need Human Approval?} HA -->|Yes| H[Human Approval] H --> FA[Final Response] HA -->|No| FA FA --> LOG[Trace / Eval / Cost Log] LOG --> DATA[Evaluation Dataset] DATA --> PL

更重要的是，你能解释每个设计决策：

• 为什么这里用 RAG，不用 fine-tuning？
• 为什么这里用 LangGraph，不用普通 while loop？
• 为什么这个工具要人工审批？
• 为什么多 Agent 在这里有价值？
• 为什么这个回答可信？
• 怎么证明改版后效果变好了？

这才算真正学会 Agent 架构和设计。

13. 一句话总结

Agent 学习最好的路径不是“先找最强框架”，而是：

1. 先理解模型边界。
2. 再学会给模型接工具。
3. 然后用 RAG 给模型可靠知识。
4. 接着用 Agent loop 让模型能行动。
5. 再用状态图让行动可控。
6. 最后用评估、观测、安全和成本控制让系统可上线。

真正成熟的 Agent 工程师，不是让模型“看起来很聪明”，而是能让它在复杂环境里稳定、可解释、可回滚、可持续改进。