OpenAI Agents SDK实战：Harness与沙盒分离架构详解

模型能力跃升催生新一代智能体框架

OpenAI 在最新一期 Build Hours 中，由 API 团队工程师 Steve 和 Agents 产品经理 Nish 深入讲解了 Agents SDK 的重大更新。核心信息非常明确：模型正在变得越来越擅长长时间自主工作，而 Agents SDK 的目标就是让开发者能够轻松构建、部署和管理这类长效智能体。

这里所说的"智能体"（Agent），是指能够感知环境、自主决策并执行行动的AI系统。与传统的单轮问答不同，智能体具备持续运行、工具调用和多步推理的能力，能够在复杂任务中自主规划和执行。近两年来，随着大语言模型推理能力的飞速提升，智能体从学术概念迅速走向工程实践，成为AI应用的核心范式之一。

值得注意的是，这一跃升有其历史脉络。从2022年的ChatGPT到2024年的o1/o3系列，大语言模型的推理能力经历了质的飞跃。早期的智能体框架（如LangChain、AutoGPT）虽然概念超前，但受限于模型的指令遵循能力和工具调用稳定性，在生产环境中频繁出现幻觉、循环和任务偏离等问题。随着模型在长程推理、代码生成和工具使用上的持续突破，智能体的可靠性阈值终于跨越了工程实用的临界点，催生了以Agents SDK为代表的新一代生产级框架。

Steve 提到，OpenAI 内部的 Codex 工具已经能够连续运行数天甚至一周。Codex 是 OpenAI 推出的云端软件工程智能体，它能够在隔离的沙盒环境中自主阅读代码、编写代码、运行测试，本质上是一个"永不疲倦的程序员"。基于 Codex 构建的安全扫描智能体可以自动检测代码库中的安全漏洞，数据分析智能体则能直接连接数据湖回答复杂查询——以前需要花一小时写 SQL 的工作，现在只需一句提示词。所谓数据湖（Data Lake），是一种集中存储海量原始数据的架构，支持结构化、半结构化和非结构化数据的统一存储与分析，是现代企业数据基础设施的核心组件。

然而，在自己的系统中构建生产级智能体仍然很难。如何平衡性能与灵活性？如何管理沙盒容器的生命周期和状态？如何让框架足够可定制？Agents SDK 的最新更新正是为了解决这些痛点。

Agents SDK 架构革新：Harness 与 Compute 分离

本次更新中最关键的架构决策是将 Harness（编排层）与 Compute（计算沙盒）彻底分离。

这一架构决策本质上是将"控制平面"与"数据平面"解耦，是分布式系统设计中的经典模式。控制平面（Harness）负责状态机管理、任务调度和错误恢复，数据平面（Compute沙盒）负责实际代码执行。这种解耦使得两个层面可以独立扩展和替换，同时也是实现高可用性的前提——当某个沙盒节点故障时，控制平面可以在另一个节点无缝重建执行环境，而不影响整体任务进度。

在传统模式下，智能体的循环逻辑和文件操作运行在同一个容器中——就像 Codex 在你的笔记本上运行一样。这里的"容器"指的是基于 Docker 等技术的轻量级虚拟化环境，它将应用程序及其依赖打包在一个隔离的运行时中，确保环境一致性和资源隔离。容器技术已成为现代云原生架构的基石，但其"临时性"特征（容器可能随时被调度系统回收或重启）也给需要持久状态的智能体带来了挑战。

这在本地开发时没问题，但部署到生产环境会带来严重问题：

• 沙盒变成承重结构：容器一旦崩溃或过期，所有状态都会丢失
• 密钥管理困难：沙盒中存放密钥会面临提示注入攻击和数据泄露风险。提示注入（Prompt Injection）是针对大语言模型的一类安全攻击，攻击者通过在输入中嵌入恶意指令，诱导模型执行非预期操作——例如泄露系统提示词中的API密钥或绕过安全限制。当密钥存放在智能体可访问的沙盒中时，这类攻击的危害会被显著放大。
• 状态恢复复杂：需要自行实现快照和重建机制

