Agent 框架选型

先列不可妥协的运行需求

选型输入不是“想做一个研究 Agent”，而是可验证的运行契约：请求可能持续多久，状态丢失能否重跑，哪些动作需要人工审批，取消如何传播，副作用如何幂等，Trace 是否能导出，数据能否离域，以及团队主要语言和部署环境。

任何硬约束无法满足的候选先淘汰，不要再用“社区活跃”“集成很多”补分。开发速度是约束之一，但不能抵消数据越界、不可恢复或不可审计。

比较框架的核心抽象

框架 API 会变化，核心抽象更稳定。抽象如果贴合团队的问题表达，调试和治理成本会下降；若抽象错配，再丰富的插件也只会增加转换层。

Graph/State Machine

LangGraph v1 把 State、Node、Edge、Checkpoint 和 Interrupt 作为一等概念，适合长任务、显式分支、人工中断和恢复。官方文档说明 Checkpoint 以 Thread 组织并在 Super-step 边界保存；Interrupt 恢复时会从节点开头重新执行，因此中断前副作用必须幂等。代价是状态 Schema、节点边界和迁移版本需要主动设计。

Agent Conversation

AutoGen v0.4 采用分层、异步、事件驱动架构：AgentChat 提供对话与 Team 抽象，Core 提供更底层 Actor/Runtime。它与 v0.2 有破坏性变化；截至 2026 年，Microsoft 已提供从 AutoGen 迁往 Microsoft Agent Framework 的官方路径，新项目必须把 Agent Framework 一并纳入候选，而不能只根据旧 AutoGen 教程决策。

Role/Task/Crew

CrewAI 的 Crew/Agent/Task 适合用角色与任务表达协作，Flow 则提供事件驱动、状态、分支和持久化。它对业务人员理解多 Agent 友好，但角色数量容易变成组织结构模拟；需要验证每个 Agent 是否带来独立信息、权限隔离或质量增益，而不是增加 Token 和错误传播。

Agent/Tool/Runner

OpenAI Agents SDK 以 Agent、Tool、Handoff、Guardrail 和 Runner 为核心，TypeScript 版本支持 Session、Tracing、MCP 与 Human-in-the-loop，适合用语言原生控制流快速落地。Smolagents 保持轻量，并提供 CodeAgent 和 ToolCallingAgent；代码动作具有表达力，也意味着必须审查沙箱和执行权限。薄抽象便于理解，但持久工作流、跨 Provider 语义和企业控制面可能需要自行补齐。

生产能力要逐项实测

“支持持久化”至少要追问保存时点、原子性、版本 Schema、并行写入、敏感字段和恢复重放语义。“支持人工审批”要确认进程能否退出、状态能否序列化、审批过期或策略变化后如何恢复。“支持 Streaming”要测试背压、断线、取消和最终状态。

依赖云托管服务时，还要把本地框架能力和平台能力分开标注。否则迁离托管层后，Checkpoint、Queue、身份或 Trace 可能一起消失。

PoC 要覆盖最难场景而非 Hello World

选择一个真实、可控且足够困难的垂直切片：读取受保护数据，调用一个带副作用 Tool，在执行前暂停审批，进程退出后恢复，流式返回进度，并在 Provider/Tool 超时、拒绝、取消和重复消息下保持正确终态。所有候选使用同一输入集、业务契约和验收器。

PoC 报告区分“框架原生支持”“官方扩展”“团队封装”和“尚未验证”。不要用各框架不同的示例任务比较开发行数，这只能反映教程风格。

总成本包括框架之外的补齐项

TCO 包括学习、建模、测试、调试、托管、监控、安全评审、升级和退出。一个框架少写 300 行 Loop，却需要自建身份、状态迁移和审计平台，整体未必更便宜。反之，因担心锁定而重写所有基础能力，也会把维护风险转嫁给团队。

锁定点通常不在 Agent 类名，而在持久化状态、事件格式、Tool/Context 接口、Trace 数据、托管 API 和 Prompt/模型耦合。把这些点列成迁移清单，估算导出、双写、回放和停机成本。

自研只应拥有差异化控制面

默认不自研模型 SDK、JSON-RPC、MCP/A2A 基础类型或通用 Trace 导出；这些更适合复用标准和成熟库。组织应拥有业务任务/状态契约、身份与策略、执行账本、数据边界、评测集和审计，因为它们决定风险与迁移能力。

// 业务层只依赖稳定内部端口，框架适配器实现它
interface AgentRuntimePort {
  start(input: RunInput): Promise<RunHandle>
  resume(runId: string, command: ResumeCommand): Promise<RunHandle>
  cancel(runId: string, reason: string): Promise<void>
  events(runId: string): AsyncIterable<DomainRunEvent>
}

// DomainRunEvent 由组织定义；不得直接暴露某框架内部 Event。

Adapter 不能做成最低公分母而丢失所有价值。先定义必须可移植的核心语义，再允许框架特性通过受控扩展使用，并记录迁移时如何降级。

选型结论包含适用范围和反例

ADR 应先给默认推荐，再写适用范围、拒绝条件、候选为何落选、已验证证据、未验证假设、残余风险、Owner 和退出计划。框架版本、插件、Provider 和部署方式都进入 Decision Context；“采用 LangGraph”不是完整结论。

复审由证据触发：框架 Major 升级、核心组件进入弃用、SLO 连续失守、补齐层超过框架本身、供应商政策变化或迁移成本显著上升。不要只设“每年看一次”而没有退出指标。