第一章：AI Agent 框架总论与四大编排范式

本章目标：建立”什么是 Agent 框架”的全局认知，理解四种编排范式的设计动机和适用边界。

1.1 什么是 AI Agent？

在讨论框架之前，先对齐一个最基本的定义。

AI Agent = LLM + 工具 + 循环

一个普通的 LLM 调用是”问一个问题，得到一个回答”——单轮、无副作用。而 Agent 加了两个东西：

1. 工具（Tools）：让 LLM 不只是”说”，还能”做”——搜索网页、执行代码、读写文件、调用 API
2. 循环（Loop）：让 LLM 不只是”做一次”，而是”做完看看结果，决定要不要继续做”

日常类比：普通 LLM 像一个只能说话的顾问——你问他建议，他给你方案，但他不能亲自动手。Agent 像一个能动手的实习生——你给他一个目标，他会想办法（思考）、动手做（工具）、看看做对没（观察）、不对就再来一轮。

这个”思考→行动→观察→循环”的模式就是著名的 ReAct 模式（Reasoning + Acting），几乎所有 Agent 框架的核心执行循环都是它的变体。

1.2 为什么需要 Agent 框架？

你可能会想：既然 Agent 的本质就是”调 LLM + 调工具 + 循环”，我自己写 50 行代码不就搞定了？

是的，一个最简单的 Agent 确实可以 50 行搞定：

# 最朴素的 Agent 循环（伪代码）
messages = [{"role": "user", "content": task}]
while True:
    response = call_llm(messages, tools=my_tools)
    if response.has_tool_calls():
        for tool_call in response.tool_calls:
            result = execute_tool(tool_call)
            messages.append({"role": "tool", "content": result})
    else:
        print(response.text)
        break

但当你要真正用在生产环境时，问题就来了：

Agent 框架就是为了解决这些”循环之外”的工程问题。 不同框架选择解决不同子集的问题，这就是它们的差异化来源。

1.2.5 Agent 框架的核心抽象层

所有成熟的 Agent 框架——不管是哪个范式——都需要处理五个层面的问题。我们称之为”Agent 框架五层模型”：

┌─────────────────────────────────────────────────────┐
│              可观测层（Observability）                  │
│   Tracing / Metrics / Logging / Token Accounting     │
├─────────────────────────────────────────────────────┤
│              编排层（Orchestration）                    │
│   循环控制 / 状态管理 / 多Agent协调 / 人机协作         │
├─────────────────────────────────────────────────────┤
│              记忆层（Memory）                          │
│   短期记忆(对话历史) / 长期记忆(向量库) / 工作记忆     │
├─────────────────────────────────────────────────────┤
│              工具层（Tools）                           │
│   工具注册 / 参数验证 / 执行沙箱 / 结果格式化          │
├─────────────────────────────────────────────────────┤
│              模型层（Model）                           │
│   LLM调用 / 流式响应 / 重试降级 / 多模型切换          │
└─────────────────────────────────────────────────────┘

模型层是最底层，负责与 LLM 的直接交互。它要处理的核心问题包括：统一不同供应商（OpenAI / Anthropic / 本地模型）的 API 差异、管理 API Key 和鉴权、实现流式响应的解析、在调用失败时自动重试或降级到备用模型。日常类比：模型层是快递公司——不管你用顺丰还是中通，包裹（请求）最终都要送达（得到回复）。如果一家快递爆仓了，自动换一家。

工具层负责管理 Agent 能使用的所有外部能力。核心问题：工具如何注册（声明式 vs 编程式）、工具的输入参数如何验证（JSON Schema / Pydantic）、工具执行是否需要沙箱隔离（比如代码执行工具不能 rm -rf /）、工具返回结果如何格式化为 LLM 能理解的文本。不同框架对工具层的处理差异巨大：LangChain 用 @tool 装饰器自动从函数签名生成 schema；tRPC-Agent 用 Go 的 interface 强制类型安全；CrewAI 直接复用 LangChain 的工具生态。

记忆层解决”Agent 怎么记住之前发生的事”。三种记忆类型：

• 短期记忆（Working Memory）：当前对话的消息列表，随 context window 增长而增长
• 长期记忆（Long-term Memory）：跨会话的持久化知识，通常用向量数据库存储
• 工作记忆（Scratchpad）：Agent 在执行过程中的中间状态和草稿

记忆层的关键挑战是 context window 管理——当对话历史超过模型的 token 限制时，如何智能地压缩或裁剪，同时不丢失关键信息。