分离后，沙盒变成了完全临时性的资源，可以随时销毁和重建。Harness 运行在你现有的基础设施上（如 Temporal 任务、AWS 等），负责状态管理、快照和恢复。Temporal 是一个开源的分布式工作流引擎，专门用于编排长时间运行的、需要容错和状态持久化的任务。它通过事件溯源机制自动记录每一步执行状态，即使进程崩溃也能从断点恢复，非常适合作为智能体编排层的底层基础设施。Agents SDK 会自动处理这一切。

Codex 风格的 Harness：开箱即用的核心能力

Agents SDK 引入了 Codex 风格的 Harness，将 Codex 中经过验证的工具和模式带入了通用智能体开发。以下是几项核心能力的详细拆解。

自动压缩（Auto-compaction）

当对话上下文超出窗口限制时，模型能够自动压缩上下文并继续工作。这意味着智能体理论上可以无限期运行——数小时、数天甚至数周，不再受上下文长度的硬性约束。

上下文窗口（Context Window）是大语言模型的核心限制之一，它定义了模型在单次推理中能"看到"的最大文本长度。即使是最先进的模型（如GPT-4o的128K token窗口），在面对持续数天的任务时也会迅速耗尽上下文空间。自动压缩技术通过智能摘要和信息提炼，将早期对话中的关键信息浓缩为更短的表示，从而在有限窗口内保留最大信息量。这类似于人类的"工作记忆"机制——我们不会记住每一句对话的原文，但会保留关键结论和决策依据。

从认知科学角度看，这一机制还与人类的"渐进式遗忘"策略高度相似：心理学研究表明，人类在处理长期任务时会自然地将细节压缩为抽象规则和关键节点，而非逐字保留所有信息。自动压缩技术在工程上模拟了这一过程，其核心挑战在于如何判断哪些信息"值得保留"——这本身就需要对任务目标有深刻理解，也是当前压缩算法设计的难点所在。

异步 Shell 交互

模型可以编写 Shell 命令，等待执行结果。如果命令未完成，它可以先去做其他事情，然后再回来检查。SDK 会跟踪所有正在运行的命令状态，确保不会遗漏任何异步任务。

异步执行模式（Async Execution）是现代并发编程的核心范式。传统的同步模式下，程序必须等待每个操作完成才能继续，这在面对耗时的I/O操作（如编译大型项目、运行测试套件）时会造成大量空闲等待。异步模式允许程序在等待期间切换到其他任务，显著提升整体吞吐量。对于智能体而言，这意味着它可以同时发起多个长时间运行的命令（如并行运行多个测试用例），然后统一收集结果，将原本串行的工作流转化为并行执行，大幅缩短复杂任务的总耗时。

文件系统操作

包括查看图片、使用 apply patch 工具内联编辑文件等能力，让智能体能够像人类开发者一样在代码库中工作。

技能系统（Skills）

技能是一组文件的打包，包含一个 skill.md 主文件和相关脚本资源。Steve 举了一个税务准备技能的例子：包含所有 IRS 规则、文档处理脚本和表格填写逻辑。

技能系统的设计理念借鉴了软件工程中"可复用组件"的思想。在传统智能体开发中，领域知识通常以冗长的系统提示词形式硬编码，难以维护和复用。技能系统将领域知识、操作流程和工具脚本封装为独立的、可版本化的模块，类似于编程中的"库"或"包"。这种模块化设计使得团队可以独立开发、测试和迭代各个技能，然后像乐高积木一样组合到不同的智能体中，大幅提升了开发效率和知识管理的规范性。

从知识工程（Knowledge Engineering）的视角来看，技能系统还解决了一个长期困扰AI应用的"知识孤岛"问题。过去，企业的领域专业知识往往分散在各个团队的提示词模板、内部文档和个人经验中，难以系统化沉淀和共享。技能系统提供了一个标准化的知识封装格式，使得"税务专家的知识"、"合规审查流程"等高价值领域能力可以像软件包一样被发布、订阅和复用，为企业构建知识资产库提供了基础设施。

新增的 Skills API 支持上传、版本管理和默认版本设置。同时，GitHub 也是存储技能的绝佳选择——天然支持版本控制和 PR 审查流程。

沙盒环境：多平台一等支持

Agents SDK 提供了对多个沙盒平台的一等支持，开发者可以根据场景灵活选择：

