OpenAI Agents SDKOpenAI Agents SDK

模型与开放条件Model & openness

官方自述 provider-agnostic。 官方的接入口径是一句话： 支持 OpenAI 两套 API，也支持 100+ 其他 LLM。

官方原文："It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs."

实现路径有两层证据：

• 核心依赖是 openai>=3.0.0。
• 可选依赖有两个 extra，都是非 OpenAI 路径。

两个 extra 分别是 litellm（openai-agents[litellm]） 与 any-llm（openai-agents[any-llm]，要求 Python ≥3.11）。

官方 models 页给出完整接入面（已核验）。 官方专列 "Non-OpenAI models" 与 "Third-party adapters" 两节。

两节里的接入点：

• 内置 provider 接入点可指向 OpenAI 兼容端点。
• 另有 Any-LLM / LiteLLM 两个 beta 适配器。

内置接入点的官方示例：

MultiProvider(openai_base_url="https://openrouter.ai/api/v1")

适配器的官方示例：

anthropic/claude-3-5-sonnet

LiteLLM 页上的口径是：一个接口接 100+ 模型，也可以用任何 AI 模型。

官方原文："allows you to use 100+ models via a single interface ... use any AI model in the Agents SDK"

换 provider 的改动量 = 换 model（字符串名 / LitellmModel(...) / provider 前缀）。

⚠ 但官方没有「零改动」的量化承诺，各家能力对齐度需实测。

The official self-description is provider-agnostic. The official access statement is one sentence: the OpenAI two APIs are supported, and so are 100+ other LLMs.

Official wording: "It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs."

The implementation path has two layers of evidence:

• The core dependency is openai>=3.0.0.
• There are two optional extras, both non-OpenAI paths.

The two extras are litellm (openai-agents[litellm]) and any-llm (openai-agents[any-llm], requires Python ≥3.11).

The official models page gives the full access surface (verified). The official docs dedicate "Non-OpenAI models" and "Third-party adapters" sections.

Access points in those sections:

• Built-in provider access points can point at OpenAI-compatible endpoints.
• Plus Any-LLM / LiteLLM beta adapters.

Official example of the built-in access point:

MultiProvider(openai_base_url="https://openrouter.ai/api/v1")

Official adapter example:

anthropic/claude-3-5-sonnet

The LiteLLM page's wording: one interface to 100+ models, and any AI model can be used.

Official wording: "allows you to use 100+ models via a single interface ... use any AI model in the Agents SDK"

Switching providers = change the model (a string name / LitellmModel(...) / provider prefix).

⚠ But the official docs make no "zero-change" quantitative promise; per-vendor capability alignment needs testing.

运行位置Where it runs

你自己运营进程 —— 它是库，不是服务。

README 的四种运行方式全部是本地代码调用：

• Runner.run_sync
• RealtimeRunner.run
• VoicePipeline.run
• sandbox client

唯一例外是 SandboxAgent 的 hosted sandbox client —— 官方提到可以用托管沙箱。

⚠ 但那依赖 OpenAI 侧的容器服务，不是「整个 agent 托管」。

You run the process yourself — it is a library, not a service.

All four run modes in the README are local code calls:

• Runner.run_sync
• RealtimeRunner.run
• VoicePipeline.run
• sandbox client

The only exception is SandboxAgent's hosted sandbox client — the official docs mention a hosted sandbox is available.

⚠ But that depends on OpenAI-side container services; it is not "the whole agent hosted".

本地文件Local files

本地文件能力明确存在，但不在默认 agent 里。

官方为「需要检查文件、跑命令、打补丁，或在长任务间保留工作区状态」 的场景单独提供了 SandboxAgent。

官方原文：SandboxAgent 是 preconfigured to work with a container to perform work over long time horizons

它的 default_manifest 里可以声明 GitRepo(repo=..., ref=...)。

沙箱客户端分平台：

• UnixLocalSandboxClient —— macOS / Linux。
• Windows 须用 DockerSandboxClient（需 openai-agents[docker] extra）。
• Windows 也可用 hosted sandbox client。