编排层是各框架差异化最大的地方，也是本章重点讨论的”四大范式”所在。它决定了 Agent 的执行逻辑如何组织：是链式串联、图状流转、角色分工还是微服务调用。编排层还包括循环控制（什么时候停？最多跑几轮？）、状态管理（节点间如何传递数据？）、多 Agent 协调（谁先谁后？并行还是串行？）以及人机协作（哪些步骤需要人类审批？）。

可观测层是生产环境的刚需。它回答”Agent 在干什么？干了多久？花了多少钱？出了什么错？”这些运营问题。典型能力包括：分布式链路追踪（一次请求经过了哪些节点）、指标统计（延迟 P99 / Token 消耗 / 成功率）、结构化日志（每一步的输入输出）、成本核算（每次对话花了多少钱）。不同框架对可观测层的支持程度差异极大：LangChain 需要购买 LangSmith 商业服务；tRPC-Agent 直接继承 tRPC 的 OpenTelemetry 集成；CrewAI 基本没有内建可观测能力。

框架选型的本质就是看：这五层中，哪些层是你的痛点？哪个框架在这些层上的方案最适合你？

1.3 四大编排范式

2022-2026 年间涌现的 Agent 框架，按照它们对”Agent 怎么组织协作”这个核心问题的回答，可以分为四大流派：

范式一：管道流派（Pipeline）—— LangChain

核心信念：万物皆 Runnable，用管道组合。

chain = prompt | llm | output_parser
result = chain.invoke({"question": "什么是 Agent?"})

日常类比：Unix 命令的管道 cat file | grep error | wc -l。每个命令只做一件事，用 | 串起来完成复杂任务。数据从左到右流过每一站。

适用场景：线性的、确定性的数据处理流。比如”检索文档→生成摘要→格式化输出”。

局限：无法表达循环（”如果质量不够就返工”）、无法表达条件分支（”根据问题类型走不同路径”）。一旦需要这些，LangChain 就把你推给 LangGraph。

Runnable 接口实现原理：invoke / stream / batch

LangChain 的管道之所以能用 | 操作符串联，核心在于 Runnable Protocol——所有组件统一实现同一套接口：

# LangChain 管道骨架（≤20 行）—— 核心是 | 操作符串联 Runnable
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_template("用一句话解释{concept}")  # Runnable
llm = ChatOpenAI(model="gpt-4o")                                    # Runnable
parser = StrOutputParser()                                           # Runnable

chain = prompt | llm | parser          # | 创建 RunnableSequence（串行）
result = chain.invoke({"concept": "微服务"})  # invoke / stream / batch 三种调用

Runnable 的威力在于组合性：你可以像搭乐高一样把任意 Runnable 拼接——串行（Sequence）、并行（Parallel）、条件选择（Branch）、透传（Passthrough）。但这种组合性是线性世界里的——数据只能向前流，不能回头。一旦你需要”如果输出不满意就回到上一步重做”，管道模型就力不从心了，必须升级到图模型。

范式二：图流派（Graph）—— LangGraph

核心信念：程序即有向图，状态在 Channel 中流淌。

graph = StateGraph(AgentState)
graph.add_node("research", research_fn)
graph.add_node("write", write_fn)
graph.add_conditional_edges("write", quality_check, {"pass": END, "fail": "research"})

日常类比：地铁线路图。站点是节点，轨道是边，换乘站是条件路由。你可以做环线（循环），可以在某站等人（human-in-the-loop），还能在任意站存档（checkpoint）改天继续坐。

适用场景：需要循环、分支、并行的复杂工作流。需要状态一致性保证的场景。

局限：学习曲线陡峭。简单场景过度工程化。

图编排骨架：定义状态 → 添加节点 → 连边 → 编译执行

# LangGraph 骨架（≤20 行）—— 关键：State + Node + Edge + Conditional
from langgraph.graph import StateGraph, END
from typing import TypedDict, Literal

class ArticleState(TypedDict):          # 1. 共享状态 Schema
    topic: str
    draft: str
    quality_score: float
    revision_count: int

def research(state): ...                # 2. 节点 = 纯函数(state → partial update)
def write(state): ...
def review(state): ...

def should_continue(state) -> Literal["pass", "revise", "give_up"]:  # 3. 条件路由
    if state["quality_score"] >= 0.8: return "pass"
    if state["revision_count"] >= 3: return "give_up"
    return "revise"

