Agents API 与 Agents SDK 区别：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 个维度拆开讲。

一张总对比表

分维度详解

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 这条路走不通。

顺带把 SDK 的版本与运行门槛补齐：Python 版当前是 v0.22.3，要求 Python 3.10 或更高，安装命令 pip install openai-agents（语音能力装 openai-agents[voice]，Redis 会话装 openai-agents[redis]）。仓库对口很活跃，openai-agents-python 已有约 29.5k star、4.8k fork，属于还在快速迭代的版本，锁依赖时要留意小版本变化。

3. 执行环境与沙箱

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

SDK 侧的具体形态在官方文档里写得很清楚：sandbox agents 用 manifest 描述工作区文件，沙箱客户端可选 UnixLocalSandboxClient（仅 macOS / Linux）或 DockerSandboxClient（Windows 上要装 openai-agents[docker] 或用托管沙箱客户端）。也就是说，Windows 用户直接跑本地沙箱这条路是不通的，这是很多人在跨平台迁移时才发现的坑。

4. 会话持久化

Agents API 的 session 是持久对象：任务做完可以追加输入继续聊，流断了可以找回会话和已保存的产出。Agents SDK 的历史与状态由你的应用决定存哪里，灵活但都是你的工作量。SDK 内置了几种 session 后端可选：SQLAlchemy、Redis、MongoDB、Dapr，以及加密 session，官方还提供高级 SQLite session，按你的存储栈挑即可。

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. 能力细节差异

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

8. Agents SDK 的能力地图（官方文档可查）

SDK 的核心只有三个原语：Agents（带指令和工具的 LLM）、Agents as tools / Handoffs（Agent 之间委派）、Guardrails（输入输出校验）。在它们之上，官方文档给出了这些能力模块，选型时可以对照自己需要的功能：

1. Sandbox agents：在真实隔离工作区里干长任务的专家 Agent，支持 manifest 定义文件、可恢复会话。
2. Realtime agents：基于 gpt-realtime-2.1 的低延迟语音/多模态 Agent。
3. Voice agents：语音转文字 + Agent 工作流 + 文字转语音的管线。
4. Sessions：跨轮记忆层（SQLAlchemy / Redis / MongoDB / Dapr / 加密）。
5. MCP server tool calling：内置把远程 MCP 工具暴露给 Agent 的能力。
6. Tracing：可视化、调试、监控 Agent 运行，接 OpenAI 的评估与微调工具链。

它还是 provider-agnostic 的：官方文档写明支持 OpenAI Responses / Chat Completions，也能接 100+ 其他 LLM。

场景化推荐

1. 内部工具、Slack 机器人、工单自动化：选 Agents API。 Incident 响应、Slack bot、数据分析师这些官方示例（见 API 概览的 showcase）本质都是"给任务、收结果"，托管会话和沙箱能省掉一整个运维面。
2. 现有产品里的深度集成：选 Agents SDK。你的服务已经有一套部署、权限、存储体系，SDK 让 Agent 循环长在现有代码里，不用迁就托管环境的行为。
3. 数据不能出域：Agents API 的 self_hosted 只解决执行位置，控制面仍在 OpenAI 且不支持 ZDR；强合规场景倾向 Agents SDK 自建。
4. 只想快速验证想法：先跑 Agents API 的托管沙箱快速开始，一个文件就能看到 Agent 写代码、跑代码的全过程，验证成本最低。
5. 该不该干脆只用 Responses API：官方给了一条很实用的判据。要自己掌控 loop、工具分发和状态管理，或工作流很短、只是想拿模型回复，就直接用 Responses API；要让 runtime 帮你管轮次、工具执行、Guardrails、Handoffs、Sessions，或需要真实工作区和可恢复执行，就上 Agents SDK。两者不必全局二选一，很多应用是 SDK 管编排、Responses API 走底层路径混着用。

踩坑与前提：选之前先确认这几条

1. SDK 官方只维护 Python 与 TypeScript 两个实现，Go / Java / Ruby 团队只能走 Agents API 的 HTTP 接口或对应语言 SDK，别指望社区包能长期跟上官方节奏。
2. Windows 上跑 SDK 的本地沙箱要用 Docker 客户端（openai-agents[docker]），UnixLocalSandboxClient 只在 macOS / Linux 可用。
3. Python 版本低于 3.10 装不上，CI 镜像要提前升。
4. Agents API 现在还是 public beta，请求要带 OpenAI-Beta: agents=v1，接口仍可能变化，放生产要有回滚预案。
5. Agents API 目前仅美国数据驻留、不支持 ZDR，这条对国内或欧盟合规团队往往是硬约束。

迁移与共存成本

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

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