⚠ 这条是本站选型时的实用信息：Windows 用户不能直接用本地 Unix 沙箱路径。

Local-file capability explicitly exists, but not in the default agent.

For scenarios that "need to inspect files, run commands, apply patches, or preserve workspace state across longer tasks" the official docs provide SandboxAgent separately.

Official wording: SandboxAgent is preconfigured to work with a container to perform work over long time horizons

Its default_manifest can declare GitRepo(repo=..., ref=...).

Sandbox clients split by platform:

• UnixLocalSandboxClient — macOS / Linux.
• Windows must use DockerSandboxClient (requires the openai-agents[docker] extra).
• Windows can also use the hosted sandbox client.

⚠ A practical selection note: Windows users cannot use the local Unix sandbox path directly.

关机后的任务Tasks after shutdown

自托管 = 关了就停。 README 没有托管执行选项 （Realtime 是长连接，但进程仍在自己手里）。

断点续跑有官方支撑。 Sessions 章节写明 官方原文："Automatic conversation history management across agent runs"。

可选后端有 SQLite（SQLAlchemy 依赖）与 Redis（openai-agents[redis]）。

SandboxAgent 的 default_manifest 也面向 官方原文："preserve workspace state across longer tasks"。

Self-hosted = stop it and it's gone. The README has no hosted execution option (Realtime is a long connection, but the process stays in your hands).

Resuming after interruption has official support. The Sessions section states Official wording: "Automatic conversation history management across agent runs".

Optional backends include SQLite (SQLAlchemy dependency) and Redis (openai-agents[redis]).

SandboxAgent's default_manifest also targets Official wording: "preserve workspace state across longer tasks".

工具与扩展Tools & extensions

工具面是官方列出的四类：functions、MCP、hosted tools， 以及 agents as tools（把别的 agent 当工具调）。

后两类与 handoffs 并列，都是核心委派机制。

MCP 是核心依赖，不是可选。 这一点看 tools 的依赖声明：

• mcp>=1.19.0,<3 写在 dependencies 里。
• 它不在 optional-dependencies 里，是一等能力。

Guardrails 可配置。 官方列「Configurable safety checks for input and output validation」，分 input 与 output 两个方向。

The tool surface is the four kinds the official docs list: functions, MCP, hosted tools, and agents as tools (calling other agents as tools).

The latter two sit alongside handoffs as core delegation mechanisms.

MCP is a core dependency, not optional. See the dependency declaration:

• mcp>=1.19.0,<3 is in dependencies.
• It is not in optional-dependencies — a first-class capability.

Guardrails are configurable. The official list includes "Configurable safety checks for input and output validation", split into input and output directions.

上下文与记忆Context & memory

官方原文只有 Sessions。

官方原文："Automatic conversation history management across agent runs"

可选后端有 Redis（openai-agents[redis]） 与 SQLAlchemy（SQLAlchemy + asyncpg 依赖）。

注意与本站主张的分野。

Sessions 管的是会话历史。

本站的「状态 ≠ 上下文」主张里，把大工具输出落盘这类手段在本 SDK 属用户自建。

SandboxAgent 的沙箱工作区可以承担这个角色，但官方没有把它宣传成 context 管理层。

The official wording only has Sessions.

Official wording: "Automatic conversation history management across agent runs"

Optional backends include Redis (openai-agents[redis]) and SQLAlchemy (SQLAlchemy + asyncpg dependencies).

Note the divergence from our claim.

Sessions manages conversation history.

In our "state ≠ context" claim, measures like spilling large tool outputs to disk are user-built in this SDK.

SandboxAgent's sandbox workspace can play that role, but the official docs do not market it as a context-management layer.

权限与限制Permissions & limits

内建 Guardrails（输入 + 输出双向校验）+ Human in the loop（工具级审批）。

这是本站目前见到的权限面最完整的内建方案。两句官方原文：

