导读#

这篇路线不是简单的“框架学习清单”，而是一份以真实业务 Agent 为主线的长期学习地图。你可以把它当作：

学习路线：明确每个阶段学什么、做到什么程度；
项目规划：把知识点落到可运行项目中；
工程手册：覆盖工具调用、记忆、RAG、安全、评估和维护；
能力清单：用 checklist 判断自己是否真正具备 Agent 工程能力。

路线速览#

模块	你将掌握什么	结果
基础能力	Python 工程化、FastAPI、Pydantic、Docker、Redis、PostgreSQL	能搭建 Agent 后端工程
核心范式	ReAct、Plan-and-Execute、Workflow、Agentic RAG、Multi-Agent	能判断业务场景适合哪种范式
Harness 架构	Context、Memory、Tools、Planner、Executor、Guardrails、Evaluator	能设计完整 Agent 系统
工程落地	Tool Calling、MCP、Agent Skills、LangGraph、RAG、AgentOps	能实现可运行、可维护系统
评估优化	Golden Dataset、Trajectory Eval、Failure Taxonomy、Eval as CI Gate	能量化优化 Agent 效果
生产维护	观测、回放、灰度、回归测试、成本控制、降级策略	能把 Demo 变成生产级系统

总目标：你最终要成为哪类 Agent 工程师#

你要成为的不是“会调用大模型 API 的开发者”，也不是“会写 LangChain Demo 的应用工程师”，而是具备完整 Agent 系统设计能力的工程型架构人才。

最终能力画像：

范式判断能力：看到一个业务场景，能判断该用普通 LLM、RAG、Workflow Agent、Tool-use Agent、Multi-Agent、Computer-use Agent，还是不该用 Agent。
Harness 架构能力：能把上下文、记忆、工具、规划、执行、反馈、安全、评估、观测组合成一个可运行、可维护的系统。
工程实现能力：能使用 Python / Java / FastAPI / LangGraph / LlamaIndex / OpenAI API / Claude API / MCP / Redis / PostgreSQL / Docker 等技术完成可部署系统。
业务建模能力：能把客服、交易履约、知识库、代码助手、数据分析等业务拆成流程、状态、工具、权限、异常和指标。
评估优化能力：能构建测试集、失败样本集、回归测试集、trace 分析和端到端指标体系。
生产维护能力：能进行 prompt / tool / memory / model / policy 的版本管理、灰度发布、线上排查、成本控制和持续优化。
项目表达能力：能把学习成果转化为 GitHub 项目、技术博客、简历亮点、面试叙事和长期技术沉淀。

一句话总结：

精英 Agent 工程师 = 懂 LLM + 懂后端工程 + 懂业务流程 + 懂评估优化 + 懂长期维护。

整体学习主线#

这条路线分成 4 条并行主线，但学习时以项目驱动推进。

1
主线 A：Agent 理论范式
2
Prompt Engineering → ReAct → Plan-and-Execute → Reflection → Workflow Agent → Agentic RAG → Multi-Agent → Computer-use Agent
3

4
主线 B：Agent Harness 架构
5
Input → Intent → Context → Memory → Tools → Planner → Executor → Guardrails → Evaluator → Observability → HITL
6

7
主线 C：Python 工程落地
8
FastAPI → Pydantic → LangGraph → Tool Calling → MCP → RAG → LiteLLM → Redis/PostgreSQL → Docker → AgentOps
9

10
主线 D：业务项目训练
11
PromptLab-Agent → SmartKB-Agent → OrderFlow-Agent → CodeFix-Agent → AgentOps-Platform

学习原则#

这条路线的核心不是“学更多框架”，而是把 Agent 做成可运行、可评估、可维护的业务系统。

不以“学框架”为目标，而以“能否解决业务闭环”为目标；
不先做复杂多 Agent，先做稳定的单 Agent 状态图闭环；
不只看最终回复，要看工具轨迹、状态变化、失败原因和成本；
不把 Prompt 当玄学，要做版本管理、测试和回归；
不把 RAG 做成普通问答，要做业务证据链和可验证决策；
不盲目微调，先做 Prompt / RAG / Tool / Eval，再判断是否需要微调。

最终技术栈建议#

核心工程栈#

模块	推荐技术	学习目标
后端服务	FastAPI / Spring Boot	暴露 Agent 服务、工具服务、业务接口
数据建模	Pydantic / dataclass / Java DTO	定义状态、工具参数、结构化输出
Agent 编排	LangGraph	构建状态图、条件路由、checkpoint、HITL
模型调用	OpenAI API / Claude API / LiteLLM	结构化输出、工具调用、多模型路由、fallback
工具协议	Function Calling / MCP	标准化工具注册、调用、权限与审计
RAG	LlamaIndex / LangChain / Qdrant / Milvus / BM25 / rerank	企业知识库、规则检索、证据链
存储	PostgreSQL / MySQL / Redis	业务数据、状态、缓存、队列
评估	pytest / Ragas / LangSmith / 自定义 metrics	节点级、工具级、端到端评估
观测	OpenTelemetry / LangSmith / Langfuse / 日志系统	trace、span、token、成本、延迟
部署	Docker / docker-compose	本地和服务器部署
微调	Hugging Face TRL / LLaMA-Factory / LoRA / QLoRA	小模型工具调用和领域适配实验

