版本与时效声明
-
本文是对前面各篇笔记的汇总与评价。表格中的事实都来自对应专题笔记，出处见各篇的参考资料；“评价”“建议”两类内容是笔者的观点。
-
各产品对应的版本如下（2026-10-09）：
产品 版本 OpenAI Agents SDK 0.23.1 OpenAI Agents API beta Claude Agent SDK Python 0.2.164 / TS 0.3.293 Claude Managed Agents beta pi 1.1.0 DSH 0.2.0-rc.2，开发者预览 -
这几个产品都在高速迭代，其中三个是 beta 或预览版本，本文结论的有效期很短。做实际选型之前，请先查看各产品最新的官方文档。
本文要点
- 用两个坐标轴给六个产品定位：抽象层级（只提供原语，还是提供完整的 harness）和运行位置（在你的进程里，还是由厂商托管）。
- 选型的核心问题有三个：谁来运行循环？要不要内置工具和沙箱？要不要支持多家模型？
- 文末给出一条循序渐进的学习路线，从手写循环一直到托管 agent。
1. 定位图#
2. 总对比表#
| 维度 | OpenAI Agents SDK | OpenAI Agents API | Claude Agent SDK | Claude Managed Agents | pi | DSH |
|---|---|---|---|---|---|---|
| 类别 | 开源 agent 运行时 | 托管的 Codex harness | Claude Code 作为库 | 托管的 harness | 极简可扩展的 harness 与库 | 一切皆插件的 harness |
| 层级 | L3（加 Sandbox 后到 L4） | L5 | L4 | L5 | L1、L3、L4 分包提供 | L1 到 L4，每层都是插件 |
| 循环在哪运行 | 你的进程 | OpenAI | 你的进程，内部再启动 CLI 子进程 | Anthropic | 你的进程 | 你的进程；SDK 方式会启动运行时子进程 |
| 模型 | OpenAI 为主，可以接入其他厂商 | OpenAI | Claude | Claude | 数十家 | DeepSeek 为主；通过 pi-ai 适配器接入多家 |
| 语言 | Python、JS/TS | REST，各语言都有 SDK | Python、TS | REST，各语言都有 SDK | TypeScript | TypeScript；另有 Python SDK |
| 工具定义 | 装饰器，基于签名和 docstring | JSON Schema 函数，加上处理器 | @tool 加进程内 MCP | custom 工具，在你这边执行 | TypeBox | defineTool 插件 |
| 内置工具 | 托管工具，加 Sandbox 能力 | 沙箱里的 shell、文件等 | 一整套编码工具 | bash、文件、web 等工具集 | 默认 4 个：read、bash、edit、write | 按 preset 组合 |
| 状态 | 4 种策略：本地列表、Session、conversation、链式 | 托管的 session、turn、item | 本地 JSONL，支持 resume 和 fork | 托管的 session 和事件 | 树状 JSONL | 事件溯源日志，带格式迁移 |
| 多 Agent | handoffs、agents-as-tools | 托管的 subagent | subagents | 协调者加 roster | 默认不提供，可以用扩展实现 | subagent seam，可委派给 Claude Code 或 Codex |
| 安全 | guardrails、needs_approval | 沙箱、vault | 权限模式、hooks、can_use_tool | 权限策略、vault | 默认不设防，靠扩展或容器 | fail-closed 沙箱、审批 seam |
| 扩展机制 | hooks、自定义模型提供方 | plugins、skills、MCP | hooks、plugins、skills、MCP | skills、MCP、outcomes | 扩展、skills、packages | Cordis 插件、profile 与 patch |
| 可观测性 | 内置 tracing | Dashboard、OTLP 导出 | OpenTelemetry、费用统计 | 事件流、webhook | 细粒度事件流 | 会话日志、OpenTelemetry 插件 |
| 成熟度 | 0.x，迭代快 | beta | 0.x，几乎每天发版 | beta | 1.1.0 | 开发者预览 |
| 许可与计费 | MIT 开源；按模型用量计费 | 按 API 计费 | 使用受 Anthropic 商业条款约束 | token 费用，加 $0.08/会话小时 | MIT | MIT |
表中各项事实的出处，见 2.3 OpenAI Agents SDK、2.4 OpenAI Agents API、3.3 Claude Agent SDK、3.4 Claude Managed Agents、4.1 pi 全景与设计哲学、5.1 DeepSeek Harness 全景。
关于“许可”这一行
- Claude Agent SDK 的使用受 Anthropic 商业服务条款约束，个别组件以各自的 LICENSE 文件为准。详见 3.3 Claude Agent SDK 引用的官方 overview。
- OpenAI Agents SDK 的许可证是 MIT，依据是 PyPI 上 openai-agents 的元数据
License-Expression: MIT。
3. 选型决策树#
几条经验法则（笔者观点）
- 先从最简单的一层开始。 能用一次 API 调用解决的事，就不要上 agent；能用 L3 解决的，就不要上 L4。Anthropic 在 Building Effective AI Agents（2024-12-19）中也建议：先找最简单的方案，只在必要时才增加复杂度，有时这意味着根本不需要构建 agent 系统1。
- “厂商绑定”是个连续的谱，不是非黑即白。 例如 Agents SDK 也能接入其他厂商的模型，pi-ai 也能用 OpenAI 的模型。真正的绑定，来自你依赖了哪些托管能力，比如服务端会话、托管工具、托管沙箱。
- 安全模型要和部署方式匹配。
- pi 默认没有权限系统，一定要放进容器里运行；
- Claude Agent SDK 有多层权限，但
bypassPermissions只应该在隔离环境中使用； - DSH 有 fail-closed 沙箱，但官方明确说它不能作为唯一的安全措施。
- beta 和预览版本不要直接用于生产。 Agents API、Managed Agents、DSH 都还在 beta 或预览阶段，接口可能变化。DSH 还存在 npm 包与仓库源码不一致的情况，见 5.3 DSH 核心机制与插件开发 › 8. 踩坑记录：npm 包落后于仓库源码。
4. 再谈“轻量”#
你在问题里把 pi 和 DSH 称为“轻量化 SDK 的代表”。研究下来，笔者认为“轻量”至少有三种含义：
| 含义 | pi | DSH | 说明 |
|---|---|---|---|
| 核心代码少 | ✅ agent 循环约 2,500 行 | ✅ Cordis 约 2,700 行，agent-loop 约 2,400 行 | 两者的核心都能在一两天内读完 |
| 默认功能少 | ✅ 4 个工具，提示词不到 1,000 token | 视 preset 而定，minimal 很精简 | pi 把“少”当作一种设计哲学 |
| 一切可以拔掉、可以替换 | ⚪ 有扩展系统，但核心是固定的 | ✅ 连循环都是插件 | DSH 在这个维度上走得最远 |
| 整体代码量小 | ❌ 仓库约 20 万行 | ❌ 约 43 万行 | 两者的发行版都不小 |
行数都是笔者用 find 加 wc -l 的粗略统计，见 4.1 pi 全景与设计哲学 和 5.1 DeepSeek Harness 全景。
结论（笔者观点）：pi 和 DSH 的“轻”，指的是核心小、可控、可替换，而不是“总代码量小”。它们和厂商 SDK 最大的区别在于：
- 透明：你能看到每一个请求、每一条上下文；
- 可替换：模型、工具、循环都可以换掉；
- 不绑定任何厂商的托管服务。
5. 学习路线（建议）#
| 阶段 | 做什么 | 产出（可以写成博客） |
|---|---|---|
| 1 | 用 OpenAI 和 Anthropic 的原生 SDK 各手写一次 agent 循环 | 《30 行代码看懂 Agent Loop》 |
| 2 | 用 Agents SDK 实现 handoff、护栏和 session；用 Tool Runner 改写阶段 1 的代码 | 《从手写循环到 Agents SDK：框架替我做了什么》 |
| 3 | 带着阶段 1 的代码，对照阅读 pi-agent-core/src/agent-loop.ts，列出它多处理了哪些边界情况 | 《读源码：一个生产级 Agent 循环的边界情况》 |
| 4 | 用 Claude Agent SDK 和 pi 各做一个“读仓库、写报告”的 agent，体会内置工具与权限的差异 | 《Claude Agent SDK vs pi：开箱即用与极简可控》 |
| 5 | 按 DSH 的 Cordis 教程把第 1 到 7 章全部跑一遍（不需要 API Key），再写一个自己的工具插件 | 《一切皆插件：从 Cordis 看可组合的 Agent 架构》 |
| 6 | 选一个托管产品做长任务，同时补上 tracing、护栏、成本监控 | 《托管 Agent 的成本与可控性权衡》 |
和后端知识的结合点
下面这些主题既是 agent 的工程问题，也是后端博客的好选题：
- 事件溯源：DSH 的会话日志、pi 的树状会话；
- 幂等：Agents API 的
Idempotency-Key； - 进程模型与隔离：Claude Agent SDK 的子进程架构、各家的沙箱阶梯；
- 依赖注入与生命周期管理：Cordis；
- 供应链安全：pi 的依赖锁定实践。
6. 最后一张图：抽象层级#
小结#
- 没有最好的 SDK，只有最适合的那一层。 先问自己：循环谁来写？工具谁来执行？状态放在哪？用哪家的模型？
- OpenAI 和 Claude 的两条产品线在 2026 年已经高度对称：
- 客户端 SDK 加原语：Responses 对应 Messages；
- L3 循环：Agents SDK 对应 Tool Runner；
- L4 harness：Sandbox Agents 对应 Agent SDK；
- L5 托管：Agents API 对应 Managed Agents。
- pi 和 DSH 代表的是另一条路线：开放、透明、可替换。
相关笔记#
参考资料#
注释与出处#
-
Anthropic Engineering，Building Effective AI Agents（2024-12-19），https://www.anthropic.com/engineering/building-effective-agents ↩