Tlrince Notes
返回专栏
Agent SDK/01 · 基础/1.1

从 LLM API 到 Agent Harness 的分层

在 Agent 领域，“SDK”这个词被用得非常宽泛：openai 包、OpenAI Agents SDK、Claude Agent SDK、Tool Runner、pi、DSH 都被称为 SDK，但它们解决的问题不在同一层。

Tlrince发布于 2026-10-09
预计阅读
14分钟
全文字数
3,173字
资料截至
2026-10-09
#agent-sdk/基础#agent
Agent SDK · 基础1.1
本文要点
  1. 在 Agent 领域，“SDK”这个词被用得非常宽泛：openai 包、OpenAI Agents SDK、Claude Agent SDK、Tool Runner、pi、DSH 都被称为 SDK，但它们解决的问题不在同一层。
  2. 本文把 Agent 技术栈拆成 L0–L5 六层，并把 OpenAI、Claude、pi、DSH 的每个产品放到对应的位置。
  3. 选型本质上是在回答一个问题：这一层你想自己写，还是交给别人？
关于版本

这是一篇概念性文章，不绑定具体的 SDK 版本。文中各产品归属哪一层，以 2026-10-09 各官方文档为准，出处见文末脚注。各 SDK 的具体版本号，见对应专题笔记开头的「版本与时效声明」。

1. 为什么需要一张分层图#

先看一组容易混淆的名字：

名字它实际是什么所在层（见下文）
openai（Python 包）OpenAI REST API 的官方客户端库L1
OpenAI Agents SDK（openai-agents）构建在 Responses API 之上的 Agent 运行时，包含 Runner、handoffs、guardrails、sessions 等L3，部分能力到 L4
OpenAI Agents API（beta）OpenAI 托管的 Codex harnessL5
anthropic（Python 包）Claude API 客户端库，其中带一个 beta 的 Tool RunnerL1（Tool Runner 属于 L3）
Claude Agent SDK把 Claude Code 打包成库，带内置工具、权限、会话和 hooksL4
Claude Managed Agents（beta）Anthropic 托管的 harness 加沙箱L5
pi一组分层的包：pi-ai（L1）、pi-agent-core（L3）、pi-coding-agent（L4）L1–L4
DSH（DeepSeek Harness）基于 Cordis 的“一切皆插件” harnessL1–L4，每层都是插件

Anthropic 的官方文档专门用一张表区分了 Agent SDK、Claude Code CLI、Client SDK（含 tool runner）和 Managed Agents，区分的依据是“谁来运行 agent、内置了什么、通过什么方式访问”1。OpenAI 的文档也给出了 Agents API、Agents SDK、Responses API 三者的对比表2。两家厂商都在主动澄清这件事，说明它确实容易混淆。

2. 六层模型#

agent-sdk-layers.svg
读图方法

从下往上看：每往上一层，框架替你做的事就多一些，你能直接控制的细节就少一些。

L0 · 模型 HTTP API#

  • 本质：一个 HTTP 接口，例如 OpenAI 的 POST /v1/responses、Anthropic 的 POST /v1/messages。
  • 有状态还是无状态
    • Claude 的 Messages API 是无状态的，每次请求都要带上完整的对话历史3。
    • OpenAI 的 Responses API 默认会把 response 存储 30 天（可用 store: false 关闭），你可以用 previous_response_id 或 Conversations API 让服务端帮你接续上下文4。
  • 你需要自己处理：鉴权、序列化、重试、超时、SSE 流式解析。

L1 · 客户端 SDK（Client SDK）#

  • 把 L0 包装成类型安全的方法调用，例如 client.responses.create(...)、client.messages.create(...)。
  • 典型能力：类型定义、自动重试、超时控制、流式 helper、分页。以 Anthropic Python SDK 为例，它默认对连接错误以及 408、409、429 和 5xx 自动重试 2 次，默认超时为 10 分钟5。
  • 特例：pi-ai 是一个“统一多厂商”的 L1。它用同一套 Context 和消息格式对接 OpenAI、Anthropic、Google、DeepSeek 等数十家提供方，并支持在对话中途切换模型6。

L2 · 工具调用协议（Tool Calling / Function Calling）#

  • 模型本身不会执行任何代码。它只会返回一个结构化的请求，意思是“我想调用某个函数，参数是这些”；真正执行的是你的程序7。
  • 按执行位置可以分成两类8：
    • 客户端工具：由你的程序执行，比如你自己定义的 get_weather。
    • 服务端工具：由厂商执行，比如 web search、code execution。
  • 完整的往返过程见 1.2 Tool Calling 与 Agent Loop 原理。

