热门 Agent 框架源码导读：五个入口看懂设计

读 Agent 框架，最容易迷失在 README 的“快速开始”和几十个功能名里。每个项目都能创建 Agent、注册工具、流式输出和组织多角色，仅看 Hello World，很难理解它真正把复杂度放在哪里。

更有效的源码阅读顺序是：从运行入口进入，沿状态、工具、错误、持久化与 Trace 五条线追踪一次任务。你会发现，框架差异主要不在创建 Agent 的那三行代码，而在失败和长时运行时谁拥有控制权。

本文对比五个高关注 Python 生态项目：OpenAI Agents SDK、LangGraph、PydanticAI、Google ADK 和 Microsoft Agent Framework，并补充 CrewAI、CAMEL 与 AutoGen 的位置。

一、先说明“热门”怎样定义

本系列在 2026-07-19 通过 GitHub API 抓取了 55 个相关仓库的快照。本文五个主项目当时数据为：

项目	Stars	最近 Push	License	主要定位
LangGraph	37,611	2026-07-19	MIT	状态图与持久运行
OpenAI Agents SDK	28,017	2026-07-19	MIT	少量 Agent 原语与 Loop
Google ADK Python	20,689	2026-07-17	Apache-2.0	开发、评测、部署全生命周期
PydanticAI	18,649	2026-07-19	MIT	Python 类型与 Agent 工程
Microsoft Agent Framework	12,222	2026-07-19	MIT	Agent + 图工作流，Python/.NET

Star 只表示关注度。它不能证明架构更好、Bug 更少，也不能替你的业务 Eval。动态数据应注明快照日期，不应在文章里写成永恒排名。

二、读框架的五个入口

入口 1：Runner / Loop

找 run、runner、loop 或 invoke。它回答：一次模型输出后，谁解析 Tool Call，谁执行工具，谁决定继续，怎样停止。

入口 2：State / Message

找运行状态、消息、事件和上下文类型。它回答：事实保存在聊天列表、类型对象、共享图 State，还是事件日志中。

入口 3：Tool Boundary

找 Tool 定义、Schema 生成、批准、结果和异常。它回答：Python 函数怎样变成模型工具，参数错误和业务错误如何进入 Loop。

入口 4：Error / Limit

找异常、重试、最大轮数、取消和 Guardrail。它回答：框架如何面对失败，而不是如何展示成功 Demo。

入口 5：Persistence / Trace / Eval

找 Session、Checkpoint、Store、Trace 和 Eval。它回答：进程退出后能否恢复，运行证据怎样连接到质量判断。

按这五条线读完一个最小实例，再看 Multi-Agent 和协议扩展，理解会清晰得多。

三、OpenAI Agents SDK：从最小 Runner 理解 Agent Loop

OpenAI Agents SDK 强调较少原语：Agent、Tool、Handoff、Guardrail、Session 和 Tracing。[1]

图 1：OpenAI Agents SDK 的入口相对集中，适合先从 Runner 追一次完整 Loop。来源见文末。

源码阅读可以从以下路径开始：

src/agents/agent.py
src/agents/run.py
src/agents/run_state.py
src/agents/run_internal/run_loop.py
src/agents/run_internal/tool_execution.py
src/agents/run_internal/approvals.py
src/agents/result.py

设计思想

Agent 保存名称、指令、模型、工具、Handoff 等配置；Runner 拥有运行控制。模型返回后，内部 Loop 解析结果，执行工具或交接，再把新项目送入下一轮，直到得到最终输出或触发限制。

这种设计的优点是概念少，普通 Python 开发者容易从函数工具起步。Manager 可以把专业 Agent 当工具，也可以通过 Handoff 转移控制权。

复杂度在哪里

简单 API 背后仍有大量运行细节：批准、Guardrail、Session 持久化、流式事件、Tool Use 跟踪、错误处理和 Trace。读源码时不要停在 Runner.run()，要继续进入 run_internal/run_loop.py 和 tool_execution.py。

适合什么

希望用轻量原语搭建 Tool-Calling、多 Agent 和 Trace，又愿意自己管理更外层业务状态、部署和 Durable Runtime 的团队。

四、LangGraph：把控制流和持久状态放到中心

LangGraph 以 State、Node、Edge 和 Checkpoint 为核心，Agent 只是图上的一种节点组合。[2]

图 2：LangGraph 的 README 强调 resilient agents，其设计重点是状态图、恢复和人工介入。来源见文末。

源码入口：

