框架巡礼：LangGraph / Agents SDK / Claude Agent SDK

一句话定义

Agent 框架的价值不是实现循环（kp-017 已证明 90 行够了），而是提供循环之外的生产件：状态持久化、并发调度、人审节点、流式输出、 tracing 与部署集成——选框架就是选这些生产件的设计哲学。

为什么重要

框架选型是团队级决策，换框架的成本随 Agent 数量增长。2023 年的框架大爆发（上百个）已收敛到 2026 年的三强格局，各自哲学清晰：LangGraph = 显式图与控制（你画流程）；OpenAI Agents SDK = 极简循环与交接（模型决定流转）；Claude Agent SDK = 生产级单 Agent 形态（Claude Code 同款内核）。理解三者差异，比学会任何一个的 API 都重要——因为差异背后是 kp-007 的根本问题：控制流放哪。

前置知识

kp-017（手写循环——祛魅的前提）、kp-019（编排）。

核心概念

三强对比

维度	LangGraph	OpenAI Agents SDK	Claude Agent SDK
核心抽象	图（节点=步骤，边=流转）	Agent（循环+工具）+ handoff	预构建的 Claude Code 类 Agent（循环+CLI工具+权限）
控制流	开发者显式定义	模型 handoff 决定	模型自主 + 权限系统约束
状态	checkpoint 持久化、可回放	轻量（run 管理）	会话持久 + 文件系统
杀手锏	复杂工作流可视化/可中断/时间旅行调试	极简上手、与 OpenAI 生态无缝	白拿 Claude Code 的工程化（hook/权限/MCP）
适合	流程复杂的多阶段管线	快速构建服务型多 Agent	构建编程/终端型产品
代价	学习曲线陡（图思维）	定制深了要自己补件	绑定 Claude 生态与形态

LangGraph 的图思维

pythonfrom langgraph.graph import StateGraph, END
builder = StateGraph(State)            # State 是共享的 TypedDict
builder.add_node("plan", plan_node)    # 节点 = 读状态→改状态的函数
builder.add_node("execute", execute_node)
builder.add_node("review", review_node)
builder.add_edge("plan", "execute")
builder.add_conditional_edges("review", should_retry,
    {"retry": "execute", "done": END})
graph = builder.compile(checkpointer=...)  # ← 每步自动存档

它把 kp-006 的 while 循环外化为图：分支、循环、人审（interrupt）都成为一等公民，可可视化、可断点续跑。代价是你必须预先想清楚结构——这正是它适合"流程已知"场景、不适合"全自主探索"的原因。

Agents SDK 的极简哲学

pythonfrom agents import Agent, Runner
triage = Agent(name="客服分诊", instructions="...", handoffs=[refund_agent, tech_agent])
result = await Runner.run(triage, user_msg)

handoff 是它的灵魂：模型在对话中把控制权交给另一个 Agent（作为特殊工具调用实现）。控制流由模型分布决定——与 LangGraph 的哲学正好相对。2025 年发布时官方明确砍掉了上一代（Assistants/Swarm）的复杂概念，"less is more" 路线。

Claude Agent SDK：产品级形态外包

直接提供 Claude Code 的内核（查询-编辑-执行循环、CLAUDE.md 记忆、权限门、hook、MCP、subagent），你在其上做产品封装。本质是把"顶级 Agent 的工程化"当依赖装进来——适合终端型、编程型场景；通用场景受其形态约束。

原理与机制

三者的哲学差异可以统一到 kp-007 的控制光谱上：LangGraph 把控制流放在代码/图（workflow 端），Agents SDK 放在模型（agent 端），Claude SDK 放在模型 + 预置护栏（产品端）。没有最优，只有匹配：

步骤确定、要审计、要人审插桩 → LangGraph
探索型、服务型、快迭代 → Agents SDK（或直接 kp-017 自研 + 平台件）
终端/编程型产品、想白拿成熟权限与记忆系统 → Claude Agent SDK

另一条 2025 年后强化的事实标准：框架层都在 MCP 原生支持上卷（工具生态共享），且都接 LangSmith/OpenTelemetry 类 tracing（kp-025）——框架的护城河正从"抽象"转向"运维件"。

直观类比

LangGraph = 乐高图纸：结构清晰、改起来要重新拼，但成品可预测可复制
Agents SDK = 给实习生放权：你说目标，他自己决定找哪个同事（handoff）
Claude Agent SDK = 雇一个带完整工具箱和门禁卡的成手

实例与案例

同一需求（"周报聚合：抓数据→分析→人审→发布"）的三框架落点：

LangGraph：四节点图，人审 用 interrupt 暂停等输入，checkpoint 让周五中断周一续跑
Agents SDK：triage Agent handoff 给 analyst，再 handoff 给 publisher（人审要自建外部循环）
Claude Agent SDK：一个会话让它跑，权限系统拦住"发布"动作等人批准（kp-023 现成实现）

注意结论：需求里的"人审+断点续跑"天然偏好 LangGraph——选型从需求特征出发，不从流行度出发。

常见误区

误区一："框架让 Agent 更聪明"。框架不改变模型能力；同一模型+同一工具，框架间上限差异远小于工具/提示设计的差异（kp-010/004）。
误区二：跳过 kp-017 直接学框架。你会把图、节点、handoff 当魔法背下来，遇到 bug 无法下沉。
误区三：框架重度抽象 + 深度定制。绕过抽象的定制比自研更难维护——当你的定制开始对抗框架哲学，就是换/退的信号。
误区四：忽视自研路线。生产中大量团队最终回到"kp-017 + 少量库 + 自家平台件"，框架不是必经之路（尤其工具少、流程简单的场景）。

自测题

框架的真正价值是什么（不是什么）？
三强的控制流哲学分别落在 kp-007 光谱的哪一段？
什么信号说明该换框架或退回自研？

（参考答案：1. 生产件（状态/并发/人审/tracing/部署），不是智能；2. 代码端 / 模型端 / 模型+护栏端；3. 定制开始对抗框架的核心抽象时。）

与其他知识点的关系

循环本质 → kp-006/017；编排思想 → kp-019
框架的运维件 → kp-025/027；MCP 集成 → kp-011
Claude Agent SDK 的产品级样本 → kp-028