L3 · Agent Loop（智能体循环）#

  • 自动重复“调用模型 → 执行工具 → 把结果放回上下文 → 再调用模型”，直到模型不再请求工具为止。
  • 代表实现：
    • OpenAI Agents SDK 的 Runner9
    • Anthropic SDK 的 beta Tool Runner（client.beta.messages.tool_runner）10
    • pi-agent-core 的 Agent 类11
    • DSH 的 agent-loop 插件12

L4 · Harness（驾驭层，即完整的 Agent 运行时）#

“harness”原意是马具：给模型这匹马套上缰绳和车辕，它才能拉车干活。在 Agent 语境里，harness 指的是在 L3 循环之外再加上一整套“干活的设施”：

组件作用Claude Agent SDKpi-coding-agentDSH
内置工具读写文件、执行命令、搜索Read、Edit、Write、Bash、Glob、Grep、WebSearch 等13默认只启用 read、bash、edit、write 四个14tool-fs、tool-bash、tool-fs-search 等插件15
上下文管理接近窗口上限时压缩历史自动 compaction13compaction16compaction 插件族17
会话持久化恢复、分叉JSONL 会话，支持 resume、fork18树状 JSONL，支持分支16事件溯源的 session log12
权限与沙箱拦截危险操作权限模式加 hooks13不内置权限系统，靠扩展或容器19沙箱阶梯加审批，fail-closed20
扩展机制定制行为hooks、subagents、skills、plugins、MCP1extensions、skills、packages19一切皆插件（Cordis）12

三者对自己的定位：

  • Claude Agent SDK：提供与 Claude Code 相同的工具、agent loop 和上下文管理1。
  • pi：自称 a minimal, extensible agent harness19。
  • DSH：自称开源的 agent harness，架构是“一切皆插件”21。
  • OpenAI：Agents SDK 里的 Sandbox Agents 补上了 workspace、文件和 shell 这一类 harness 能力22。

L5 · 托管 Agent 服务（Hosted Agents）#

  • 由厂商替你运行 harness、沙箱和会话存储，你只通过 REST 接口和 SSE 事件流与它交互。
  • 目前的代表：
“服务端工具”不等于 L5

Responses API 的 web_search、Claude 的 code_execution 只是让厂商代为执行某一个工具，循环本身仍可能在你的程序里。L5 指的是整个循环加运行环境都放在厂商那边。

3. 四家产品在分层上的位置#

DSH（DeepSeek）

pi（Earendil）

Claude / Anthropic

OpenAI

dsh-llm-pi-ai 适配器复用 pi-ai

L5 · Agents API（beta）

L4 · Agents SDK + Sandbox Agents

L3 · Agents SDK Runner

L1 · openai 包

L0 · Responses API

L5 · Managed Agents（beta）

L4 · Claude Agent SDK

Claude Code CLI 子进程

L3 · Tool Runner（beta）

L1 · anthropic 包

L0 · Messages API

L4 · pi-coding-agent

L3 · pi-agent-core

L1 · pi-ai（统一多厂商）

L4 · dsh 运行时（profile 组合）

L3 · dsh-agent-loop 插件

L1 · dsh-llm 接口 + 适配器插件

DeepSeek API

DSH（DeepSeek）

pi（Earendil）

Claude / Anthropic

OpenAI

dsh-llm-pi-ai 适配器复用 pi-ai

L5 · Agents API（beta）

L4 · Agents SDK + Sandbox Agents

L3 · Agents SDK Runner

L1 · openai 包

L0 · Responses API

L5 · Managed Agents（beta）

L4 · Claude Agent SDK

Claude Code CLI 子进程

L3 · Tool Runner（beta）

L1 · anthropic 包

L0 · Messages API

L4 · pi-coding-agent

L3 · pi-agent-core

L1 · pi-ai（统一多厂商）

L4 · dsh 运行时（profile 组合）

L3 · dsh-agent-loop 插件

L1 · dsh-llm 接口 + 适配器插件

DeepSeek API

图中几条依赖关系的出处：

  • Agents SDK 默认通过 Responses API 调用 OpenAI 模型26。
  • Claude Agent SDK 会启动并管理一个 claude CLI 子进程，通过 stdio 与它通信27。
  • pi 的三个包逐层依赖11。
  • DSH 有一个基于 pi-ai 的适配器插件 dsh-llm-pi-ai，作者称它为官方 DeepSeek 适配器的“设计验证孪生”28。
一个有意思的事实

这一节的两个“轻量级”项目之间有真实的代码联系：DSH 的 LLM 层可以直接借用 pi-ai 的多厂商能力。

4. 一个 Agent 由什么组成#