graph = StateGraph(ArticleState)        # 4. 建图 + 编译
graph.add_node("research", research)
graph.add_node("write", write)
graph.add_node("review", review)
graph.set_entry_point("research")
graph.add_edge("research", "write")
graph.add_edge("write", "review")
graph.add_conditional_edges("review", should_continue, {
    "pass": END, "revise": "research", "give_up": END  # 循环！
})
app = graph.compile()
result = app.invoke({"topic": "AI Agent", "revision_count": 0})

核心机制解析：图的执行引擎 Pregel 按”超步”（superstep）推进——每个超步执行一个节点，把输出合并到 State 中，再根据边的定义决定下一步执行哪个节点。循环就是”某个节点被多次执行”。Checkpoint 就是”在每个超步后把 State 快照存起来”——崩了可以从最近的 checkpoint 恢复，人类审批可以在任意节点暂停等待。

范式三：角色流派（Role Play）—— CrewAI / Agno

核心信念：Agent 就是人，协作就是分工。

researcher = Agent(role="研究员", goal="找到最新趋势", backstory="你有10年经验...")
writer = Agent(role="写手", goal="写出高质量文章", backstory="你擅长深入浅出...")
crew = Crew(agents=[researcher, writer], process=Process.sequential)

日常类比：剧组拍电影。导演（Process）安排工作顺序，演员（Agent）各有角色定位。你不需要理解”有向图”“超步”“Channel”——只需要知道”谁做什么”。

适用场景：角色分工明确的多 Agent 任务。快速原型。非技术人员也能理解的编排。

局限：状态管理弱。复杂工作流表达力不足（Sequential/Hierarchical 太粗粒度）。

角色编排骨架：Agent(role+backstory) → Task → Crew

# CrewAI 骨架（≤20 行）—— 关键：backstory 决定行为模式
from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="市场研究员",
    goal="收集并分析目标市场数据",
    backstory="资深分析师…用数据说话…不确定就说数据缺失",  # ← 行为约束
    tools=[search_tool],
)
writer = Agent(role="策略撰写人", goal="输出可执行策略", backstory="…结论先行…不超3页…")

research_task = Task(description="调研AI Agent市场", agent=researcher)
strategy_task = Task(description="输出策略建议", agent=writer, context=[research_task])

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, strategy_task],
    process=Process.sequential,  # 按顺序执行
)
result = crew.kickoff()

backstory 是角色流派的灵魂。它不是装饰性文字——它直接注入到 system prompt 中，决定了 LLM 的行为模式。好的 backstory 应该包含：身份定位（决定专业度和视角）、行为约束（减少幻觉和无关输出）、输出风格（让结果格式可预测）。一个常见错误是把 backstory 写成”你很厉害你很专业”——这没有任何约束力。有效的 backstory 要有具体的行为规则。

范式四：微服务流派（Microservice-Native）—— tRPC-Agent

核心信念：Agent 就是微服务，RPC 就是协作。

type MyAgent struct{}
func (a *MyAgent) Run(ctx context.Context, inv *Invocation) (<-chan *Event, error) { ... }
func (a *MyAgent) Tools() []Tool { return myTools }
func (a *MyAgent) Info() Info { return Info{Name: "researcher"} }
func (a *MyAgent) SubAgents() []Agent { return nil }

日常类比：公司组织架构。每个部门（Agent）是独立运作的团队，通过 OA 系统（tRPC 框架）互相发工单协作。部门间不需要私下建微信群——OA 已有审批流、权限管理、消息追踪。

适用场景：Go 微服务体系。高并发生产环境。需要服务治理（负载均衡/熔断/链路追踪）的场景。

局限：社区生态不成熟。Go 的 AI/ML 库远不如 Python。

微服务暴露骨架：定义 Agent → 创建 Runner → 注册协议 → 启动

// tRPC-Agent 骨架（≤15 行）—— 关键：同一 Agent 多协议暴露
func main() {
    s := trpc.NewServer()
    myAgent := llmagent.New(                        // 1. 定义 Agent
        llmagent.WithName("researcher"),
        llmagent.WithTools(searchTool),
        llmagent.WithModel("gpt-4o"),
    )
    r := runner.New(runner.WithAgent(myAgent))      // 2. Runner 管理运行时
    agent.RegisterService(s, r)                     // 3a. tRPC 原生协议
    openai.RegisterHandler(s, r)                    // 3b. OpenAI 兼容 HTTP
    a2a.RegisterHandler(s, r)                       // 3c. Agent-to-Agent
    s.Serve()                                       // 4. 启动（自动服务发现）
}

