Agent 智能体开发全攻略：从 ReAct 到企业级架构

⚠️ 重要：本文包含 ReAct Agent（标准推理-行动循环） 、Supervisor Agent（多 Agent 协调与任务分发） 、Hierarchical Agent（层级代理与子任务拆解） 、Swarm Agent（无状态多 Agent 切换与 Handoff） 、Plan-and-Execute（先规划后执行与动态重规划） 、Reflection & Critique（自我反思与纠错） 、企业级 Agent 架构（路由→权限→工具→执行→审计） 等 Agent 智能体开发七大核心主题。

文中涉及的相关代码示例地址：https://github.com/m12305/Langchain-LangGraph-agent --- Langchain/LangGraph 学习项目

相关项目推荐：https://github.com/m12305/hello-FastAPI --- FastAPI 学习项目
前面我们学会了图、工具、记忆和 RAG，现在终于要把这一切组装成真正的 Agent。从单体的 ReAct 循环，到多 Agent 的协调、层级、交接、规划与反思，再到企业级的五层架构------本文带你走完 Agent 智能体开发的完整旅程。

文章目录

[Agent 智能体开发全攻略：从 ReAct 到企业级架构](#Agent 智能体开发全攻略：从 ReAct 到企业级架构)
- [一、ReAct Agent：LangGraph 标准推理-行动循环](#一、ReAct Agent：LangGraph 标准推理-行动循环)
- - [1.1 什么是 ReAct？](#1.1 什么是 ReAct？)
  - [1.2 两种创建方式](#1.2 两种创建方式)
- [二、Supervisor Agent：多 Agent 协调与任务分发](#二、Supervisor Agent：多 Agent 协调与任务分发)
- - [2.1 什么是 Supervisor Agent？](#2.1 什么是 Supervisor Agent？)
  - [2.2 完整 Supervisor Agent 架构](#2.2 完整 Supervisor Agent 架构)
- [三、Hierarchical Agent：层级代理与子任务拆解](#三、Hierarchical Agent：层级代理与子任务拆解)
- - [3.1 什么是 Hierarchical Agent？](#3.1 什么是 Hierarchical Agent？)
  - [3.2 三层层级架构](#3.2 三层层级架构)
- [四、Swarm Agent：无状态多 Agent 切换](#四、Swarm Agent：无状态多 Agent 切换)
- - [4.1 什么是 Swarm Agent？](#4.1 什么是 Swarm Agent？)
  - [4.2 Swarm vs Supervisor](#4.2 Swarm vs Supervisor)
  - [4.3 Handoff 机制实现](#4.3 Handoff 机制实现)
- [五、Plan-and-Execute Agent：先规划后执行](#五、Plan-and-Execute Agent：先规划后执行)
- - [5.1 ReAct vs Plan-and-Execute](#5.1 ReAct vs Plan-and-Execute)
  - [5.2 三阶段流水线](#5.2 三阶段流水线)
- [六、Reflection & Critique：自我反思与纠错 Agent](#六、Reflection & Critique：自我反思与纠错 Agent)
- - [6.1 什么是 Reflection Agent？](#6.1 什么是 Reflection Agent？)
  - [6.2 Reflection vs ReAct](#6.2 Reflection vs ReAct)
  - [6.3 三个角色的 Reflection 循环](#6.3 三个角色的 Reflection 循环)
  - [6.4 用 `Send()` 实现并行反思](#6.4 用 Send() 实现并行反思)
- [七、企业级 Agent 架构：路由 → 权限 → 工具 → 执行 → 审计](#七、企业级 Agent 架构：路由 → 权限 → 工具 → 执行 → 审计)
- - [7.1 五层企业 Agent 架构](#7.1 五层企业 Agent 架构)
  - [7.2 多模型编排策略](#7.2 多模型编排策略)
  - [7.3 五层架构骨架](#7.3 五层架构骨架)
- 八、全章知识地图
- 总结

一、ReAct Agent：LangGraph 标准推理-行动循环

1.1 什么是 ReAct？

ReAct = Reasoning (推理) + Acting (行动)，是 AI Agent 最经典的运作模式。

复制代码

┌──────────────────────────────────────────────┐
│              ReAct Agent 循环                 │
│   ┌──────────┐     ┌──────────┐              │
│   │  Thought  │────▶│  Action   │             │
│   │  (推理)    │◀────│  (行动)    │             │
│   └──────────┘     └──────────┘              │
│         │                ▼                    │
│         │         ┌──────────┐              │
│         └────────▶│Observation│              │
│                   │  (观察)    │              │
│                   └──────────┘              │
│   循环直到: 得到 Final Answer 或达到最大轮数    │
└──────────────────────────────────────────────┘

类比解决一道数学题：Thought "这题应该用勾股定理" → Action 拿草稿纸计算 → Observation 计算结果 → Thought "结果合理，可以写答案了" → Final Answer。

1.2 两种创建方式

方式	适用场景	灵活性
`create_react_agent()`	标准场景，快速原型	⭐⭐
手动构建 StateGraph	自定义逻辑，复杂控制流	⭐⭐⭐⭐⭐

方式一：create_react_agent() 一键创建

python 复制代码

from langgraph.prebuilt import create_react_agent

def add(a: int, b: int) -> int:
    """两数相加"""
    return a + b

# 两行代码创建一个 ReAct Agent
agent = create_react_agent(model, [add])
result = agent.invoke({"messages": [HumanMessage(content="3加5等于多少？")]})

方式二：手动构建 ReAct 图（理解底层）

python 复制代码

from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]

def should_continue(state: AgentState) -> str:
    """判断是否继续调用工具 ------ 循环的关键"""
    last_message = state["messages"][-1]
    if hasattr(last_message, "tool_calls") and last_message.tool_calls:
        return "tools"     # 有工具调用 → 去执行工具
    return END             # 没有 → 结束

def call_model(state: AgentState):
    response = model.bind_tools(tools).invoke(state["messages"])
    return {"messages": [response]}

builder = StateGraph(AgentState)
builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))   # 内置工具执行节点
builder.set_entry_point("agent")
builder.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
builder.add_edge("tools", "agent")   # 工具执行完 → 回到 agent 继续思考
graph = builder.compile()

🔗 关联：create_react_agent() 内部就是用 StateGraph + ToolNode 构建的；7.3 的 ReAct 循环就是这里的底层实现。
⚠️ 坑：① 无限循环 → 设置 recursion_limit 或最大轮数；② 工具描述不清 → 模型不调用或乱调，每个工具必须有清晰 docstring；③ 忘记 .bind_tools(tools) → 模型不知道有哪些工具；④ System Prompt 冲突 → 用 SystemMessage 明确角色和规则。

二、Supervisor Agent：多 Agent 协调与任务分发

2.1 什么是 Supervisor Agent？

类比项目经理：Supervisor Agent 自己不干活，但负责把任务分配给合适的 Worker。

复制代码

┌─────────────────────────────────────────────────────┐
│                 Supervisor Agent                     │
│                  (项目经理)                           │
│          ┌────────┼────────┼────────┐               │
│          ▼        ▼        ▼        ▼               │
│     ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐            │
│     │ 搜索  │ │ 计算  │ │ 代码  │ │ 数据  │            │
│     │Worker │ │Worker │ │Worker │ │Worker │            │
│     └──────┘ └──────┘ └──────┘ └──────┘            │
│          │        │        │        │               │
│          └────────┼────────┼────────┘               │
│                   ▼                                 │
│              Supervisor (继续分配或结束)              │
└─────────────────────────────────────────────────────┘

核心机制 ：Supervisor 是一个路由函数，根据当前状态决定下一个 Worker。实际项目中，Supervisor 本身也是一个 LLM 调用，让模型决定路由。

python 复制代码

# Supervisor 的 System Prompt ------ 让模型决定路由
SUPERVISOR_PROMPT = """你是任务协调者。根据用户需求，决定下一步行动:

可选 Worker:
- SEARCH: 需要搜索信息时
- CALCULATE: 需要计算时
- CODE: 需要编写代码时
- FINISH: 任务完成时

请只回复 Worker 名称。"""

2.2 完整 Supervisor Agent 架构

python 复制代码

class MultiAgentState(TypedDict):
    messages: Annotated[list, add_messages]
    next: str  # Supervisor 决定的下一个 Worker

def supervisor_node(state: MultiAgentState):
    """Supervisor 分析状态，决定下一步"""
    response = model.invoke([
        SystemMessage(content=SUPERVISOR_PROMPT),
        HumanMessage(content=f"当前对话: {state['messages']}\n下一步?"),
    ])
    return {"next": response.content.strip()}

def supervisor_router(state: MultiAgentState) -> str:
    """根据 Supervisor 的决策进行路由"""
    if state["next"] == "FINISH":
        return END
    return state["next"].lower()  # 返回 Worker 名

builder = StateGraph(MultiAgentState)
builder.add_node("supervisor", supervisor_node)
builder.add_node("search_worker", search_worker)
builder.add_node("math_worker", math_worker)
builder.set_entry_point("supervisor")
builder.add_conditional_edges("supervisor", supervisor_router, {
    "search": "search_worker", "math": "math_worker", END: END,
})
# 每个 Worker 完成后回到 Supervisor
builder.add_edge("search_worker", "supervisor")
builder.add_edge("math_worker", "supervisor")

🔗 关联：本质是 7.2 条件路由 + 7.6 子图嵌套的组合；每个 Worker 内部可以是完整的 ReAct Agent (9.1)；9.3 Hierarchical Agent 是 Supervisor 的层级扩展。
⚠️ 坑：① 死循环（反复调用同一 Worker）→ 添加 round_limit 或 FINISH 强制退出；② 路由错误 → 优化 Supervisor 的 System Prompt，给更多示例；③ Worker 间状态丢失 → State 中 add_messages 自动累积所有消息；④ Worker 能力重叠 → 在 Prompt 中明确边界、加优先级规则。

三、Hierarchical Agent：层级代理与子任务拆解

3.1 什么是 Hierarchical Agent？

类比公司管理层级：CEO Agent 拆解战略 → Manager Agent 分配具体任务 → Tools 执行具体操作。

复制代码

               ┌─────────────┐
               │  CEO Agent  │  ← 顶层: 理解目标，拆解战略
               └──────┬──────┘
          ┌───────────┼───────────┐
          ▼           ▼           ▼
    ┌─────────┐ ┌─────────┐ ┌─────────┐
    │ Manager │ │ Manager │ │ Manager │  ← 中层: 分配具体任务
    └────┬────┘ └────┬────┘ └────┬────┘
      ┌──┴──┐    ┌──┴──┐    ┌──┴──┐
      ▼     ▼    ▼     ▼    ▼     ▼
    工具  工具  工具  工具  工具  工具       ← 底层: 执行具体操作

类比建筑工地：总工程师"建一栋楼"拆解为地基/框架/装修；结构工程师负责地基，再分配挖掘/浇筑/测量；工人执行具体动作。

3.2 三层层级架构

python 复制代码

# 顶层: CEO Agent ------ 拆解任务（输出结构化 JSON 任务单）
CEO_SYSTEM_PROMPT = """你是项目总管。将用户需求拆解为子任务列表。

输出格式 (JSON):
{
    "subtasks": [
        {"id": "1", "title": "...", "assignee": "researcher", "detail": "..."},
        {"id": "2", "title": "...", "assignee": "analyst",   "detail": "..."},
    ]
}
可用部门:
- researcher: 搜索和收集信息
- analyst: 分析和总结数据
"""

def ceo_node(state):
    """CEO: 拆解任务"""
    response = model.invoke([
        SystemMessage(content=CEO_SYSTEM_PROMPT),
        HumanMessage(content=state["user_request"]),
    ])
    plan = json.loads(response.content)
    return {"subtasks": plan["subtasks"], "current_subtask": 0}

# 中层: 每个部门一个节点，有自己的工具集
builder = StateGraph(HierarchicalState)
builder.add_node("ceo", ceo_node)
builder.add_node("researcher", create_manager("researcher"))
builder.add_node("analyst", create_manager("analyst"))

# 路由: CEO → 各个 Manager → 回到 CEO 审查
builder.add_conditional_edges("ceo", route_to_manager, {
    "researcher": "researcher", "analyst": "analyst",
    "review": "ceo", "FINISH": END,
})
# Manager 完成后回 CEO
builder.add_edge("researcher", "ceo")
builder.add_edge("analyst", "ceo")

关键设计决策：任务传递（发文本 vs 结构化任务单）、结果汇总（直接返回 vs 写共享 State）、工具分配（共享 vs 按角色隔离）、出错处理（向上报告 vs 重试 N 次再报告）。

🔗 关联：本质是 7.6 子图嵌套 + 9.2 Supervisor 模式的层级化；每一层内部都可以是 ReAct Agent (9.1)；是企业级架构 (9.7) 的天然实现方式。
⚠️ 坑：① 拆解粒度太细/太粗 → 给 CEO Prompt 添加粒度示例；② 层级过深（消息延迟、信息失真）→ 一般不超过 3 层；③ 下级自治过度（跑偏）→ 每层增加校验节点；④ 汇总信息丢失 → 要求结构化的汇总格式。

四、Swarm Agent：无状态多 Agent 切换

4.1 什么是 Swarm Agent？

Swarm 源自 OpenAI 的实验性项目，核心思想：

Agent 之间通过"交接 (Handoff)"来切换，每个 Agent 是无状态的，处理完就交出去。

类比医院分诊 ：前台分诊护士判断你该去哪个科室 → 把你交给内科医生 → 医生发现问题超范围 → 再交给外科医生。每次交接都是完整的控制权转移，而非任务分配。

4.2 Swarm vs Supervisor

维度	Swarm	Supervisor
控制模式	接力棒（谁拿到谁负责）	遥控器（一直有人指挥）
状态管理	每次交接传递上下文	共享 State 中所有可见
适用场景	对话分流、客服切换	复杂任务分解、多步协作
消息复杂度	低（只需传当前 context）	高（需要共享完整历史）

4.3 Handoff 机制实现

python 复制代码

# Handoff 本质上是一个特殊的 "工具"
def create_handoff_tool(agent_name: str):
    """创建一个交接工具"""
    @tool
    def handoff(context: str) -> str:
        f"""将对话移交给 {agent_name}。传递上下文: {context}"""
        return f"已移交给 {agent_name}"
    return handoff

# 每个 Agent 有一组业务工具 + handoff 工具
triage_tools = [handoff_to_travel, handoff_to_support]  # 分诊端的交接工具
travel_tools = [search_flights, book_flight, handoff_to_triage]  # 旅行端业务 + 可返回

# 检测是否发生了 handoff
def detect_handoff(state) -> str:
    """检查最后一个工具调用是否是 handoff"""
    last_msg = state["messages"][-1]
    if hasattr(last_msg, "tool_calls"):
        for tc in last_msg.tool_calls:
            if tc["name"].startswith("handoff_to_"):
                target = tc["name"].replace("handoff_to_", "")
                return target  # 返回目标 Agent 名称
    return None  # 无 handoff，继续

# 构建切换图
builder = StateGraph(AgentState)
builder.add_node("triage", triage_agent)
builder.add_node("travel", travel_agent)
builder.add_node("support", support_agent)
builder.set_entry_point("triage")
builder.add_conditional_edges("triage", detect_handoff, {
    "travel": "travel", "support": "support", END: END,
})
# 同理为其他 agent 添加 handoff 路由

🔗 关联：底层仍是 LangGraph 的条件边路由；Handoff 工具本质是特殊的 Tool 调用 (6.3)；比 Supervisor (9.2) 更轻量，适合对话分流场景。
⚠️ 坑：① 无限交接（A→B→A→B）→ 设 max_handoffs 上限；② 上下文丢失 → 在 handoff 参数中传足够上下文；③ 交接判断失误 → 优化 handoff 工具描述；④ 循环交接检测 → 维护已访问 Agent 的集合。

五、Plan-and-Execute Agent：先规划后执行

5.1 ReAct vs Plan-and-Execute

复制代码

ReAct (边想边做):                Plan-and-Execute (先想再做):
Thought → Action → Obs            Plan: 步骤1, 步骤2, 步骤3
Thought → Action → Obs                      │
...                                        ▼
每步都在"想下一步"               Execute 步骤1 → 结果1
优势: 灵活应对变化               Execute 步骤2 → 结果2
劣势: 容易跑偏，缺乏全局观        Re-plan? (需要的话调整)
                                优势: 全局最优，不迷路
                                劣势: 计划可能一开始就错了

类比旅行规划：ReAct 是"到机场 → 看下一班飞哪 → 飞过去 → 再决定去哪"；Plan-and-Execute 是"先做攻略 (Day1 故宫, Day2 长城...) → 每天按计划走 → 下雨了就调整"。

什么时候用哪个：写技术文章/数据分析报表/代码审查 → Plan-and-Execute（结构重要）；网上查资料/与用户对话 → ReAct（不确定性强）。

5.2 三阶段流水线

python 复制代码

# ==== 阶段1: Planner (生成计划) ====
PLANNER_PROMPT = """你是一个任务规划专家。将目标拆解为可执行的步骤。
输出格式 (JSON):
{
    "plan": [
        {"step": 1, "action": "搜索相关资料", "tool": "search"},
        {"step": 2, "action": "提取关键数据", "tool": "extract"},
        {"step": 3, "action": "生成分析报告", "tool": "write"},
    ]
}
注意:
- 每个步骤必须能用指定的 tool 完成
- 步骤之间可以有依赖关系
"""

def planner_node(state):
    """生成计划"""
    response = model.invoke([
        SystemMessage(content=PLANNER_PROMPT),
        HumanMessage(content=state["objective"]),
    ])
    plan = json.loads(response.content)
    return {"plan": plan["plan"], "current_step": 0, "results": []}

# ==== 阶段2: Executor (逐步执行) ====
def executor_node(state):
    """执行当前步骤"""
    step = state["plan"][state["current_step"]]
    tool = get_tool_by_name(step["tool"])
    result = tool.invoke(step["action"])
    return {"results": [result]}

# ==== 阶段3: Replanner (动态重规划) ====
def replanner_node(state):
    """检查是否需要调整计划"""
    if all_steps_done(state):
        return {"next": "FINISH"}
    response = model.invoke([...])   # 用 LLM 评估是否需要重规划
    if response.needs_replan:
        return {"plan": response.new_plan, "current_step": 0}
    else:
        return {"current_step": state["current_step"] + 1}

# 图结构: planner → executor → replanner（决定继续/重规划/结束）

🔗 关联：可以内嵌 ReAct Agent (9.1) 作为 Executor；Replanner 本质上是一个轻量级 Supervisor (9.2)；适合作为 Hierarchical Agent (9.3) 的顶层策略。
⚠️ 坑：① 计划过于抽象（"分析数据"无法执行）→ Prompt 中要求具体工具名和参数；② 不做重规划（第1步失败后面全废）→ 每步执行后都走 Replanner 检查；③ 计划太死板 → Replanner 看到中间结果后更新计划；④ 步骤依赖不明确 → 在 Plan JSON 中标记 depends_on。

六、Reflection & Critique：自我反思与纠错 Agent

6.1 什么是 Reflection Agent？

Reflection = 自我反思 。Agent 不仅做事，还会审视自己的输出，发现问题后自动修正。

复制代码

Generator (生成) → Critique (审视) → Revise (修正) → (再审视)
    类比: 写完文章 → 自己读一遍 → 发现写得不好 → 改

类比考试检查：Generate 做完一道大题 → Critique "第二步的计算对了吗？单位换算了吗？" → Revise 发现错误、重新计算、得出正确答案。

6.2 Reflection vs ReAct

维度	ReAct	Reflection
核心循环	思考→行动→观察	生成→审视→修正
关注点	外部工具调用	内部输出质量
纠错方式	通过工具结果反馈	通过自我审查发现
典型场景	搜索、计算、API 调用	写作、代码生成、翻译

两者常组合使用：ReAct 负责与外部的交互，Reflection 负责内部质量控制。

6.3 三个角色的 Reflection 循环

python 复制代码

# ===== Generator: 生成内容 =====
def generator_node(state):
    response = model.invoke([
        SystemMessage(content="你是一个内容生成者。根据需求生成回答。"),
        HumanMessage(content=state["task"]),
    ])
    return {"draft": response.content, "iteration": state.get("iteration", 0) + 1}

# ===== Critic: 审视内容（输出结构化 JSON 评分）=====
CRITIC_PROMPT = """你是严格的质量审查员。审查以下内容，指出问题。
审查维度:
1. 准确性: 事实是否正确？
2. 完整性: 是否遗漏关键信息？
3. 逻辑性: 推理是否严谨？
4. 清晰度: 表达是否清楚？
输出 JSON:
{ "score": 1-10, "issues": ["问题1", "问题2"], "needs_revision": true/false }
"""

def critic_node(state):
    response = model.invoke([
        SystemMessage(content=CRITIC_PROMPT),
        HumanMessage(content=f"审查以下内容:\n{state['draft']}"),
    ])
    return {"critique": json.loads(response.content)}

# ===== Revisor: 根据意见修正 =====
def revisor_node(state):
    issues = state["critique"]["issues"]
    response = model.invoke([
        HumanMessage(content=f"根据审查意见:{issues}\n修改内容:\n{state['draft']}"),
    ])
    return {"draft": response.content}

# 图结构: generator → critic → (revise → critic) → FINISH
builder = StateGraph(ReflectionState)
builder.add_node("generator", generator_node)
builder.add_node("critic", critic_node)
builder.add_node("revisor", revisor_node)
builder.set_entry_point("generator")
builder.add_edge("generator", "critic")
builder.add_conditional_edges("critic", decide_after_critique, {
    "revise": "revisor",   # 需要修改
    "FINISH": END,         # 质量合格，结束
})
builder.add_edge("revisor", "critic")  # 修改后再审

6.4 用 `Send()` 实现并行反思

python 复制代码

from langgraph.graph import Send

def continue_to_critique_dimensions(state):
    """生成多个并行的 Critic 任务（多维度审视）"""
    dimensions = ["accuracy", "completeness", "clarity", "logic"]
    return [
        Send("dimension_critic", {"dimension": d, "draft": state["draft"]})
        for d in dimensions
    ]

def dimension_critic_node(state):
    """每个维度一个独立的审视者"""
    response = model.invoke([
        HumanMessage(content=f"从'{state['dimension']}'维度审查:\n{state['draft']}")
    ])
    return {"critiques": [{state["dimension"]: response.content}]}

def aggregate_critiques(state):
    """将并行审视的结果汇总（合并、去重、排序）"""
    ...

🔗 关联：Send() API 是 LangGraph 实现并行反思的关键 (7.6)；Reflection 可以嵌入 ReAct Agent (9.1) 的工具调用后；在企业级架构 (9.7) 中 Reflection 是质量保障层。
⚠️ 坑：① 过度反思（无限改下去）→ max_iterations 硬限制；② Critic 太宽松 → Prompt 强调"严格"给扣分示例；③ Critic 太苛刻 → 给评分标准，>=7 分就放行；④ 修改引入新错误 → 每轮只改 Critic 指出的问题；⑤ 成本翻倍（一次反思 3 次 LLM 调用）→ 简单任务跳过 Reflection。

七、企业级 Agent 架构：路由 → 权限 → 工具 → 执行 → 审计

7.1 五层企业 Agent 架构

类比银行柜台系统：入口层（拿号排队、身份验证）→ 路由层（分到对公/对私/理财窗口）→ 工具层（柜员能操作的内部系统）→ 执行层（按流程办理业务）→ 审计层（所有操作有记录、日终盘账）。

复制代码

┌──────────────────────────────────────────────────────────┐
│                    📨 入口层 (Gateway)                     │
│  API Gateway / 负载均衡 / 认证鉴权 / 速率限制              │
├──────────────────────────────────────────────────────────┤
│                    🧭 路由层 (Router)                      │
│  意图识别 → 模型选择 → 工具集选择 → 权限校验               │
├──────────────────────────────────────────────────────────┤
│                    🔧 工具层 (Tool Layer)                  │
│  工具注册中心 / 工具版本管理 / 调用审计 / 超时控制         │
├──────────────────────────────────────────────────────────┤
│                    🚀 执行层 (Execution)                    │
│  Agent 图执行 / Checkpoint 管理 / 人机协同 / 重试         │
├──────────────────────────────────────────────────────────┤
│                    📊 审计层 (Audit)                       │
│  日志 / 追踪 / 成本核算 / 质量评估 / 合规审计             │
└──────────────────────────────────────────────────────────┘

7.2 多模型编排策略

不要所有任务都用 GPT-4！ 企业级架构会根据任务复杂度选择不同模型：

任务类型	推荐模型	原因
意图识别 / 路由	gpt-4o-mini / deepseek-chat	简单分类，不需要大模型
摘要 / 翻译	gpt-4o-mini	常规 NLP 任务
复杂推理 / 规划	gpt-4o / claude-sonnet-5	需要强推理能力
代码生成	claude-sonnet-5 / gpt-4o	代码质量要求高
安全审核	gpt-4o	不能出错

7.3 五层架构骨架

python 复制代码

# 1. 入口层: API 入口 + 认证 + 限流
class AgentGateway:
    async def handle_request(self, request):
        user = await self.auth.verify(request.api_key)   # 鉴权
        await self.limiter.check(user.id, user.tier)     # 限流
        return await self.router.route(request, user)    # 转发到路由层

# 2. 路由层: 意图识别 + 模型选择矩阵 + 权限校验
class AgentRouter:
    MODEL_MATRIX = {
        ("search", "low"): "gpt-4o-mini",
        ("search", "high"): "gpt-4o",
        ("code", "medium"): "claude-sonnet-5",
        # ... 更多 (intent, complexity) → model 组合
    }
    def route(self, request, user):
        intent = self.light_model.invoke(ROUTE_PROMPT.format(msg=request.message))  # 轻量模型做意图识别
        model_key = (intent["intent"], intent["complexity"])
        selected_model = self.MODEL_MATRIX.get(model_key, "gpt-4o-mini")
        if intent["intent"] in user.restricted_intents:
            raise PermissionError(f"用户无权使用 {intent['intent']}")
        return self.execute(request, intent, selected_model, user)

# 3. 工具层: 工具注册中心 + 版本 + 权限
class ToolRegistry:
    def register(self, tool, version, permissions): ...
    def get_for_user(self, user) -> list:
        """只返回用户有权使用的工具"""
        return [info.tool for info in self._tools.values()
                if all(p in user.permissions for p in info.required_permissions)]

# 4. 执行层: Agent 图 + Checkpoint + 重试
class AgentExecutor:
    async def execute(self, agent_graph, state, config):
        for attempt in range(self.max_retries):          # 最多重试 N 次
            try:
                return await agent_graph.ainvoke(state, config)
            except Exception as e:
                if attempt == self.max_retries - 1:
                    raise
                saved_state = await agent_graph.aget_state(config)  # 从最近 checkpoint 恢复
                state = saved_state.values

# 5. 审计层: 日志 + 追踪 + 成本核算
class AuditLogger:
    def log(self, event):
        record = {
            "user_id": event.user_id, "session_id": event.session_id,
            "action": event.action, "model": event.model,
            "tokens": event.token_count,
            "cost": self.calculate_cost(event.model, event.token_count),  # 成本核算
            "duration_ms": event.duration_ms,
        }
        self.storage.append(record)   # 写入数据库 / Kafka / 日志文件

完整请求流程 ：入口层接收 → 路由层识别意图选模型 → 工具层按用户权限取工具 → 执行层 create_react_agent(model.bind_tools(tools), tools) 运行 → 审计层记录日志、token 与成本。

🔗 关联：LangSmith (12.1) 可作为审计层的追踪方案；LangServe (13.1) 可作为入口层的 API 框架；工具层依赖 LangChain Tool 体系（阶段 6）；执行层依赖 LangGraph（阶段 7）。
⚠️ 坑：① 单点瓶颈（一个慢 Worker 拖慢整个系统）→ 异步 + 超时 + 降级；② 工具权限泄露（用户 A 调用了只有 B 能用的工具）→ 工具层必须做权限校验；③ 成本失控（某用户滥用导致账单爆炸）→ 每用户设 daily budget / rate limit；④ 审计缺失 → 每层都要记录审计日志；⑤ 过度工程化（简单场景也套五层架构）→ 按需裁剪：小项目可合并层级。

八、全章知识地图

复制代码

                  ┌─────────────────────────────────────────┐
                  │        Agent 智能体开发知识体系           │
                  └─────────────────────────────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │                           │                           │
         ▼                           ▼                           ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   单体 Agent     │         │   多 Agent 协作  │         │   工程与生产      │
│                 │         │                 │         │                 │
│ • ReAct 循环     │         │ • Supervisor    │         │ • Plan-and-      │
│ • create_react_  │         │   协调分发       │         │   Execute 规划   │
│   agent()        │         │ • Hierarchical  │         │ • Reflection    │
│ • ToolNode       │         │   层级拆解       │         │   自我反思       │
│ • System Prompt  │         │ • Swarm Handoff │         │ • 五层企业架构    │
└─────────────────┘         └─────────────────┘         └─────────────────┘
         │                           │                           │
         └───────────────────────────┼───────────────────────────┘
                                     │
                  ┌──────────────────┴──────────────────┐
                  │           生产级能力栈                │
                  │                                     │
                  │  • 多模型编排（按复杂度选模型）         │
                  │  • 角色化工具权限 + 工具注册          │
                  │  • Checkpoint 重试 + 人机协同         │
                  │  • 审计日志 + 成本核算                │
                  └─────────────────────────────────────┘

总结

模块	核心洞察
ReAct Agent	思考→行动→观察循环；`create_react_agent()` 一键创建，手写 StateGraph 理解底层
Supervisor Agent	项目经理式协调；LLM 作为路由函数，Worker 完成回 Supervisor
Hierarchical Agent	CEO→Manager→Tool 层级拆解；结构化任务单传递，层级不超过 3 层
Swarm Agent	接力棒式 Handoff 交接；无状态、轻量，适合对话分流
Plan-and-Execute	先规划后执行；Planner→Executor→Replanner 三阶段，动态重规划
Reflection & Critique	生成→审视→修正；`Send()` 实现多维度并行反思；ReAct 管外部、Reflection 管内部质量
企业级架构	路由→权限→工具→执行→审计五层；多模型编排 + 审计成本；按需裁剪不过度工程

从单体的 ReAct 循环，到 Supervisor / Hierarchical / Swarm 的多 Agent 协作，再到 Plan-and-Execute 与 Reflection 的高级模式，最后落到企业级五层架构------你已经掌握了完整构建 Agent 智能体的能力 🚀

本文基于"AI Agent 学习项目"第 9 阶段（Agent 智能体开发）整理，覆盖 9.1 ReAct Agent、9.2 Supervisor Agent、9.3 Hierarchical Agent、9.4 Swarm Agent、9.5 Plan-and-Execute、9.6 Reflection & Critique、9.7 企业级 Agent 架构七个章节。

Agent 智能体开发全攻略：从 ReAct 到企业级架构