前沿增强模块#

模块	作用	放入路线的位置
MCP	标准化 Agent 与外部工具、资源、提示模板的连接	阶段 4：工具调用与外部系统集成
Agent Skills / Skill Registry	把工具、脚本、模板、说明文档打包成可复用能力包	阶段 4：工具与技能化封装
GraphRAG / RuleRAG	用图谱或规则结构增强 RAG 的证据组织能力	阶段 6：Agentic RAG
A2A / Agent-to-Agent 协议思想	多 Agent 跨系统通信与协作	阶段 8：Multi-Agent
Trace / Trajectory 级评估	不只评估最终答案，还评估每一步轨迹	阶段 11：评估与可观测性
Eval as CI Gate	把评估集接入 CI，防止 prompt/tool 版本更新导致退化	阶段 12：生产维护
AgentOps	Agent 的监控、回放、失败归因、成本治理	阶段 12：生产部署与长期维护
Computer-use / Browser-use Agent	无 API 场景下通过浏览器或 GUI 操作系统	阶段 2

阶段总览#

阶段	主题	核心目标
阶段 0	前置基础补齐	搭建 Agent 工程底座
阶段 1	LLM 与 Prompt Engineering	把 Prompt 做成可测试资产
阶段 2	Agent 基础范式	掌握范式边界与业务适配
阶段 3	Agent Harness 架构	建立完整系统模块认知
阶段 4	工具调用、MCP 与 Agent Skills	连接真实业务系统
阶段 5	Memory 与 Context Engineering	管理上下文与长期记忆
阶段 6	Agentic RAG / GraphRAG / RuleRAG	构建可追溯业务证据链
阶段 7	Planning / Reflection / Verifier	处理复杂任务与自我修正
阶段 8	Multi-Agent 系统	设计多角色协同机制
阶段 9	Agent 微调工程	判断何时需要微调以及如何构造轨迹数据
阶段 10	Agent 安全、约束与可靠性	构建安全边界与防护机制
阶段 11	评估、测试集与可观测性	建立量化评估和失败归因体系
阶段 12	生产部署、AgentOps 与长期维护	从 Demo 走向生产级系统

配套文章索引#

阶段	主文章	专项扩展
阶段 0	Agent 工程基础底座：从 Python 服务到可演进的 Runtime 骨架	—
阶段 1	上下文工程与 Prompt Engineering 基础	Prompt 注入攻击防护 · OrderFlow-Agent Prompt 模块设计
阶段 2	Agent 基础范式：从 ReAct 到 Multi-Agent 的工程理解	Agent 意图识别与路由工程
阶段 3	Agent Harness 架构设计	—
阶段 4	Tool Calling、MCP 与 Agent Skills	—
阶段 5	Agent Memory 与 Context Engineering	—
阶段 6	Agentic RAG、GraphRAG 与 RuleRAG	—
阶段 7	Planning、Reflection 与 Verifier	—
阶段 8	Multi-Agent 与 A2A 协作	—
阶段 9	Agent 微调工程	—
阶段 10	Agent 安全、约束与可靠性	—
阶段 11	Agent 评估、测试集与可观测性	—
阶段 12	Agent 生产部署与 AgentOps	—

第一部分：基础能力与核心范式#

阶段 0：前置基础补齐#

学习目标#

补齐 Agent 工程落地所需的基础能力，但不要过度学习。所有基础都服务于后续项目。

核心知识#

能力	学到什么程度
Python 工程化	会组织项目结构、虚拟环境、依赖管理、配置、日志、异常、类型提示
Web 后端	会用 FastAPI 写接口、请求响应、异常处理、OpenAPI 文档
LLM API	会调用 chat、structured output、tool calling、streaming
Pydantic	会定义 schema、字段校验、嵌套模型、错误处理
RAG 基础	理解 chunk、embedding、retrieval、rerank、citation
向量数据库	会用 Qdrant / Milvus / Chroma 任意一个完成检索
Redis	会做缓存、限流、任务状态、队列
PostgreSQL / MySQL	会保存业务数据、测试集、日志
GitHub	会写 README、issue、commit、目录结构
Docker	会用 docker-compose 启动服务依赖

实践任务#

搭建基础工程：

1
agent-system/
2
  app/
3
    api/
4
    core/
5
    schemas/
6
    services/
7
    agents/
8
    tools/
9
    rag/
10
    memory/
11
    eval/
12
    tests/
13
  data/
14
  docs/
15
  docker-compose.yml
16
  README.md

