Agent SDK

关于时效

本专题的资料截至 2026-10-09。每篇 SDK 笔记的开头都有一个「版本与时效声明」，写明了所依据的 SDK 版本。这些 SDK 都在快速迭代，其中几个仍是 beta 或预览版。本专题不会随官方更新而同步更新，动手之前请务必对照官方文档。

这个专题讲什么

系统梳理两类 Agent SDK：

厂商 SDK：OpenAI 与 Claude（Anthropic），从客户端 SDK、Agent SDK 一直讲到托管 Agent；
轻量级代表：pi（Earendil，原作者 Mario Zechner）和 DSH（DeepSeek Harness）。

目标是真正理解它们：每个 SDK 处在哪一层、替你做了什么、内部怎样运转、该怎么选。

阅读顺序#

建议先读 01 基础的两篇。之后 OpenAI 和 Claude 两条线可以并行阅读，二者在结构上是对称的；然后读 pi 和 DSH；最后读对比篇。

目录#

01 基础#

篇目	一句话
1.1 从 LLM API 到 Agent Harness 的分层	用 L0–L5 六层模型，把所有产品放到同一张地图上
1.2 Tool Calling 与 Agent Loop 原理	分别用 OpenAI 和 Anthropic 的原生 SDK 手写 agent 循环，理解原理

02 OpenAI（代码：Python）#

篇目	一句话
2.1 OpenAI 开发者生态全景	产品地图、演进时间线，以及 Responses、Agents SDK、Agents API 怎么选
2.2 OpenAI 客户端 SDK 与 Responses API	item 模型、三种状态策略、内置工具、结构化输出、流式输出
2.3 OpenAI Agents SDK	Agent、Runner、handoffs、护栏、sessions、tracing、Sandbox agents
2.4 OpenAI Agents API	托管的 Codex harness（beta）

03 Claude（代码：Python）#

篇目	一句话
3.1 Claude 开发者生态全景	一个端点，三种循环形态，再加一个托管选项
3.2 Anthropic 客户端 SDK 与 Messages API	content block、adaptive thinking、Tool Runner、缓存、refusal 与 fallback
3.3 Claude Agent SDK	把 Claude Code 当作库来用：子进程架构、权限判定顺序、hooks、subagents
3.4 Claude Managed Agents	托管的 harness（beta）：Agent、Environment、Session、Events

04 pi（代码：TypeScript）#

篇目	一句话
4.1 pi 全景与设计哲学	极简核心、“不做”清单、分层包结构
4.2 pi-ai 统一多模型 API	数十家厂商统一成一套接口，可以在对话中途切换模型 ✅ 已实际运行
4.3 pi-agent-core 最小 Agent 运行时	约 2,500 行的双层循环源码解读 ✅ 已实际运行
4.4 pi-coding-agent SDK 与扩展系统	SDK、树状会话、扩展、RPC

05 DSH（代码：TypeScript）#

篇目	一句话
5.1 DeepSeek Harness 全景	一切皆插件；profile、bundle、patch 层层叠加；与外部生态互通
5.2 Cordis 与一切皆插件	时空可组合性：插件、服务、inject、effect、waterfall ✅ 已实际运行
5.3 DSH 核心机制与插件开发	事件溯源日志、工具流水线、fail-closed 沙箱，以及写一个插件 ✅ 已实际运行

06 对比#

篇目	一句话
6.1 同一个任务的六种写法	一个天气助手的六种实现
6.2 横向对比与选型建议	总对比表、决策树、对“轻量”的再定义、学习路线

附录#

术语表：按字母排序的术语速查，标注了各 SDK 之间的含义差异
参考资料：一手资料汇总、源码 commit 快照，以及代码校验环境

知识地图#

Agent SDK 知识地图拖动平移 · 滚轮或双指缩放

01 基础：先建立分层地图，再理解循环

02 OpenAI · Python

03 Claude · Python

04 pi · TypeScript

05 DSH · TypeScript

06 对比：同一任务的六种写法，以及选型

附录

Agent SDK 知识地图
资料截至 2026-10-09，不随官方更新。各 SDK 的版本见每篇开头的「版本与时效声明」。
每一列是一家，每一行是六层模型里的一层；入口见 00 专题导读。

1.1 从 LLM API 到 Agent Harness 的分层阅读 →

1.2 Tool Calling 与 Agent Loop 原理阅读 →

版本基准
资料截至 2026-10-09

概览
产品地图与选型

L5 托管 Agent
厂商运行循环、沙箱和会话

