Agent 与 Skills约 10 分钟

Agents API 与 Agents SDK 区别：8 维度对比表

AI 指南·更新于 2026-09-14·◉ 0 浏览

Agents API 是 OpenAI 托管的云上 Agent 运行时（公测中），Agents SDK 是跑在你应用里的 TS/Python 编排框架。本文用 8 个维度对比边界、计费、合规与选型建议。

一句话结论：想让 OpenAI 帮你托管 Agent 的运行时（会话、沙箱、上下文管理全套省心），选 2026 年 9 月 10 日公测的 Agents API；想在自己服务器里用 TypeScript/Python 代码完全掌控 Agent 循环的每个细节，选一直都在的 Agents SDK。两者不冲突，同一个产品里完全可以共存。

这个结论的依据是官方文档的明确表述：Agents SDK 文档写着"Agents SDK runs in your application; the Agents API runs a managed harness in OpenAI's service"。下面用 8 个维度拆开讲。

一张总对比表

维度	Agents API	Agents SDK	来源
定位	OpenAI 托管的 Codex 执行环境，云上 Agent 运行时	代码优先的本地编排框架	官方两篇文档
运行位置	OpenAI 基础设施上跑 Agent 循环	你的应用/服务器里跑	SDK 文档对比章节
接入方式	HTTP 接口 + 官方 SDK（含 `OpenAI-Beta: agents=v1` 头）	TypeScript / Python 包	快速开始文档
执行环境	openai_hosted 托管沙箱、self_hosted、E2B/Modal/Daytona 等第三方	由你的代码决定（SDK 也有 sandbox agents 概念）	环境文档
会话与状态	持久化会话，可跨轮继续、断流恢复	状态由应用自己保存	两篇文档
计费	API 无附加费；模型/工具按标准价，托管沙箱收容器费	包本身免费，模型 token 正常计费	社区公告 + 定价页
数据驻留	仅美国，不支持 ZDR	取决于你的部署	API 概览文档
适合人群	想快速上线、不想管运行的团队	要深度定制循环与基础设施的团队	综合官方描述

分维度详解

1. 定位与运行位置

Agents API 把 Codex 背后的执行环境（harness）开放成云服务：OpenAI 帮你管会话、编排、上下文压缩和恢复，你的应用只负责给任务、收事件。Agents SDK 则相反，Agent 循环、工具调用、状态保存全部发生在你的进程里，你写的是普通的应用代码。来源：Agents API 概览、SDK 文档。

2. 语言与接入

Agents API 是接口优先：任何语言都能走 HTTP，官方另提供 JS/Python/Go/Java/Ruby SDK 封装，curl 也行。Agents SDK 是代码优先：目前只有 TypeScript 和 Python 两个实现（openai-agents-js、openai-agents-python）。用 Go 或 Java 的团队，SDK 这条路走不通。

3. 执行环境与沙箱

Agents API 的环境是配置项：openai_hosted 一行参数就能拿到托管沙箱，也能切 self_hosted 或接 E2B、Modal、Daytona、Runloop、Vercel、Cloudflare、Blaxel、DigitalOcean、OCI 这些第三方沙箱。Agents SDK 里沙箱是你自己搭的执行环境（sandbox agents），编排和执行分离的思路一致，但搭建和维护都是你的事。

4. 会话持久化

Agents API 的 session 是持久对象：任务做完可以追加输入继续聊，流断了可以找回会话和已保存的产出。Agents SDK 的历史与状态由你的应用决定存哪里，灵活但都是你的工作量。

5. 计费

两者 API 层面都不加收费用。差异在执行环境：Agents API 用托管沙箱时按容器规格收费（官方定价页：1GB $0.03、4GB $0.12、16GB $0.48、64GB $1.92，每 20 分钟一个计费单元）；Agents SDK 用自己的机器，没有这笔钱。来源：OpenAI 开发者社区公告（2026-09-10）与官方定价页。

6. 数据驻留与合规

Agents API 概览明确写着：目前仅支持美国数据驻留、不支持 Zero Data Retention，选 self-hosted 沙箱也不会让整个 API 变成 ZDR 合规。对数据出境有硬要求的团队，这条几乎是决定性的；Agents SDK 因为跑在你自己的基础设施上，合规边界由你定义。

7. 能力细节差异

多 Agent：Agents API 建会话时配 multi_agent 即可让主 Agent 派发子 Agent（可限并发数）；Agents SDK 的编排（handoffs、agents-as-tools）由你在代码里设计，粒度更细。
权限：Agents API 的 key 需要 api.agents.read、api.agents.write 加 api.responses.write；Agents SDK 只需要普通的模型调用权限。
观测：两边都有 tracing 能力，Agents API 还提供会话级 observability 文档与 webhook。

场景化推荐

内部工具、Slack 机器人、工单自动化：选 Agents API。 Incident 响应、Slack bot、数据分析师这些官方示例（见 API 概览的 showcase）本质都是"给任务、收结果"，托管会话和沙箱能省掉一整个运维面。
现有产品里的深度集成：选 Agents SDK。你的服务已经有一套部署、权限、存储体系，SDK 让 Agent 循环长在现有代码里，不用迁就托管环境的行为。
数据不能出域：Agents API 的 self_hosted 只解决执行位置，控制面仍在 OpenAI 且不支持 ZDR；强合规场景倾向 Agents SDK 自建。
只想快速验证想法：先跑 Agents API 的托管沙箱快速开始，一个文件就能看到 Agent 写代码、跑代码的全过程，验证成本最低。

迁移与共存成本

两个方向都不算伤筋动骨，因为 Agent 定义（模型、指令、工具）在两边概念一致：

从 SDK 迁到 API：主要是把工具实现改为通过 API 会话提交，自建沙箱改挂成 self_hosted 环境或第三方 provider；注意 Beta 头与 key 权限变化。
从 API 迁回 SDK：会话持久化和托管恢复要自己补，等价于把"省心"换回"控制权"。
共存：完全可行。常见的做法是交互式链路用 SDK（低延迟、进程内），长任务后台用 Agents API（托管、可恢复）。背景知识不够的话，先读什么是 AI Agent和AI Agent 工作流入门；工具体系的关系可以看 MCP、Skill 与 Agent 的区别；想把 Codex 用明白的，参考OpenAI Codex 完整指南。

常见问题 FAQ

Agents API 会取代 Agents SDK 吗？

官方文档把两者并列为不同的运行时选项，没有替代关系的表述；一个管托管运行，一个管本地编排，按场景选即可。

用 Agents API 还要付沙箱容器费吗？

用 OpenAI 托管沙箱时要收，按容器规格每 20 分钟计费（1GB 规格 $0.03 起）；换成 self_hosted 或第三方沙箱则容器费由对应方收取或不产生，模型 token 两边都照常计费。

Agents SDK 支持 Go 或 Java 吗？

SDK 本身只有 TypeScript 和 Python 实现；Go/Java/Ruby 团队想用托管运行时可以直接调 Agents API 的 HTTP 接口或用对应语言的 OpenAI SDK。

Agents API 现在是正式版吗？

不是。2026 年 9 月 10 日起为公开测试（public beta），请求需带 OpenAI-Beta: agents=v1，接口仍可能变化，生产使用要有心理准备。

两者可以混用吗？

可以。模型、指令、工具的配置概念两边通用，常见组合是实时链路用 SDK、后台长任务用 Agents API，按需拆分即可。

作者：AI345

最后更新于 2026 年 9 月