项目产出#

FastAPI 服务能启动；
.env 配置能读取；
日志能输出；
pytest 能运行；
Pydantic schema 能校验；
Docker Compose 能启动 Redis / PostgreSQL / 向量库。

达标标准#

你能从零搭建一个后端项目，并通过接口模拟订单、物流、规则、退款和工单服务。

阶段 1：LLM 与 Prompt Engineering 基础#

学习目标#

把 Prompt 从“临时话术”升级为生产系统里的可版本化、可测试、可回滚的指令资产。

核心知识#

Prompt 分层
- System Prompt：模型长期边界；
- Developer Prompt：应用侧任务规则；
- User Prompt：用户当前请求；
- Tool Result Context：工具返回事实；
- Memory Context：被筛选后的历史信息。
生产级 Prompt 原则
- 明确任务、输入、输出、约束；
- 优先结构化输出；
- 对高风险动作增加确认；
- 不依赖长篇 CoT，使用结构化中间字段；
- Prompt 必须有版本号、测试集和变更记录。
Chain-of-thought 替代设计

1
任务类型
2
证据列表
3
决策字段
4
置信度
5
风险标签
6
下一步动作
7
失败原因

Prompt Injection 防护基础
- 区分可信上下文和不可信上下文；
- 不让网页、文档、用户输入覆盖系统规则；
- 对工具调用前做 policy check。

实践任务#

为 OrderFlow-Agent 编写 5 类 Prompt：

意图识别 Prompt；
槽位抽取 Prompt；
规则检索 Query Rewrite Prompt；
责任归因 Prompt；
客服回复生成 Prompt。

每个 Prompt 包含：

输入字段；
输出 schema；
正例；
反例；
测试样例；
版本号。

项目产出#

1
prompts/
2
  intent_v1.md
3
  slot_extract_v1.md
4
  policy_rewrite_v1.md
5
  responsibility_v1.md
6
  response_v1.md
7
tests/prompts/
8
  test_intent_prompt.py
9
  test_responsibility_prompt.py
10
docs/prompt_design_notes.md
11
docs/prompt_eval_report.md

达标标准#

你能解释每个 Prompt 为什么这样设计，并能用测试集说明新版本是否优于旧版本。

阶段 2：Agent 基础范式与适用边界#

学习目标#

理解 Agent 范式的本质，不盲目套框架。重点是判断“什么场景适合什么范式”。

核心范式#

范式	核心思想	适合场景	主要风险
ReAct	Reason + Act 循环	搜索、查询、轻量工具使用	循环、成本高、动作不稳定
Plan-and-Execute	先规划再执行	多步骤任务、复杂流程	计划过时、执行偏离
Reflection	执行后反思修正	代码、写作、复杂判断	延迟和成本上升
Tool-use Agent	模型选择工具并生成参数	数据查询、业务操作	工具误用、越权
Workflow Agent	固定流程 + 局部 LLM	交易履约、审批、售后	灵活性较低
Router Agent	路由到不同工具/专家	多意图系统	路由错误级联
Agentic RAG	检索、判断、追问、再检索	企业知识库、规则决策	检索链路复杂
Code Agent	读写代码、运行测试	编程助手、自动修复	沙箱和安全要求高
Computer-use Agent	操作浏览器/GUI	无 API 的业务系统	慢、不稳定、难评估
Multi-Agent	多角色协作	复杂研究、评审、业务分工	成本、冲突、不可控

工程判断原则#

高可靠业务流程：优先 Workflow Agent；
需要外部数据：Tool-use Agent + RAG；
需要规则依据：Agentic RAG / RuleRAG；
需要多角色评审：Multi-Agent；
无 API 系统自动化：Computer-use Agent；
简单问答：不要用复杂 Agent。

实践任务#

针对“用户申请退款”实现 4 种版本：

普通 LLM 回复；
ReAct 工具调用；
Workflow Agent 状态图；
Workflow + RAG + Tool Verification。

比较：

准确率；
工具调用次数；
是否可解释；
是否易测试；
延迟和成本；
是否能用于生产。

项目产出#

1
examples/
2
  refund_plain_llm.py
3
  refund_react_agent.py
4
  refund_workflow_agent.py
5
  refund_workflow_rag_verified.py
6
docs/paradigm_learning_notes.md

达标标准#

你能在面试中讲清楚：为什么交易履约更适合 Workflow Agent + Tool-use + RuleRAG，而不是完全开放式 ReAct。

第二部分：Agent Harness 架构与核心模块#

阶段 3：Agent Harness 架构设计#

学习目标#

把 Agent 看成一个由多个工程模块组成的系统，而不是一个大 Prompt。

Harness 模块总览#