libs/langgraph/langgraph/graph/state.py
libs/langgraph/langgraph/pregel/main.py
libs/langgraph/langgraph/pregel/_loop.py
libs/langgraph/langgraph/pregel/_runner.py
libs/langgraph/langgraph/pregel/_checkpoint.py
libs/prebuilt/langgraph/prebuilt/tool_node.py

设计思想

应用先定义共享 State，各节点读取状态并产生更新，边决定后续节点。Pregel 风格运行时负责分步执行、写入与检查点。条件边可以表达模型路由，固定边可以表达确定性 Workflow。

复杂度在哪里

图让控制流显式，却要求开发者认真设计 State 合并、节点幂等、并行更新、Checkpoint 与版本。一个图能画出来，不代表每个 Node 的副作用已经可靠。

适合什么

需要长时运行、人工暂停恢复、复杂分支或希望把 Workflow 与 Agent 混合在明确图结构中的系统。

五、PydanticAI：用 Python 类型约束 Agent 边界

PydanticAI 把 Pydantic 的类型、验证和开发体验带入 Agent 系统，强调模型无关、类型化依赖与输出、Toolset、Durable 与 Evals。[3]

图 3：PydanticAI 仓库把类型化 Agent、Eval 与 Graph 放在同一代码库中。来源见文末。

建议入口：

pydantic_ai_slim/pydantic_ai/agent/
pydantic_ai_slim/pydantic_ai/run.py
pydantic_ai_slim/pydantic_ai/tools.py
pydantic_ai_slim/pydantic_ai/tool_manager.py
pydantic_ai_slim/pydantic_ai/toolsets/approval_required.py
pydantic_evals/pydantic_evals/evaluators/agentic.py
pydantic_graph/pydantic_graph/graph_builder.py

设计思想

Agent 的依赖和输出可以成为类型契约；Tool 由 Python 签名与 Schema 连接；Toolset 可以组合、过滤、重命名、延迟加载和增加审批。这使“模型看到哪些能力”成为可编程对象。

复杂度在哪里

类型能捕获结构错误，却不能自动证明业务正确。amount: int 通过验证，不代表退款金额获批。类型边界必须与 Policy、环境终态和 Eval 组合。

适合什么

重视 Python 类型、依赖注入、结构化输出、模型可替换与测试体验，希望把 Agent 代码写得更像普通应用工程的团队。

六、Google ADK：把 Agent 生命周期做成完整工具箱

Google ADK 提供 Agent、Tool、Session、Artifact、Event、Evaluation、Deployment、A2A 和 Streaming 等较宽的产品面。[4]

图 4：Google ADK 的仓库定位明确覆盖构建、评测与部署。来源见文末。

源码入口：

src/google/adk/agents/base_agent.py
src/google/adk/agents/llm_agent.py
src/google/adk/agents/invocation_context.py
src/google/adk/agents/run_config.py
src/google/adk/agents/sequential_agent.py
src/google/adk/agents/parallel_agent.py
src/google/adk/agents/loop_agent.py
src/google/adk/agents/remote_a2a_agent.py
src/google/adk/events/

设计思想

BaseAgent 和 Invocation Context 形成运行骨架，LLM Agent 处理模型驱动逻辑；Sequential、Parallel、Loop 等 Agent 用确定结构表达工作流；Event 贯穿运行，Remote A2A Agent 接入外部 Agent。

这不是只包装一次模型调用，而是面向开发、调试、评测与部署的一整套 Agent Development Kit。

复杂度在哪里

能力面较宽意味着概念和配置更多。团队需要选择真正使用的子集，并检查云服务与开源组件的边界，避免因为“全生命周期”误以为业务治理已经自动完成。

适合什么

需要代码优先、Agent Team、流式、多协议、Session/Eval/Deploy 一体化，并偏好 Google 生态或多模型支持的团队。

七、Microsoft Agent Framework：Agent 与 Workflow 合流

Microsoft Agent Framework 被官方定位为 AutoGen 与 Semantic Kernel 经验的后继方向，提供 Python/.NET 的 Agent 和图工作流。[5]

图 5：Microsoft Agent Framework 同时覆盖 Python、.NET、Agent 与 Workflow。来源见文末。

阅读入口可以从：

python/packages/core/agent_framework/orchestrations/
python/packages/durabletask/agent_framework_durabletask/_workflows/runner_context.py
python/samples/02-agents/harness/console/agent_runner.py
python/samples/02-agents/harness/console/state_driver.py
python/samples/02-agents/harness/console/observers/tool_approval.py
python/samples/02-agents/evaluation/evaluate_agent.py

设计思想

单 Agent 与 Workflow 并列：Sequential、Concurrent、Handoff、Group Chat、Magentic 等模式被放入显式编排，同时连接 Durable Task、A2A、MCP、审批和评测。[6]