• Docker：本地开发和测试的首选
• Modal：云端部署的优秀选择
• Cloudflare、E2B、Vercel、Daytona、Bloxel 等第三方平台

切换沙盒后端非常简单，只需更换 Client 和 Options 的定义即可。例如从 Docker 切换到 Modal，只需将 DockerSandboxClient 替换为 ModalSandboxClient。

状态快照与恢复

当任务暂停时，Agents SDK 会自动完成以下步骤：

1. 停止沙盒容器
2. 对文件系统做快照（默认为 tarball）
3. 存储到你指定的位置（本地磁盘、R2、S3 等）

恢复时，SDK 会取回快照、启动新容器、重建文件系统。模型完全不知道自己运行在一个新容器上，实现了无缝恢复。

这里的快照机制借鉴了操作系统和虚拟化领域的成熟实践。Tarball 是 Unix/Linux 系统中将多个文件打包为单一归档文件的标准格式（.tar 或 .tar.gz），它保留了完整的目录结构和文件权限信息。在容器编排场景中，这种"冻结-恢复"模式（类似于笔记本电脑的休眠功能）使得计算资源可以按需分配：智能体不工作时释放昂贵的GPU/CPU资源，需要时在毫秒级重建完整工作环境。这对于成本控制和大规模部署至关重要。

这一机制在经济模型上也具有深远意义。传统的"常驻进程"模式要求为每个智能体持续占用计算资源，即使它90%的时间都在等待用户输入或外部API响应。快照恢复模式将智能体的计费粒度从"运行时长"转变为"实际计算时长"，理论上可以将长时间运行任务的基础设施成本降低一个数量级。这也是为什么 Serverless 计算（如 AWS Lambda、Cloudflare Workers）在智能体基础设施领域越来越受到关注的根本原因。

状态管理包含两部分：文件系统快照和对话消息历史（rollout），两者都以 JSON 格式存储，可以放入任何数据库。

实战演示：构建智能任务追踪器

Steve 通过一个会议策划任务追踪器展示了完整的开发流程，以下是关键步骤。

定义 Sandbox Agent

SandboxAgent 是 Agent 类的子类，保留了所有原有参数，同时新增了沙盒相关配置。定义非常直观：

# 指定沙盒客户端和选项
client = DockerSandboxClient(image="python:3.12")
# 或切换到云端
client = ModalSandboxClient(image="python:3.12")

Manifest：声明式文件系统

Manifest 定义了智能体启动时的文件系统结构。支持多种数据源：

• 本地文件复制
• S3/R2 存储桶挂载
• GitHub 仓库
• Azure Blob Storage

声明式配置（Declarative Configuration）是现代基础设施管理的核心范式，其哲学是"描述你想要什么，而非如何实现"。开发者只需在 Manifest 中声明智能体需要哪些文件和资源，SDK 负责处理获取、挂载和同步的具体细节。这与 Kubernetes 的 Pod Spec、Terraform 的 HCL 配置一脉相承，降低了开发者的认知负担，同时使配置具备可审计、可版本化和可复现的特性。

挂载外部存储特别适合两种场景：海量文件（数百个 PDF）和实时数据（频繁更新的数据源）。挂载方式启动更快但读取有网络延迟，复制方式读取更快但启动较慢。

自定义工具与审批机制

通过 @function_tool 装饰器可以轻松将 Python 函数注册为智能体工具：

工具还支持审批机制——例如将任务标记为"完成"需要人工确认，防止智能体自行关闭任务。这与 Codex 中"是否允许运行此命令"的交互模式一脉相承。

这种"人在回路"（Human-in-the-Loop, HITL）设计模式是当前AI安全领域的重要实践原则。完全自主的智能体在高风险操作（如删除数据、发送外部通信、执行财务操作）上存在不可忽视的风险，即使模型能力再强，也可能因对任务语境的误解而造成不可逆的后果。HITL机制在关键决策节点引入人类判断，构建了一道"最后防线"。随着模型可靠性的提升，这道防线的触发频率会逐渐降低，但其存在本身对于建立用户信任和满足合规要求至关重要。

多智能体协作