模块	解决的问题	输入	输出	常见实现	如何测试
输入理解层	标准化用户输入	query	normalized request	LLM / 规则	意图覆盖率
意图识别层	判断任务类型	query + history	intent	classifier / LLM	intent accuracy
槽位抽取层	提取业务参数	query	slots	structured output	slot F1
任务规划层	决定执行步骤	state	plan / next node	状态机 / LLM	plan validity
上下文管理层	控制模型看到的信息	state + memory + tools	compact context	selector / summarizer	context precision
短期记忆	维护当前任务状态	conversation	AgentState	LangGraph state	state consistency
长期记忆	保存跨会话信息	events	retrievable memory	DB / vector DB	memory retrieval
工具注册层	管理可用工具	tool schema	tool registry	function calling / MCP	tool schema test
工具执行层	安全执行动作	tool call	tool result	executor	tool success rate
状态管理层	记录流程进展	node output	state update	StateGraph	replay test
反思修正层	修复错误	trace + error	repaired action	verifier / critic	repair success
约束安全层	防止危险行为	input/action	allow/deny	guardrails / policy	adversarial test
人工接管层	高风险兜底	uncertain state	human decision	HITL	handoff precision
评估日志层	衡量质量	trace	metrics	eval runner	golden dataset
观测运维层	支持线上排查	run metadata	trace / dashboard	OTel / LangSmith	failure replay

实践任务#

画出 OrderFlow-Agent Harness 架构图：

1
User Input
2
  ↓
3
Input Normalizer
4
  ↓
5
Intent & Slot Layer
6
  ↓
7
Context Builder
8
  ↓
9
Planner / Router
10
  ↓
11
Tool Executor
12
  ↓
13
Policy RAG / RuleRAG
14
  ↓
15
Decision Layer
16
  ↓
17
Guardrails
18
  ↓
19
Action Execution
20
  ↓
21
Verification
22
  ↓
23
Response + Trace + Evaluation

项目产出#

1
docs/agent_harness_architecture.md
2
docs/architecture_diagram.png
3
app/agents/state.py
4
app/agents/workflow.py
5
app/agents/router.py
6
app/agents/guardrails.py

达标标准#

你能对任意业务需求拆出 Agent 的核心模块，并说清楚每个模块的输入、输出、风险和测试方式。

阶段 4：工具调用、MCP 与 Agent Skills#

学习目标#

掌握工具调用的工程本质：模型只生成结构化调用意图，真正执行业务的是受控工具层。

核心知识#

Function Calling / Tool Calling
- 工具名；
- 工具描述；
- 参数 schema；
- 返回 schema；
- 错误 schema；
- 权限级别；
- 是否有副作用；
- 是否需要人工确认。
MCP 思想
- MCP Client；
- MCP Server；
- Tools；
- Resources；
- Prompts；
- tool registry；
- 权限和审计；
- 工具供应链安全。
Agent Skills 思想
- 工具是单个动作；
- Skill 是可复用能力包；
- Skill 可以包含说明文档、脚本、模板、示例、资源文件；
- 适合把“订单处理”“规则判断”“日报生成”“代码审查”封装成能力模块。
工具调用失败处理
- 参数缺失 → 澄清或补全；
- 网络失败 → 重试；
- 权限不足 → 拒绝或人工；
- 工具成功但状态未变 → verification；
- 重复调用有副作用 → 幂等 key；
- 高风险工具 → 二次确认。

实践任务#

实现 OrderFlow-Agent 工具层：

1
query_order(order_id)
2
query_logistics(order_id)
3
search_policy(query, context)
4
create_refund(order_id, amount, reason)
5
create_compensation(order_id, amount, reason)
6
create_ticket(order_id, reason, priority)
7
verify_final_state(order_id, expected_state)

进一步封装成 Skill：

1
skills/
2
  order_fulfillment_skill/
3
    SKILL.md
4
    tools.py
5
    schemas.py
6
    examples.jsonl
7
    tests/

项目产出#

1
app/tools/
2
  order_tool.py
3
  logistics_tool.py
4
  policy_tool.py
5
  refund_tool.py
6
  ticket_tool.py
7
  verification_tool.py
8
app/mcp/
9
  client.py
10
  server.py
11
  registry.py
12
skills/order_fulfillment_skill/

达标标准#

不依赖 LLM，也能手动跑通：

1
输入订单号
2
→ 查订单
3
→ 查物流
4
→ 检索规则
5
→ 创建退款
6
→ 校验退款状态

同时能解释：哪些工具允许自动执行，哪些工具必须人工确认。

阶段 5：Memory 与 Context Engineering#

学习目标#

理解上下文工程比单纯 Prompt Engineering 更重要。模型质量取决于：你给它看什么、不让它看什么、以什么结构给它看。

核心知识#

类型	作用	项目示例
Conversation Memory	当前多轮对话	用户刚补充订单号
Working Memory	当前任务状态	AgentState 中订单、物流、规则
Episodic Memory	事件记忆	用户之前多次投诉物流
Semantic Memory	稳定知识	平台规则、业务概念
Vector Memory	语义检索	历史工单、FAQ
Summary Memory	压缩摘要	长对话摘要
Long-term Memory	跨会话持久化	用户偏好、常见问题
Scratchpad	临时中间状态	节点临时结果

