本系列与 Agent-00 自学导航 并列：Agent-00 偏案例因果链；Agent-10 偏单点技术掌握。示例优先绑定 本仓库 agent/、mcp/，并采用 LangChain / LangGraph 等成熟框架，而非重写 toy 实现。
段末注释：Agent 在此指由大语言模型（large language model，LLM）驱动、可调用工具并完成多步任务的智能体应用。
本仓库框架映射
| Agent-10 | 本仓库模块 | 成熟框架 |
|---|---|---|
| 01 结构化输出 | agent/planner/llm.py |
LangChain with_structured_output(ResearchPlan) |
| 02 Tool Loop | agent/uni/runtime/tool_loop.py |
OpenAI tool_calls + 自研 ReAct（AgentRuntime 统一入口） |
| 03 MCP | mcp/mcp_*、uni/mcp_client/stdio.py |
FastMCP + 官方 MCP Python SDK |
| 04 配置 Agent | agent/uni/runtime/agent_runtime.py |
YAML + Skills（编排外置 LangGraph） |
| 05 HTTP/SSE | agent/uni/api/、orchestrator/streaming.py |
FastAPI + LangGraph stream_mode=updates |
| 06 Hybrid RAG | mcp/mcp_rag_gene、agent/literature/ |
FastMCP Store + AgentRuntime tool loop |
| 07 Graph RAG | mcp/mcp_rag_methods、agent/method_kb/ |
JSON 图 Store + AgentRuntime |
| 08 HITL | orchestrator/graph.py、streaming.py |
LangGraph interrupt_before + Checkpointer |
| 09 编排 | agent/orchestrator/ |
LangGraph StateGraph；build_pipeline（线性）+ build_pipeline_loop（审核回环） |
| 10 长任务 | agent/analyst/、mcp/mcp_argo_sirna/ |
MCP submit/status/wait + HITL 闸门 |
| 11 报告 | agent/reporter/、graph.synthesize_with_langchain |
模板合成 + LangChain ChatModel |
推荐阅读顺序
| 序号 | 文档 | 核心问题 |
|---|---|---|
| 01 | LLM 调用与结构化输出 | 如何让模型稳定按格式回答？ |
| 02 | Tool Calling 与 Agent 执行循环 | 如何让模型「动手」而不只聊天？ |
| 03 | MCP 协议与 Server 开发 | 工具如何标准化、跨 Host 复用？ |
| 04 | 配置驱动 Agent 与人格 Skills | 多角色如何低成本切换与维护？ |
| 05 | FastAPI 与 Agent 流式服务 | 如何把 Agent 暴露给 Web/客户端？ |
| 06 | 混合检索 RAG | 私有知识如何检索并减少胡编？ |
| 07 | 图数据库与 Graph RAG | 关系型知识如何用图表达与问答？ |
| 08 | 人在回路 HITL | 高风险动作如何让人确认？ |
| 09 | 多 Agent 编排与 LangGraph | 多角色如何显式协作与恢复？ |
| 10 | 长任务与外部计算调度 | 分钟/小时级任务如何接入 Agent？ |
| 11 | 引用约束生成与报告合成 | 报告如何强制可追溯、可审计？ |
与 Agent-00 阶段（S0–S10）的大致对应
| Agent-00 阶段 | 可优先阅读的 Agent-10 |
|---|---|
| S0–S1 裸问答 / 约束输出 | 01 |
| S2 工具 | 02 |
| S3 MCP | 03 |
| S4 多角色 | 04 |
| S5 图编排 | 09、08 |
| S6 RAG | 06、07 |
| S9 HTTP 服务 | 05 |
| 长任务 / 报告 | 10、11 |
此为学习映射，非工程里程碑绑定。
每篇文档结构约定
- 行业常见问题
- 该技术如何解决
- 核心原理
- 典型实现方式与代码示例
- 替代方案与优缺点
- 自检题
- 延伸阅读
代码示例约定
第 4 节优先 本仓库真实模块摘录 + CLI/API 验收；禁止用 stdlib 重写 LangGraph/LangChain/MCP 已有能力。
| 要求 | 说明 |
|---|---|
| 框架绑定 | LangChain / LangGraph / FastMCP / MCP SDK 与本仓库 agent/、mcp/ 对齐 |
| RAG 类 | Part A 索引构建 + Part B AgentRuntime tool loop |
| 编排/HITL | 必须引用 agent/orchestrator/ 的 StateGraph、Checkpointer、interrupt_before |
| 验收 | 给出 uv run python -m agent.*.cli ... 或 Web API 路径 |
| 独立 demo | 仅当仓库无对应模块时允许，且须标注为补充而非主路径 |
| 类属性注释 | 凡文档中出现 class / Pydantic / TypedDict 声明，须对每个会在运行时生效的字段加注释，说明被谁读取、起什么作用 |