Agent 解剖图Agent 解剖图
Agent 解剖图
部件比喻说明对应层
模型（LLM）大脑决定下一步做什么L0 / L1
指令（system prompt）岗位说明书告诉模型它是谁、该怎么做L1
工具（tools）手和脚读写文件、调用 API、执行命令L2
循环（loop）心跳反复执行“思考 → 行动 → 观察”L3
上下文与记忆工作台当前对话、工具结果、压缩后的摘要L3 / L4
会话存储日记本可以恢复、分叉、回放L4
运行环境与沙箱工位和围栏让工具在受控的环境里执行L4 / L5
护栏与权限安全员校验输入输出，审批危险操作L3 / L4
可观测性（tracing）行车记录仪记录每一步，方便调试和评估L3 / L4

5. 关键术语速查#

更完整的定义见 术语表。

术语一句话解释
AgentOpenAI 的定义是“配备了指令和工具的 LLM”26；Claude Agent SDK 的定义是“通过自己规划步骤、调用工具来完成任务的应用”1
HarnessAgent 的完整运行时，等于循环加工具、上下文、会话、权限、扩展机制（见上文 L4）
Tool / Function Calling模型输出结构化的调用请求，由程序执行后把结果回传给模型7
服务端工具 / Hosted Tool由厂商代为执行的工具，例如 web search、code interpreter8
MCPModel Context Protocol，一个开放协议，规定应用如何以标准方式向 LLM 提供工具和上下文29
Skills可复用的“说明书 + 脚本”包，通常是一个带 SKILL.md 的目录，在需要时才加载3016
Handoff / Subagent多 Agent 协作：控制权转交给另一个 agent（handoff），或者派生一个子 agent 去完成子任务（subagent）3132
Guardrail对输入、输出或工具调用做校验，不通过就中断执行33
Compaction上下文接近窗口上限时，把较早的历史压缩成摘要13
Sandbox隔离的执行环境，限制工具能读写哪些文件、能访问哪些网络20
同一个词，不同 SDK 里含义不同

以“turn”为例：

  • Claude Agent SDK 中，一个 turn 是循环里的一次往返，即一次模型输出加上它触发的工具执行13。
  • DSH 中，“步骤”（step）指一次模型请求加它调用的工具，而“轮次”（turn）包含零个或多个步骤，要处理完已接纳的输入才结束34。

阅读文档时，务必看清各家自己的定义。

6. 怎么用这张图做选型#

你的需求建议的起点
只是调用模型做摘要、分类、抽取L1 客户端 SDK
自定义工具，并且想完全控制流程L1 + 手写循环（参考 1.2 Tool Calling 与 Agent Loop 原理）
想少写循环代码，但工具都是自己的L3：Agents SDK、Tool Runner、pi-agent-core
需要一个能读写文件、跑命令的“干活型” agentL4：Claude Agent SDK、pi-coding-agent、DSH
不想运维，要长时间运行和托管沙箱L5：Managed Agents、Agents API
要多厂商切换，或者想完全掌控上下文pi、DSH

详细对比见 6.2 横向对比与选型建议；用同一个任务对比几种写法，见 6.1 同一个任务的六种写法。

小结#

  • L1 解决“怎么调用模型”，L3 解决“怎么循环”，L4 解决“怎么让循环真正去干活”，L5 解决“谁来运维”。
  • OpenAI 和 Claude 在每一层都有官方产品；pi 和 DSH 则把 L1 到 L4 全部开源，并且可以替换。
  • 后续各篇都会先回答“它处在哪一层”，再展开讲细节。

相关笔记#

参考资料#