AutoGen 的位置

AutoGen 仍是高关注仓库，快照时约 59,815 Stars，但官方仓库说明新用户应查看 Microsoft Agent Framework，AutoGen 继续以维护和社区支持为主。[7] 因此，新项目不能只按历史 Star 选择 AutoGen，应评估迁移路径和当前官方方向。

适合什么

已有 Microsoft/.NET、Semantic Kernel 或 AutoGen 背景，需要 Agent 与确定性 Workflow、企业集成和 Durable 编排结合的团队。

八、CrewAI 与 CAMEL：角色社会的两种表达

CrewAI 快照约 55,776 Stars，以角色化 Crew 与事件驱动 Flow 形成两层：Crew 强调自治协作，Flow 强调业务控制。[8]

CAMEL 快照约 17,423 Stars，Societies、RolePlaying 和 Workforce 更强调多 Agent 社会、协调者、Planner、Critic 与 Worker。[9]

两者适合研究或实现角色分工，但仍要回到第 14、15 讲的问题：角色是否拥有不同工具、上下文、权限和评价标准。只有名字不同的 Agent，不会因为框架支持 Group Chat 就产生独立判断。

九、五个框架的核心取舍

项目	第一抽象	控制流	状态重点	典型优势	先检查的代价
OpenAI Agents SDK	Agent + Runner	Loop/Handoff/代码	Run/Session	原语少、上手直	外层持久业务编排
LangGraph	State Graph	Node/Edge	Checkpoint	显式图、恢复、HITL	State 与图复杂度
PydanticAI	Typed Agent	Run/Graph	类型化依赖与消息	Python 工程体验	类型不等于业务政策
Google ADK	Agent Lifecycle	多种 Agent/Workflow	Session/Event/Artifact	生命周期覆盖宽	概念面与平台选择
Microsoft AF	Agent + Workflow	Orchestrations	Durable/Workflow State	Python/.NET 与企业编排	新框架演进和迁移

没有“总体最强”。要按任务控制面选择，而不是按 Star 排名。

十、20：40 分钟源码实践

任选一个框架，固定一个 Commit，并完成“五入口追踪表”：

运行入口：
模型返回 Tool Call 后进入哪个函数：
Tool 参数在哪里校验：
Tool 失败怎样表示：
最大轮数在哪里检查：
状态保存在哪里：
进程重启怎样恢复：
Span/事件在哪里产生：
最终成功由谁宣布：

然后实现同一个最小任务：读取订单状态；只有 pending 才允许取消；操作后重新查询终态。要求记录工具参数、拒绝原因和最终状态。

不要先比较代码行数。比较哪一个框架让权限、状态、失败和验证最清楚。

本讲已核对的源码路径保存在 repo-reading-notes.md，仓库更新后应重新确认。

十一、框架选型的七条原则

1. 先用业务 Eval 验证任务，不用 Demo 选型；
2. 检查状态与错误模型，不只看成功 API；
3. 确认需要图、类型、全生命周期还是最小 Runner；
4. 检查模型和平台锁定边界；
5. 查看 License、维护方向、发布节奏和迁移说明；
6. 用一个有失败和副作用的 Spike，而不是天气查询；
7. 保留自己的领域状态、Tool Contract 和 Eval，避免全部绑在框架内部。

十二、这一讲的结论

读 Agent 框架，不要从角色数量和功能清单开始。沿 Runner、State、Tool、Error、Persistence/Trace 五条线追踪一次任务，才能看到真正的控制面。

OpenAI Agents SDK 偏最小原语，LangGraph 偏显式状态图，PydanticAI 偏 Python 类型工程，Google ADK 偏完整生命周期，Microsoft Agent Framework 偏 Agent 与 Workflow 合流。选择取决于你的失败模式和运营需求。

下一讲用三个端到端案例把这些组件落地：深度研究、企业客服和 Coding Agent，各自怎样选择 Loop、工具、Memory、Eval 与人工边界。

---

参考资料

[1] OpenAI Agents SDK. https://github.com/openai/openai-agents-python

[2] LangGraph. https://github.com/langchain-ai/langgraph

[3] PydanticAI. https://github.com/pydantic/pydantic-ai

[4] Google ADK Python. https://github.com/google/adk-python

[5] Microsoft, Agent Framework Overview. https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview

[6] Microsoft, Agent Framework Orchestrations. https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/

[7] Microsoft AutoGen. https://github.com/microsoft/autogen

[8] CrewAI. https://github.com/crewAIInc/crewAI

[9] CAMEL. https://github.com/camel-ai/camel