Context Engineering 关键问题#

哪些信息必须进入上下文？
哪些信息应该压缩？
哪些信息不能进入上下文？
工具结果如何压缩？
长对话如何分层摘要？
记忆何时写入？
记忆冲突如何解决？
如何评估记忆是否有用？

Memory Write Policy#

1
长期偏好 → 可写长期记忆
2
当前任务状态 → 写 AgentState
3
工具结果 → 写 trace，不一定写长期记忆
4
敏感信息 → 默认不写长期记忆
5
不确定信息 → 不写或标记低置信度
6
用户明确要求删除 → 必须删除

实践任务#

为 OrderFlow-Agent 设计三层记忆：

1
短期：当前会话状态 AgentState
2
中期：当前订单/工单处理历史
3
长期：用户偏好、投诉模式、规则命中历史

项目产出#

1
app/memory/
2
  short_term.py
3
  long_term.py
4
  context_builder.py
5
  memory_policy.py
6
  summarizer.py
7
  conflict_resolver.py
8
tests/memory/

达标标准#

你能解释清楚：为什么某条信息进入上下文，为什么某条信息不进入上下文，以及记忆错误时如何修复。

第三部分：RAG、规划、多 Agent 与微调#

阶段 6：Agentic RAG、GraphRAG 与 RuleRAG#

学习目标#

从普通知识库问答升级为业务决策证据系统，让 Agent 的判断有依据、可追溯、可验证。

核心知识#

技术	作用
Query Rewrite	把口语问题改写成检索问题
Query Decomposition	把复杂问题拆成多个检索子问题
Hybrid Retrieval	BM25 + dense vector
Rerank	对召回内容重排序
Citation	给出证据来源
Grounding	回答必须基于证据
Permission-aware RAG	基于用户权限过滤文档
RuleRAG	面向规则条款、条件、动作的检索
GraphRAG	用实体、关系、社区摘要增强复杂知识检索
RAG Evaluation	context recall、faithfulness、citation accuracy

OrderFlow-Agent 中的 RuleRAG#

普通 RAG：

1
用户问题 → 检索文档 → 生成回答

业务型 RuleRAG：

1
订单状态 + 物流状态 + 用户诉求
2
→ 生成规则检索 query
3
→ 检索规则条款
4
→ 提取适用条件
5
→ 支撑责任判断
6
→ 支撑动作决策
7
→ 记录证据链

实践任务#

构建规则库：

1
R001：商家超过 48 小时未发货，用户可申请全额退款。
2
R002：物流超过 7 天无更新，优先判定物流异常。
3
R003：已签收超过 7 天，非质量问题不支持无理由退款。
4
R004：平台补偿金额不得超过实付金额的 10%。

项目产出#

1
data/policies.json
2
rag/index_builder.py
3
rag/retriever.py
4
rag/reranker.py
5
rag/policy_parser.py
6
rag/citation_checker.py
7
rag/rule_reasoner.py

达标标准#

输入：

1
订单已支付 72 小时未发货，用户要求退款

系统输出：

1
命中规则：R001
2
责任方：merchant
3
建议动作：refund
4
证据：商家超过 48 小时未发货

阶段 7：Planning、Reflection、Verifier 与自我修正#

学习目标#

掌握规划和反思的适用边界。不是所有任务都需要 planner，也不是所有任务都值得 reflection。

核心机制#

机制	适合场景	不适合场景
Task Planning	多步骤目标明确任务	简单 FAQ
Subtask Decomposition	复杂任务拆解	原子任务
Dynamic Planning	环境状态变化	固定流程
Reflection	代码、写作、复杂判断	实时客服高并发
Critic Model	需要质量评审	低价值任务
Verifier	有明确规则或答案	主观开放问题
Retry Policy	工具失败、格式错误	有副作用的重复操作
Plan Repair	执行中断、工具失败	无状态任务

设计原则#

1
高可靠业务：优先状态机 + 局部规划
2
开放任务：可以使用 planner
3
高风险动作：必须 verifier + human-in-the-loop
4
低价值任务：不要反思，直接回答
5
工具失败：优先 plan repair，而不是重新开始

实践任务#

为 OrderFlow-Agent 加入：

初始计划生成；
工具失败后的 plan repair；
决策前 verifier；
高风险退款 human approval；
执行后 final state verification。

项目产出#

1
app/agents/planner.py
2
app/agents/verifier.py
3
app/agents/retry_policy.py
4
app/agents/plan_repair.py
5
docs/planning_strategy.md

达标标准#

你能说明：哪些节点由 LLM 决策，哪些节点由代码状态机控制，哪些节点必须进入人工确认。

阶段 8：Multi-Agent 系统与 Agent-to-Agent 协作#

学习目标#