微服务原生的核心优势：同一个 Agent 实现，通过不同 Handler 注册，可以同时以三种协议对外服务。Agent 的部署、扩缩容、灰度发布、监控告警全部复用 tRPC 已有的基础设施——不需要额外开发一行代码。这在 Python Agent 框架中需要自己搭建的东西（Docker 部署脚本、Prometheus 指标暴露、Jaeger 链路追踪、限流熔断），在 tRPC 生态里都是”配置即开启”。

1.4 演进脉络：从链到图到微服务

2022: LangChain — 链式调用（线性、无状态）
       问题：无法循环、无法分支

2023: LangGraph — 有向图（非线性、有状态）
       问题：单机执行、无分布式治理

2024: tRPC-Agent — 微服务原生（分布式、有治理）
       问题：社区年轻、生态待建

每一代框架解决上一代的核心痛点。但这不意味着后者”更好”——它们面向不同的复杂度层级。

关键洞察：你不需要一个 Agent 处理”100个用户并发请求”的问题时，LangGraph 的单机图模型完全够用。你不需要循环和分支时，LangChain 的管道是最简单的选择。框架选型 = 找到匹配你复杂度层级的最小工具。

1.4.5 2025年新兴框架速览

2025 年是 Agent 框架爆发的一年——几乎每个大厂都推出了自己的 Agent 框架。以下是五个最值得关注的新兴框架：

OpenAI Agents SDK（2025.03 发布）

OpenAI 自家的 Agent 框架，定位为”构建多Agent系统的最小但完整方案”。

from openai import agents

# 核心概念只有四个：Agent / Tool / Handoff / Guardrail
researcher = agents.Agent(
    name="researcher",
    instructions="你是研究员，搜索信息并整理。",
    tools=[agents.WebSearchTool()],
    handoffs=[writer_agent],  # 做完后可以交给 writer
)

# 运行
result = agents.run(researcher, "搜索AI趋势")

特点：极简 API（比 LangChain 少 90% 的概念）；原生 Handoff 机制（类似 tRPC-Agent 的 Swarm）；内建 Tracing（免费版 LangSmith）；与 OpenAI 模型深度绑定（原生支持 Responses API 的 tool_use）。局限：强绑定 OpenAI 模型；功能还比较基础（无图编排、无 checkpoint）。

Google ADK（Agent Development Kit，2025.04 发布）

Google 的 Agent 框架，特点是深度集成 Gemini 模型和 Google Cloud 服务。

核心概念：Agent 树（Tree of Agents）——Agent 可以有子 Agent，形成树状组织。父 Agent 自动具备”委派给子 Agent”的能力。与 tRPC-Agent 的 SubAgents 概念相似，但更强调父子关系的隐式路由。内建 A2A 协议支持和 MCP 工具协议支持。

Anthropic MCP（Model Context Protocol，2024.11 发布，2025 成为事实标准）

严格来说 MCP 不是 Agent 框架，而是工具层协议。但它对所有 Agent 框架产生了深远影响——因为它解决了”工具如何注册和发现”的标准化问题。

MCP 之前：每个框架自定义工具接口（LangChain 的 @tool、CrewAI 的 BaseTool、tRPC-Agent 的 tool.Tool）。你为 LangChain 写的工具不能直接在 CrewAI 中用。

MCP 之后：工具以独立进程（MCP Server）运行，通过标准化的 JSON-RPC 协议暴露能力。任何支持 MCP 的 Agent 框架都能直接调用任何 MCP Server 提供的工具——工具和框架解耦。

AutoGen v0.4（2025.02 发布）

微软的 Agent 框架大版本重写。v0.4 完全推翻了之前的”对话轮转”模型，转向事件驱动 + 分布式运行时：

核心变化：Agent 之间不再是”对话”关系，而是”事件发布/订阅”关系。引入 Runtime 层（类似 Actor 模型的 ActorSystem），支持 Agent 分布在不同进程/机器。引入 Team 抽象（与 tRPC-Agent 的 Team 概念类似）。定位从”研究原型”转向”生产部署”。

Agno（原 phidata，2025.01 更名）

极简主义的 Agent 框架，核心卖点是”一个 Agent 类搞定一切”。

from agno.agent import Agent
from agno.tools.search import DuckDuckGoTools

agent = Agent(
    model="gpt-4o",
    tools=[DuckDuckGoTools()],
    instructions="你是一个研究助手",
    show_tool_calls=True,
)
agent.print_response("AI Agent 框架有哪些？")

特点：API 极简（5 分钟上手）；内建 190+ 工具；内建 Team 支持（coordinate/route/collaborate 三种模式）。局限：Agent 类承载了太多职责（God Object 问题）；状态管理基本没有；不适合复杂工作流。