注释与出处#

  1. Anthropic，Agent SDK overview，https://code.claude.com/docs/en/agent-sdk/overview （访问于 2026-10-09） ↩ ↩2 ↩3 ↩4

  2. OpenAI，Agents（Agents API、Agents SDK、Responses API 对比表），https://developers.openai.com/api/docs/guides/agents ↩

  3. Anthropic，Working with the Messages API，原文写明 “The Messages API is stateless”，https://platform.claude.com/docs/en/build-with-claude/working-with-messages ↩

  4. OpenAI，Conversation state（含 previous_response_id、Conversations API、30 天存储说明），https://developers.openai.com/api/docs/guides/conversation-state ↩

  5. Anthropic，Python SDK（Retries 与 Timeouts 两节），https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python ↩

  6. earendil-works/pi，packages/ai/README.md（commit 6fb2e78），https://github.com/earendil-works/pi/blob/6fb2e7815167e6b19006fc526d1a5d0f5f998787/packages/ai/README.md ↩

  7. OpenAI，Function calling，https://developers.openai.com/api/docs/guides/function-calling ↩ ↩2

  8. Anthropic，Tool use with Claude（客户端工具与服务端工具），https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview ↩ ↩2

  9. openai/openai-agents-python，docs/running_agents.md（commit 26345c1），https://github.com/openai/openai-agents-python/blob/26345c1e45ebede8e2fc9b0bc7341dedab5e01fc/docs/running_agents.md ↩

  10. Anthropic，Tool Runner (SDK)，https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner ↩

  11. earendil-works/pi，packages/agent/README.md，https://github.com/earendil-works/pi/blob/6fb2e7815167e6b19006fc526d1a5d0f5f998787/packages/agent/README.md ↩ ↩2

  12. deepseek-ai/deepseek-harness，docs/architecture.zh.md（commit 5badb15），https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/docs/architecture.zh.md ↩ ↩2 ↩3

  13. Anthropic，How the agent loop works，https://code.claude.com/docs/en/agent-sdk/agent-loop ↩ ↩2 ↩3 ↩4 ↩5

  14. earendil-works/pi，packages/coding-agent/src/core/settings-manager.ts 第 83 行 DEFAULT_TOOL_NAMES，https://github.com/earendil-works/pi/blob/6fb2e7815167e6b19006fc526d1a5d0f5f998787/packages/coding-agent/src/core/settings-manager.ts#L83 ↩

  15. deepseek-ai/deepseek-harness，packages/bundle/web-app/presets/standard.patch.yml，https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/packages/bundle/web-app/presets/standard.patch.yml ↩

  16. earendil-works/pi，packages/coding-agent/docs/how-pi-works.md，https://github.com/earendil-works/pi/blob/6fb2e7815167e6b19006fc526d1a5d0f5f998787/packages/coding-agent/docs/how-pi-works.md ↩ ↩2 ↩3

  17. deepseek-ai/deepseek-harness，packages/compaction/，https://github.com/deepseek-ai/deepseek-harness/tree/5badb15009ae1756c3afe0ae0cef1faafc290ccc/packages/compaction ↩

  18. Anthropic，Work with sessions，https://code.claude.com/docs/en/agent-sdk/sessions ↩

  19. earendil-works/pi，根目录 README.md（含 “Permissions & Containerization” 一节），https://github.com/earendil-works/pi/blob/6fb2e7815167e6b19006fc526d1a5d0f5f998787/README.md ↩ ↩2 ↩3

  20. deepseek-ai/deepseek-harness，packages/sandbox/sandbox/README.zh.md，https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/packages/sandbox/sandbox/README.zh.md ↩ ↩2

  21. deepseek-ai/deepseek-harness，README.zh.md，https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/README.zh.md ↩

  22. openai/openai-agents-python，docs/sandbox_agents.md，https://github.com/openai/openai-agents-python/blob/26345c1e45ebede8e2fc9b0bc7341dedab5e01fc/docs/sandbox_agents.md ↩

  23. Anthropic，Release notes，2026-04-08 条目：“launched Claude Managed Agents in public beta”，https://platform.claude.com/docs/en/release-notes/overview ↩

  24. OpenAI，Agents API，https://developers.openai.com/api/docs/guides/agents-api/overview ↩

  25. openai/openai-python，CHANGELOG.md 中 3.13.0（2026-09-10）条目 “add Agents API”，https://github.com/openai/openai-python/blob/9301e319ea33ef28fba380f39a289dedc14652c1/CHANGELOG.md ↩

  26. openai/openai-agents-python，docs/index.md，https://github.com/openai/openai-agents-python/blob/26345c1e45ebede8e2fc9b0bc7341dedab5e01fc/docs/index.md ↩ ↩2

  27. Anthropic，Hosting the Agent SDK（The subprocess model 一节），https://code.claude.com/docs/en/agent-sdk/hosting ↩

  28. deepseek-ai/deepseek-harness，packages/llm/llm-pi-ai/package.json 的 description 字段，https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/packages/llm/llm-pi-ai/package.json ↩

  29. Model Context Protocol 官方介绍，https://modelcontextprotocol.io/introduction ↩

  30. Anthropic，Agent Skills overview，https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩

  31. openai/openai-agents-python，docs/multi_agent.md，https://github.com/openai/openai-agents-python/blob/26345c1e45ebede8e2fc9b0bc7341dedab5e01fc/docs/multi_agent.md ↩

  32. Anthropic，Subagents in the SDK，https://code.claude.com/docs/en/agent-sdk/subagents ↩

  33. openai/openai-agents-python，docs/guardrails.md，https://github.com/openai/openai-agents-python/blob/26345c1e45ebede8e2fc9b0bc7341dedab5e01fc/docs/guardrails.md ↩

  34. deepseek-ai/deepseek-harness，docs/glossary.zh.md（“循环层级”一节），https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/docs/glossary.zh.md ↩

输入关键词开始搜索。多个关键词用空格分隔。