理解 Multi-Agent 的价值不是“Agent 数量多”，而是专业分工、协作协议、轨迹可评估。

核心模式#

模式	说明	适合项目
Supervisor-Worker	一个主管分配任务给多个专家	客服分流、企业助手
Planner-Executor	一个负责规划，一个负责执行	长任务自动化
Researcher-Writer-Reviewer	研究、写作、审查分离	报告生成
Critic-Reflector	生成与批评分离	代码修复、内容审核
Debate	多个 Agent 辩论	决策评审，生产慎用
Swarm	多个轻量 Agent 协作	研究探索，生产慎用
Blackboard	共享状态板协作	复杂任务协同
A2A 思想	Agent 间协议化通信	跨系统 Agent 协作

OrderFlow-Agent 多 Agent 设计#

1
Coordinator Agent：总控调度
2
Context Agent：意图识别、槽位补全、上下文整理
3
Business Agent：订单、物流、售后状态查询
4
Policy Agent：规则检索、规则解释、证据提取
5
Decision Agent：责任归因、退款/补偿/转人工决策
6
Execution Agent：退款、补偿、工单工具执行
7
Verification Agent：最终状态校验、风险检查

设计原则#

不是每个 Agent 都必须调用 LLM：

1
Context Agent：LLM
2
Business Agent：API + 规则代码
3
Policy Agent：RAG + LLM
4
Decision Agent：LLM + 规则约束
5
Execution Agent：纯工具调用
6
Verification Agent：规则代码 + 少量 LLM
7
Coordinator Agent：LangGraph 条件路由

项目产出#

1
app/multi_agent/
2
  coordinator.py
3
  context_agent.py
4
  business_agent.py
5
  policy_agent.py
6
  decision_agent.py
7
  execution_agent.py
8
  verification_agent.py
9
  shared_state.py
10
docs/multi_agent_design.md

达标标准#

你能记录每个 Agent 的输入、输出、工具调用、耗时、失败原因、最终贡献，并能评估多 Agent 是否真的比单 Agent 更好。

阶段 9：Agent 微调工程#

学习目标#

理解微调在 Agent 中的边界：微调不是第一选择，而是在 Prompt、RAG、工具、评估稳定之后的优化手段。

什么时候需要微调#

适合微调：

固定格式输出不稳定；
领域术语和语气要求高；
工具调用选择有稳定模式；
有大量高质量轨迹数据；
希望用小模型降低成本。

不适合微调：

业务规则经常变化；
事实知识频繁更新；
数据少；
问题主要来自检索或工具设计；
没有评估集。

核心知识#

技术	在 Agent 中的作用
SFT	学会格式、工具调用风格、领域话术
DPO / Preference Learning	学会偏好更好的决策或回复
Tool-use Data	query、state、tool call、tool result、final answer
Trajectory Data	plan、action、observation、state、final
Rejection Sampling	多次生成并筛选高质量样本
Synthetic Data	用强模型合成训练数据
Domain Adaptation	小模型领域适配
Eval after FT	微调前后任务成功率、格式错误率、成本对比

实践项目#

1
MiniToolAgent-SFT：面向客服工具调用的小模型微调实验

流程：

构造 500—2000 条客服工具调用样本；
样本包含 query、state、tool call、tool result、final answer；
使用 LoRA / QLoRA 做小模型 SFT；
与 prompt-only 大模型比较工具调用准确率；
分析微调是否值得。

项目产出#

1
fine_tuning/
2
  data/tool_use_train.jsonl
3
  data/tool_use_eval.jsonl
4
  train_lora.py
5
  eval_tool_call.py
6
  report.md

达标标准#

你能回答：这个问题应该用 Prompt、RAG、工具工程还是微调解决，为什么？

第四部分：安全、评估、生产与维护#

阶段 10：Agent 安全、约束与可靠性#

学习目标#

掌握生产级 Agent 的安全边界，不让模型越权、误操作、泄露数据或被注入攻击操控。

核心风险#

风险	示例	防御
Prompt Injection	用户让模型忽略系统规则	指令分层、输入隔离、规则校验
Jailbreak	绕过安全策略	policy engine、输出过滤
Tool Misuse	模型乱退款	权限、确认、业务校验
Data Leakage	泄露其他用户订单	RBAC、数据过滤
Unsafe Action	高风险动作自动执行	human-in-the-loop
Context Pollution	文档内容污染系统指令	不可信内容隔离
Memory Poisoning	写入错误长期记忆	memory write policy
MCP Tool Risk	外部工具供应链风险	白名单、沙箱、审计
Skill Supply Chain Risk	Skill 中脚本或说明不可信	签名、审核、权限边界

生产级安全设计#

1
输入层：内容分类 + 注入检测
2
上下文层：可信/不可信信息隔离
3
记忆层：写入策略 + 冲突处理 + 敏感信息过滤
4
工具层：权限控制 + 参数校验 + 幂等 + 审计
5
决策层：policy engine + verifier
6
执行层：高风险动作二次确认
7
输出层：敏感信息过滤 + 格式校验
8
观测层：全链路 trace + audit log