演示中展示了两个智能体的协作：程序编辑智能体完成内容优化后，自动将任务转交给资产制作智能体。这通过 Agents SDK 的 handoff 机制实现，为构建复杂工作流提供了清晰的协作范式。

多智能体系统（Multi-Agent System, MAS）是分布式人工智能领域的经典研究方向，其核心思想是通过多个专业化智能体的协作来解决单一智能体难以处理的复杂问题。在工程实践中，这种"分工协作"模式类似于微服务架构——每个智能体专注于特定领域（如代码审查、文档生成、测试验证），通过明确的通信协议（如 handoff）进行任务传递。相比单一"全能"智能体，多智能体架构具备更好的可维护性、可扩展性和容错能力，因为单个智能体的失败不会导致整个系统崩溃。

API 层面的新能力

除了 SDK 更新，Responses API 也新增了几项值得关注的功能。

托管 Shell 工具

在 Responses API 中直接使用轻量级沙盒：上传文件、模型在容器中执行代码、返回结果。支持自动模式（自动创建和销毁容器）和手动模式，适配不同粒度的控制需求。

网络访问控制

可以为容器配置域名白名单，或完全禁止网络出入，从网络层面增强沙盒安全性。

网络访问控制在智能体安全体系中扮演着"纵深防御"的角色。即使智能体遭受提示注入攻击，被诱导尝试向外部服务器泄露数据，严格的网络出口限制也能在最后一道防线上阻断数据外泄。这种"最小权限原则"（Principle of Least Privilege）是信息安全领域的基本准则：系统组件只应拥有完成其任务所必需的最小权限集合。对于处理敏感企业数据的智能体而言，将网络访问限制在已知可信域名的白名单内，是满足SOC 2、ISO 27001等合规要求的重要技术控制措施。

TypeScript 支持

4月发布 Python 版本后，TypeScript 版本现已可用，满足了前端和全栈开发者社区的强烈需求。

选择建议：Agents SDK vs Responses API

根据 Steve 和 Nish 的建议，两者的适用场景有明确区分：

• Agents SDK：适合需要长时间运行、文件操作、多步骤工作流的复杂智能体场景。Codex Harness 与 OpenAI 模型的耦合度越来越高，未来将提供最佳性能。
• Responses API：适合一次性任务（翻译、数据结构化）、使用小众编程语言、或需要轻量级智能循环的场景。

简单来说，如果你的智能体需要"住在"一个环境里持续工作，选 Agents SDK；如果只是"来一趟"完成单次任务，Responses API 更轻便。

总结与展望

Agents SDK 的这次更新标志着智能体开发从"能用"走向"好用"的关键一步。Harness 与 Compute 的分离、开箱即用的状态管理、灵活的沙盒支持和技能系统，大幅降低了生产级智能体的开发门槛。

Nish 还透露，未来几周到几个月内将推出多智能体框架的更多能力，让监督智能体协调数百个专业智能体成为可能。大规模并行工作将成为智能体的默认模式。

这一愿景与当前行业趋势高度吻合。从 Google 的 A2A（Agent-to-Agent）协议到 Microsoft 的 AutoGen 框架，科技巨头们都在押注"智能体编排"将成为下一代计算范式。核心挑战在于：如何在保证可靠性的前提下实现大规模并行？如何设计智能体间的通信协议以避免"幻觉传播"（一个智能体的错误输出被其他智能体当作事实）？如何实现有效的资源调度和成本控制？

其中，"幻觉传播"问题尤其值得深入关注。在多智能体系统中，这是一个被严重低估的风险：当上游智能体产生错误输出（如虚构的API文档、错误的数据统计），下游智能体会将其作为可信事实纳入推理链，进而产生更复杂的错误。这种级联效应在长链路工作流中会被指数级放大。当前的缓解策略包括：在智能体间引入验证节点、使用结构化输出格式降低歧义、以及设计"怀疑性"提示词让智能体主动质疑输入数据的可靠性。这一问题的根本解决仍是当前智能体研究的核心挑战之一，其答案将在很大程度上决定多智能体系统能否真正胜任高风险的企业级任务。

对于开发者而言，现在是开始使用 Agents SDK 的最佳时机——从 Docker 本地开发起步，逐步迁移到云端沙盒，构建真正能长时间自主工作的生产级智能体。

核心要点