L4 Harness
循环 + 内置工具 + 会话 + 权限

L3 Agent Loop
自动“调模型 → 执行工具 → 回填”

L1–L2 客户端 SDK
类型、重试、流式 + 工具调用

底座

关键词

openai 3.26.1 · openai-agents 0.23.1

anthropic 1.12.1 · claude-agent-sdk 0.2.164

@earendil-works/pi-* 1.1.0

@deepseek-ai/dsh 0.2.0-rc.2（开发者预览）

2.1 OpenAI 开发者生态全景阅读 →

2.4 OpenAI Agents API阅读 →

2.3 OpenAI Agents SDK阅读 →

Agents SDK 的 Runner 就在这一层：调模型、执行工具或 handoff、直到产出最终结果
→ 2.3 OpenAI Agents SDK

2.2 OpenAI 客户端 SDK 与 Responses API阅读 →

Responses items · Conversations · 托管工具 · Agent / Runner · handoffs · guardrails · sessions · tracing

3.1 Claude 开发者生态全景阅读 →

3.4 Claude Managed Agents阅读 →

3.3 Claude Agent SDK阅读 →

Tool Runner（beta）：SDK 替你跑循环，但只循环你自己定义的工具
→ 3.2 Anthropic 客户端 SDK 与 Messages API

3.2 Anthropic 客户端 SDK 与 Messages API阅读 →

content blocks · stop_reason · adaptive thinking · prompt caching · 权限判定顺序 · hooks · Managed Agents 事件流

4.1 pi 全景与设计哲学阅读 →

—
没有托管产品

4.4 pi-coding-agent SDK 与扩展系统阅读 →

4.3 pi-agent-core 最小 Agent 运行时阅读 →

4.2 pi-ai 统一多模型 API阅读 →

统一事件 · TypeBox 工具 · 跨厂商切换 · 双层循环 · steering / follow-up · 树状 JSONL 会话 · 扩展

5.1 DeepSeek Harness 全景阅读 →

—
没有托管产品

5.3 DSH 核心机制与插件开发阅读 →

dsh-agent-loop 插件：连循环本身都是一个可替换的插件
→ 5.3 DSH 核心机制与插件开发

dsh-llm 加适配器插件（llm-deepseek、llm-pi-ai 等）
→ 5.1 DeepSeek Harness 全景

5.2 Cordis 与一切皆插件阅读 →

Cordis · Service / inject / effect · profile / bundle / patch · 会话日志是唯一事实来源 · fail-closed 沙箱

术语按字母排序，并标注各 SDK 之间的含义差异；参考资料里有源码 commit 快照和代码校验环境。

然后读 OpenAI或并行读 Claude再读轻量级默认经 Responses API 调模型自己运行 → OpenAI 托管SDK 内置的 beta 功能自己部署 → Anthropic 托管逐层依赖逐层依赖一切皆插件复用 pi-aipi2dsh（社区）

写作约定#

来源：事实性的陈述都用脚注 [^n] 标注出处，优先使用官方文档和固定 commit 的源码链接。“笔者理解”“笔者观点”“笔者统计”这几类表述，是笔者自己的分析。
代码：每个 SDK 使用官方推荐的语言：OpenAI 和 Claude 用 Python，pi 和 DSH 用 TypeScript。代码都对照真实的 SDK 版本做过类型检查；标注“✅ 已实际运行”的代码，在本地跑通过，不需要 API Key。

验收清单#

每篇笔记的开头都有版本说明：涉及具体 SDK 的笔记用「版本与时效声明」写明版本号和资料截止日期；概念篇 1.1 注明不绑定版本
正文笔记（1.1–6.2）都有“本文要点”、至少一张图、小结、相关笔记、参考资料
事实性内容都标注了出处；二手资料单独注明
Python 代码块（51 个）全部通过 pyright 类型检查；TS 代码块（22 个）逐个通过 tsc strict 检查
pi（faux provider）与 DSH（Cordis 教程、weather-tool 插件）的关键示例已在本地实际运行
Mermaid 图（45 张）全部通过 Mermaid 11.17.2 的语法解析和渲染
SVG 插图（6 张）已渲染目检，并用脚本测量过：文字之间不重叠，也不越出边框
Excalidraw 图（3 张）已用 Excalidraw 0.18.1 载入、导出并目检，所有文字都放得进各自的形状
双链、嵌入、标题锚点和 Canvas 文件节点全部能解析，frontmatter 都是合法 YAML，脚注的引用和定义一一对应