实践任务#

为 OrderFlow-Agent 增加 6 类 guardrail：

Prompt injection 检测；
退款金额上限；
用户权限校验；
高风险动作人工确认；
输出敏感信息脱敏；
工具和 Skill 白名单。

项目产出#

1
app/security/
2
  injection_detector.py
3
  permission.py
4
  policy_engine.py
5
  output_filter.py
6
  audit_log.py
7
  tool_sandbox.py
8
tests/security/

达标标准#

通过 30—50 条 adversarial test case，系统不能越权退款、泄露订单或执行不合规工具调用。

阶段 11：Agent 评估、测试集构建与可观测性#

学习目标#

把 Agent 从“感觉效果不错”变成能量化、能回归、能定位失败原因的系统。

为什么 Agent 难评估#

Agent 不是单次文本生成，而是多步骤系统：

1
输入理解
2
→ 检索
3
→ 规划
4
→ 工具选择
5
→ 参数生成
6
→ 工具执行
7
→ 状态更新
8
→ 决策
9
→ 输出

每一步都可能错，因此要做 trace / trajectory / DAG 级评估。

完整评估体系#

层级	指标
输入理解	Intent Accuracy、Slot F1
检索层	Recall@K、MRR、Citation Accuracy
工具层	Tool Selection Accuracy、Argument Accuracy、Tool Success Rate
轨迹层	Step Accuracy、Trajectory Match、DAG Validity
规划层	Plan Validity、Step Efficiency
决策层	Responsibility Accuracy、Action Accuracy
安全层	Unsafe Action Rate、Injection Defense Rate
输出层	Faithfulness、Helpfulness、Format Validity
端到端	Task Success Rate、Human Escalation Precision
系统层	Latency、Cost、Retry Rate、Fallback Rate
用户层	Satisfaction、Resolution Rate

测试集类型#

Golden Dataset：标准业务样本；
Adversarial Test Set：攻击和边界样本；
Regression Test Set：历史失败样本；
Scenario-based Evaluation：按业务流程设计样本；
Synthetic Test Set：合成覆盖长尾场景；
Online Eval：线上抽样评估；
Human Review Set：人工标注困难样本。

Failure Taxonomy#

1
F1 意图识别错误
2
F2 槽位缺失
3
F3 检索不到规则
4
F4 命中错误规则
5
F5 工具选择错误
6
F6 工具参数错误
7
F7 工具顺序错误
8
F8 责任判断错误
9
F9 动作决策错误
10
F10 工具执行失败
11
F11 状态校验失败
12
F12 输出不忠实
13
F13 安全违规
14
F14 成本或延迟超限

实践任务#

为 OrderFlow-Agent 构建测试集：

1
{
2
  "case_id": "C001",
3
  "user_query": "我的订单三天没发货，我要退款",
4
  "order_status": "paid",
5
  "logistics_status": "not_shipped",
6
  "expected_intent": "refund_request",
7
  "expected_policy_ids": ["R001"],
8
  "expected_responsible_party": "merchant",
9
  "expected_action": "refund",
10
  "expected_tool_sequence": ["query_order", "query_logistics", "search_policy", "create_refund", "verify_final_state"]
11
}

项目产出#

1
eval/
2
  datasets/golden.jsonl
3
  datasets/adversarial.jsonl
4
  datasets/regression.jsonl
5
  runner.py
6
  metrics.py
7
  trajectory_metrics.py
8
  failure_taxonomy.py
9
  report_generator.py

达标标准#

你能跑出完整报告：

1
Intent Accuracy
2
Policy Recall
3
Tool Call Accuracy
4
Trajectory Accuracy
5
Action Accuracy
6
End-to-End Success Rate
7
Avg Latency
8
Avg Cost
9
Failure Distribution
10
Regression Pass Rate

阶段 12：Agent 生产部署、AgentOps 与长期维护#

学习目标#

把 Demo 级 Agent 变成生产级 Agent：可部署、可监控、可灰度、可回滚、可持续优化。

生产架构#

1
Client
2
  ↓
3
API Gateway
4
  ↓
5
FastAPI Agent Service
6
  ↓
7
Model Gateway / LiteLLM
8
  ↓
9
LangGraph Workflow
10
  ↓
11
Tool / MCP Services
12
  ↓
13
Redis / PostgreSQL / Vector DB
14
  ↓
15
Observability + Eval + Audit + Failure Collector

核心能力#