2025 年框架格局总结：

1.5 六大框架速查表

1.5.5 框架选型决策树

面对一个具体项目，按以下维度逐步缩小选择范围：

第一步：语言约束

你的团队主力语言是什么？
├── Python → 继续往下选（绝大多数选择）
├── Go → tRPC-Agent-Go（几乎唯一的成熟选择）
├── TypeScript → Vercel AI SDK / LangChain.js / OpenAI Agents SDK
└── Java/C# → 生态极不成熟，建议 Python 微服务 + RPC 桥接

第二步：规模判断

你的 Agent 需要承受多大并发？
├── < 10 QPS（内部工具/Demo）→ 任何框架都行，选你最熟的
├── 10-100 QPS（中等规模产品）→ LangGraph / CrewAI + 容器化部署
└── > 100 QPS（高并发生产）→ tRPC-Agent / 自研循环 + 基础设施加持

第三步：复杂度匹配

你的 Agent 工作流有多复杂？
├── 线性流（A→B→C，无循环无分支）→ LangChain 管道 / CrewAI Sequential
├── 有循环有分支（质量检查→返工）→ LangGraph / tRPC-Agent StateGraph
├── 多Agent动态协作（不确定谁做什么）→ CrewAI Hierarchical / tRPC-Agent Coordinator
└── 超大规模（>10 Agent + 嵌套）→ tRPC-Agent Team of Teams / AutoGen v0.4

第四步：团队经验

你的团队对 AI/Agent 的经验程度？
├── 零经验（第一次做）→ CrewAI / Agno（上手最快）
├── 有经验（做过 RAG/Chatbot）→ LangGraph（表达力最强）
└── 资深（分布式系统老手）→ tRPC-Agent / 自研（控制力最强）

第五步：生态需求

你需要多少现成的集成？
├── 大量（接十几个SaaS工具）→ LangChain（集成最多）/ MCP 工具生态
├── 中等（几个核心工具）→ 任何框架 + MCP Server
└── 很少（自研工具为主）→ 框架选择不受此约束

常见场景速查：

1.6 本系列的学习路线

这份导读系列共 12 章，按两条主线交织推进：

主线 A：tRPC-Agent-Go 竞赛精读（第 2-5 章 + 第 11 章）

• 第 2 章：全架构——三层套娃与核心数据流
• 第 3 章：ReAct 循环——LLM Flow 的 2468 行心脏
• 第 4 章：Team 多 Agent——Coordinator vs Swarm
• 第 5 章：StateGraph 图引擎——6192 行的 Go 版 LangGraph
• 第 11 章：Ralph Loop——不信任 LLM 的验证循环

主线 C：跨框架对比（第 6-10 章 + 第 12 章）

• 第 6 章：LangGraph 精读——Channel + Pregel 的精巧设计
• 第 7 章：CrewAI 精读——角色扮演 + Flow 事件驱动
• 第 8 章：对比篇——状态管理哲学
• 第 9 章：对比篇——多 Agent 协作模式
• 第 10 章：对比篇——生产就绪度与协议生态
• 第 12 章：Memory 设计——三大框架的记忆系统演进

思考题

读完本章后，请尝试回答以下问题。不急着看答案——先用自己的理解想一想，想不通再往后读或来问我。

Q1（概念验证）：假设你要做一个”自动写周报”的 Agent——它需要：查看本周 Git 提交记录 → 读取相关代码变更 → 生成周报草稿 → 检查格式是否合规 → 不合规就修改重来。你会选哪个范式？为什么管道流派不够用？

Q2（设计取舍）：LangGraph 用”有向图”建模 Agent 行为，tRPC-Agent 说”Agent 就是微服务”。一个图节点和一个微服务实例，在你看来最本质的区别是什么？（提示：考虑部署、扩缩容、故障隔离）

Q3（范式边界）：CrewAI 的 Role/Goal/Backstory 本质上是在做什么？（提示：如果你去掉框架，直接用 system prompt 手动实现同样的效果，代码长什么样？）

Q4（演进预测）：链→图→微服务，每一代解决上一代的痛点。你觉得下一代可能解决什么痛点？（开放题，没有标准答案）

Q5（实战判断）：你所在的实习团队用 Go 开发后端微服务，现在需要加一个”智能客服 Agent”功能。你会推荐哪个框架？如果团队说”我们想两周内出 demo”呢？如果说”这个 Agent 要承受日均 100 万请求”呢？两个约束下的选择会不同吗？

下一章：第二章 tRPC-Agent-Go 全架构精读

返回目录：Agent 框架深度导读系列