官方原文："Configurable safety checks for input and output validation"

官方原文："Built-in mechanisms for involving humans across agent runs"

机制细节已核验（官方 guardrails 与 human_in_the_loop 专章）。 guardrails 共三类：

• input —— 只在链条第一个 agent 跑。
• output —— 只在产出最终输出的 agent 跑。
• tool —— 包 FunctionTool，执行前后各校验一次，可 skip/replace/raise tripwire。

第三条的 tripwire 命中即抛异常并立即中止。

input 侧可选 run_in_parallel=False，在 agent 启动前拦截。

工具级审批：needs_approval=True|callable 可用在 function_tool、ShellTool、ApplyPatchTool、Agent.as_tool。

MCP server 用 require_approval。

审批以 run-wide interruptions 暂停，RunState 可序列化/恢复。 参数无法安全解析时 fail closed，always_approve 可固化决策。

⚠ 边界要说清：官方没有内建文件/网络沙箱。

guardrails 是用户可编程的校验钩子；真正的沙箱边界交宿主机或 SandboxAgent 容器，不在 guardrail 层。

（已查 guardrails、human_in_the_loop、Sandbox agents 三页。）

与 Deep Agents 的「trust the LLM，边界责任交给你」形成鲜明对照。

Built-in Guardrails (input + output two-way validation) + Human in the loop (tool-level approval).

This is the most complete permissions surface we have seen built in so far. Two official lines:

Official wording: "Configurable safety checks for input and output validation"

Official wording: "Built-in mechanisms for involving humans across agent runs"

Mechanism details verified (official guardrails and human_in_the_loop chapters). Guardrails come in three kinds:

• input — runs only on the first agent in the chain.
• output — runs only on the agent producing the final output.
• tool — wraps FunctionTool, validates before and after execution; can skip/replace/raise a tripwire.

The third kind's tripwire throws an exception and aborts immediately.

On the input side, run_in_parallel=False optionally intercepts before the agent starts.

Tool-level approval: needs_approval=True|callable works on function_tool, ShellTool, ApplyPatchTool, Agent.as_tool.

MCP servers use require_approval.

Approvals pause via run-wide interruptions; RunState is serializable/resumable. When arguments cannot be safely parsed it fails closed; always_approve can pin a decision.

⚠ State the boundary: the official docs have no built-in file/network sandbox.

guardrails are user-programmable validation hooks; the real sandbox boundary is left to the host machine or the SandboxAgent container, not the guardrail layer.

(guardrails, human_in_the_loop, and Sandbox agents pages checked.)

This contrasts sharply with Deep Agents' "trust the LLM, boundary responsibility is yours".

适合什么任务Best for

适合：

• 想要「薄 harness」，agent loop 原语之外的自己挑。
• 需要 guardrails 与 human-in-the-loop 是内建的。
• 需要 MCP 一等支持，团队是 Python 栈。

不适合：

• 想要开箱即用的长任务工作区。
• 追求 TypeScript 生态（该用 openai-agents-js）。

不适合的两条各有替代路线。长任务工作区用 Deep Agents， 或走该 SDK 的 SandboxAgent 路线。

Fits:

• You want a "thin harness" and choose everything beyond the agent loop primitives yourself.
• You need guardrails and human-in-the-loop built in.
• You need first-class MCP support and your team is on Python.

Does not fit:

• You want a batteries-included long-task workspace.
• You are in the TypeScript ecosystem (use openai-agents-js).

Both "does not fit" items have alternative routes: for the long-task workspace use Deep Agents, or take this SDK's SandboxAgent route.

agent = SandboxAgent(
    name="Workspace Assistant",
    default_manifest=Manifest(
        entries={"repo": GitRepo(repo="openai/openai-agents-python", ref="main")}
    ),
)

agent = SandboxAgent(
    name="Workspace Assistant",
    default_manifest=Manifest(
        entries={"repo": GitRepo(repo="openai/openai-agents-python", ref="main")}
    ),
)

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.