能力	实现
队列	Redis Queue / Celery
缓存	query cache、retrieval cache、tool result cache
限流	Redis token bucket
熔断	模型或工具失败率过高自动切换
降级	强模型失败 → 弱模型 / 规则兜底 / 人工
多模型路由	cheap / reasoning / fast / fallback
Prompt 版本管理	prompt registry + version
Tool 版本管理	tool schema version
Skill 版本管理	skill registry + changelog
Memory 版本管理	memory schema + write policy
Eval as CI Gate	每次变更跑回归集
灰度发布	按用户/流量切分
反馈闭环	失败样本进入 eval dataset
AgentOps	trace、成本、延迟、失败率、回放

实践任务#

为 OrderFlow-Agent 增加：

Docker Compose；
Redis 缓存；
PostgreSQL 存储；
LiteLLM 模型网关；
trace_id；
span 级记录；
token / cost 统计；
失败样本自动沉淀；
eval CI gate。

项目产出#

1
docker-compose.yml
2
app/llm/router.py
3
app/observability/tracing.py
4
app/ops/failure_collector.py
5
app/ops/eval_ci_gate.py
6
docs/deployment.md
7
docs/maintenance_playbook.md

达标标准#

你能解释一次线上失败请求：

1
从哪里查日志
2
如何定位失败节点
3
如何复现
4
如何修复
5
如何加入回归测试
6
如何评估修复是否有效
7
如何灰度上线

附录：推荐资料入口#

官方与工程文档#

OpenAI Agents SDK: https://developers.openai.com/api/docs/guides/agents
OpenAI Structured Outputs: https://developers.openai.com/api/docs/guides/structured-outputs
OpenAI Function Calling: https://developers.openai.com/api/docs/guides/function-calling
OpenAI SFT: https://developers.openai.com/api/docs/guides/supervised-fine-tuning
OpenAI DPO: https://developers.openai.com/api/docs/guides/direct-preference-optimization
LangGraph Overview: https://docs.langchain.com/oss/python/langgraph/overview
LangGraph Durable Execution: https://docs.langchain.com/oss/python/langgraph/durable-execution
LangSmith Evaluation: https://docs.langchain.com/langsmith/evaluation
Ragas Agent Evaluation: https://docs.ragas.io/en/stable/tutorials/agent/
OpenTelemetry GenAI Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/
DSPy: https://dspy.ai/
LlamaIndex Agents / Workflows: https://developers.llamaindex.ai/python/framework/use_cases/agents/
AutoGen: https://microsoft.github.io/autogen/stable/
Model Context Protocol: https://modelcontextprotocol.io/docs/getting-started/intro
MCP Specification: https://modelcontextprotocol.io/specification/2025-06-18/
OWASP Top 10 for LLM Applications: https://owasp.org/www-project-top-10-for-large-language-model-applications/

经典论文关键词#

ReAct
Reflexion
Toolformer
Self-Refine
Plan-and-Solve
Generative Agents
Voyager
SWE-bench
AgentBench
WebArena
GAIA
τ-bench

建议长期跟踪#

OpenAI Developers
Anthropic Engineering
LangChain Blog
LlamaIndex Blog
Microsoft Research AutoGen / Agent Framework
Hugging Face Blog
Stanford NLP / DSPy
OWASP LLM Security

导读#

路线速览#

推荐阅读方式#

总目标：你最终要成为哪类 Agent 工程师#

整体学习主线#

学习原则#

最终技术栈建议#

核心工程栈#

前沿增强模块#

阶段总览#

配套文章索引#

第一部分：基础能力与核心范式#

阶段 0：前置基础补齐#

学习目标#

核心知识#

实践任务#

项目产出#

达标标准#

阶段 1：LLM 与 Prompt Engineering 基础#

学习目标#

核心知识#

实践任务#

项目产出#

达标标准#

阶段 2：Agent 基础范式与适用边界#

学习目标#

核心范式#

工程判断原则#

实践任务#

项目产出#

达标标准#

第二部分：Agent Harness 架构与核心模块#

阶段 3：Agent Harness 架构设计#

学习目标#

Harness 模块总览#

实践任务#

项目产出#

达标标准#

阶段 4：工具调用、MCP 与 Agent Skills#

学习目标#

核心知识#

实践任务#

项目产出#

达标标准#

阶段 5：Memory 与 Context Engineering#

学习目标#

核心知识#

Context Engineering 关键问题#

Memory Write Policy#

实践任务#

项目产出#

达标标准#

第三部分：RAG、规划、多 Agent 与微调#

阶段 6：Agentic RAG、GraphRAG 与 RuleRAG#

学习目标#

核心知识#

OrderFlow-Agent 中的 RuleRAG#

实践任务#

项目产出#

达标标准#

阶段 7：Planning、Reflection、Verifier 与自我修正#

学习目标#

核心机制#

设计原则#

实践任务#

项目产出#

达标标准#

阶段 8：Multi-Agent 系统与 Agent-to-Agent 协作#

学习目标#

核心模式#

OrderFlow-Agent 多 Agent 设计#

设计原则#

项目产出#

达标标准#

阶段 9：Agent 微调工程#

学习目标#

什么时候需要微调#

核心知识#

实践项目#

项目产出#