← Harness

模型与开放条件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 前缀）。

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

运行位置Where it runs

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

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

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

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

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

本地文件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 沙箱路径。

关机后的任务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"。

工具与扩展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 两个方向。

上下文与记忆Context & memory

官方原文只有 Sessions。

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

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

注意与本站主张的分野。

Sessions 管的是会话历史。

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

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

权限与限制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，边界责任交给你」形成鲜明对照。

适合什么任务Best for

适合：

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

不适合：

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

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

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