目录

OpenAI Agents API 与可插拔沙箱实战

要把一个编码或运维类 Agent 真正放进生产环境,团队往往得自己重造一整套运行时:持久化会话状态、长任务上下文压缩、断线恢复、命令执行隔离、网络出口管控以及产物收集。OpenAI 在 2026 年 9 月 10 日开放公测的 OpenAI Agents API(Beta Header 为 OpenAI-Beta: agents=v1)直接把自家的 Codex Harness 托管成云端运行时接口;随后在 11 月 18–19 日,OpenAI 又陆续公开了 Inside the Codex Sandbox 的跨平台内核隔离实现,以及内部用 Codex 驱动性能回归排查的 Performance Factory 架构。

如果说 Codex 最佳实践 讲的是工程师如何在本地 CLI、IDE 与桌面端把 Codex 用顺手,本文则聚焦服务端与生产系统视角:如何把 Agents API 当作可编程运行时接入业务后台,如何在托管容器与自托管 codex exec-server 之间准确评估网络与数据驻留边界,以及如何借鉴 Performance Factory 的验证闭环把长周期自动化任务做稳。本文基于截至 2026 年 11 月的官方文档与工程披露整理。

Agents API 的核心抽象:Session、Turn 与托管 Harness

传统无状态对话接口把循环控制权全部留在调用方手里:每一步工具调用、重试、上下文裁剪和状态落盘都要业务代码自己维护。Agents API 把这套编排循环下沉为平台托管的 Session(会话) 抽象:

flowchart LR App["业务后台 / CI 触发器"] -->|"POST /v1/agents/sessions (agents=v1)"| Harness["OpenAI 托管 Codex Harness"] Harness -->|"上下文自动压缩 & 云端状态持久化"| Session["Durable Session"] Harness -->|"下发命令"| Env["可插拔执行环境"] Env -->|"回传执行结果"| Harness Env --> Hosted["OpenAI 托管 Linux 容器"] Env --> SelfHosted["自托管 codex exec-server (出站 WebSocket)"] Env --> Partner["第三方沙箱 (E2B / Modal / Daytona)"] Harness -->|"SSE 事件流 / Webhook"| App

业务后台只负责派发目标、配置权限边界和消费事件流,编排循环与状态恢复交给 Harness,命令与文件副作用收敛在执行环境里。需要特别留意图中的回传链路:即便使用自托管执行器,命令输出与工具结果依然会回传给 OpenAI 云端 Session 参与后续推理与状态持久化。

在实际接入时,有四个运行时机制直接决定生产稳定性:

  • 持久化 Session 与文件寿命:每个 Session 保存 Agent 配置、历史轨迹与云端状态,可按 session_id 跨多轮续接。但需要注意,OpenAI 托管沙箱 中的工作区文件(live files)仅在沙箱存活期间保留,需要长期留存或交付给下游系统的结果必须显式发布为 Artifact。
  • Turn 与运行中纠偏(Steering):向空闲 Session 发送输入会开启一个新 Turn;向正在执行的 Turn 发送新输入,则会把纠偏指令注入当前循环,适合人工介入或监控告警触发中途转向。
  • 默认后台上下文压缩:长任务在多轮命令输出后容易触及上下文上限或产生注意力稀释(原理可参考 AI 上下文工程指南)。Agents API 在 Harness 层默认开启后台上下文压缩,折叠早期冗余日志并保留关键决策摘要。
  • 断流不等于取消任务:前台可通过 SSE 流实时消费事件,异步作业可配置 Webhook。断开客户端 SSE 连接只会停止本地接收,并不会自动取消服务端正在运行的 Turn;如需终止必须显式调用取消接口,重新连接则可按 session_id 恢复订阅。

执行环境选型与数据驻留边界

Agents API 通过必填字段 environment 将推理编排与执行环境解耦(见 Create Session API Reference)。选错环境形态,要么引入不必要的容器开销,要么误判合规与数据边界。

环境模式 请求体配置 核心特点 适用场景与真实边界
无执行环境 environment: { type: "none" } 显式声明不需要工作区,零容器开销 纯文本推理、结构化抽取,或仅调用外部 HTTP / MCP 工具
OpenAI 托管沙箱 environment: { type: "openai_hosted" } 托管 Linux 容器(预装 Node.js / Python),支持规格配置、预置文件、环境变量与初始化脚本 通用代码生成、数据处理、自动修单测;无法直连企业私有 VPC 内网
预热沙箱(Pre-warmed) 先独立创建并执行 setup,再通过 environment_id 挂载到 Session 消除依赖安装与代码拉取的冷启动耗时 高频触发的在线任务、大仓库依赖缓存场景
自托管 / 合作方沙箱 私有 VPC 内运行 codex exec-server,或接入 E2B / Modal / Daytona 命令执行、内部包源与私有镜像留在自有网络内 访问内网测试库、私有依赖源、自定义构建工具链

合规与安全边界必须先说清楚,不能把自托管执行器误解成「数据不出域」:

  1. 当前驻留与保留限制:根据 Agents API Overview,当前公测阶段仅支持美国数据驻留(US data residency),且不支持零数据保留(ZDR)——即便采用 自托管执行器,codex exec-server 仍通过出站 WebSocket 连回 OpenAI 交换命令与执行结果,受限于同一套云端驻留与保留规则。
  2. 网络层与权限层各司其职:在私有子网部署 codex exec-server 时,子网防火墙只能收紧「允许访问哪些内部主机和端口」;至于数据库是否只读、能操作哪些表,必须由数据库最小权限角色、受控工具接口或短期签发凭证在应用/数据层强制执行。

Inside the Codex Sandbox:OS 级内核隔离

容器并非总能替代本机隔离:在开发机或构建节点上,套一层 Docker 往往会破坏原生工具链(例如 macOS/iOS 模拟器或宿主机 SDK)。OpenAI 在 2026 年 11 月 18 日的 Inside the Codex Sandbox 中披露了跨三大操作系统的内核级沙箱实现:

  • macOS:基于 Apple Seatbelt 在系统调用层限制文件写入路径与网络访问。
  • Linux:使用 Bubblewrap 构造隔离的文件系统视图,并结合 seccomp-bpf 过滤器收窄允许调用的系统调用,无需特权 root 容器即可约束进程行为。
  • Windows:现行架构组合使用受限用户 Token、安全标识符(SID)、显式 ACL 与独立隔离账号(CodexSandboxOffline / CodexSandboxOnline),同时在兼容设备上逐步向 MXC 隔离后端迁移。

上层配置抽象为三档权限(详见 Codex Config Reference):

  1. Read-Only(只读模式):允许代码检索与只读诊断命令,禁止写入工作区,适合故障初筛与审计。
  2. Workspace-Write(工作区可写):允许写入当前工作目录、临时目录以及显式配置的额外可写根目录(extra writable roots)。需要特别注意:禁止写入并不等于禁止读取——读取规则独立管控,因此宿主机上的敏感密钥仍需通过读取隔离或独立运行环境保护,不能仅靠开启 workspace-write 就以为密钥绝对安全。
  3. Danger-Full-Access(完全访问):关闭沙箱写保护,仅限已由外层一次性容器或独立 CI Runner 兜底的隔离环境,禁止作为开发机默认档位。

这与 AI Agent 环境工程 的原则一致:安全边界必须由操作系统或容器机制物理执行,而不是靠提示词约束。

TypeScript 接入与多轮续接示例

公测阶段调用 REST 接口应请求 POST https://api.openai.com/v1/agents/sessions(注意 URL 中不含 /beta;SDK 里的 beta 只是客户端命名空间),并携带请求头 OpenAI-Beta: agents=v1。下面示例展示如何创建带托管沙箱的 Session、解析响应里的 session_id 并执行一次后续 Turn 续接(具体流式事件与官方 SDK Result Collection 用法可对照 Agents API Quickstart):

type EnvironmentConfig =
  | { type: "none" }
  | { type: "openai_hosted" }
  | { type: "environment_id"; environment_id: string };

interface CreateSessionPayload {
  agent: {
    model: string;
    instructions: string;
  };
  environment: EnvironmentConfig;
  input: string;
  stream: boolean;
}

const SESSIONS_URL = "https://api.openai.com/v1/agents/sessions";

function buildHeaders(): Record<string, string> {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    throw new Error("Missing OPENAI_API_KEY");
  }
  return {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "OpenAI-Beta": "agents=v1",
  };
}

export async function createAndContinueSession(
  initialPrompt: string,
  followUpPrompt: string,
): Promise<{ sessionId: string; followUpStatus: number }> {
  const payload: CreateSessionPayload = {
    agent: {
      model: "gpt-6-astra",
      instructions:
        "Inspect the workspace, run verification commands, and report actual command output.",
    },
    environment: { type: "openai_hosted" },
    input: initialPrompt,
    stream: false,
  };

  const createRes = await fetch(SESSIONS_URL, {
    method: "POST",
    headers: buildHeaders(),
    body: JSON.stringify(payload),
  });
  if (!createRes.ok) {
    throw new Error(`Create session failed: ${createRes.status} ${await createRes.text()}`);
  }

  const created = (await createRes.json()) as { id?: string };
  if (!created.id) {
    throw new Error("Agents API response missing session id");
  }

  // 在同一持久化 Session 上发起后续 Turn(纯流式接入时建议直接使用官方 SDK 的 result collection)
  const followUpRes = await fetch(`${SESSIONS_URL}/${created.id}/turns`, {
    method: "POST",
    headers: buildHeaders(),
    body: JSON.stringify({ input: followUpPrompt, stream: false }),
  });

  return { sessionId: created.id, followUpStatus: followUpRes.status };
}

生产落地时建议补齐三项护栏:一是在网关层给单次 Session 设定墙钟超时与 Token 预算上限;二是把 session_id 与内部工单 ID 绑定落库,区分「客户端断流重连」与「显式取消 Turn」;三是把 Beta 字段封装在独立 Adapter 内,隔离公测阶段的 Schema 变动。

从 Performance Factory 学什么:验证闭环

2026 年 11 月 19 日,OpenAI 在 How OpenAI’s Performance Factory keeps ChatGPT fast 中披露了内部性能回归自动化系统。官方数据显示,在三个多月内该系统累计跟踪了 超过 1,700 次自动调查,在 超过 600 个案例中定位到根因;另据 OpenAI 性能团队在 VentureBeat 专访 中补充的口径,约 400 个案例进入修复提案阶段,其中约 50 个上线修复受系统建议影响,约 15 个 PR 由 Codex 原样合入生产。

相比通用多 Agent 角色划分(已见 多智能体系统实战指南),Performance Factory 最值得借鉴的是把对抗校验前移到诊断阶段,并把验证延伸到上线之后:

flowchart LR Alert["延迟告警 / 回归信号"] --> Triage["调查阶段 (本文建议: Read-Only)"] Triage --> Challenge["根因反证复核"] Challenge -->|"证据不足"| Triage Challenge -->|"根因成立"| Fixer["修复提案 (本文建议: Workspace-Write)"] Fixer --> Critic["补丁对抗复核"] Critic -->|"回退 / 证据不足"| Fixer Critic -->|"通过"| SRE["人类 SRE 终审合并"] SRE --> PostCheck["上线后指标回测"]

这一闭环卡住了两个最容易翻车的点:一是先反证根因再写补丁,避免 Agent 在错误归因上写出看似通过单测的无效优化;二是上线后持续回测,把「合入 PR」之后的真实延迟变化重新接回验证闭环,而人类 SRE 始终掌握最终发布权。

适用边界与避坑清单

  • 无状态简单任务不该上 Session:单步分类、摘要或简单抽取直接走常规无状态接口延迟更低、成本更可控;若必须接入 Agents API 做纯文本任务,请显式传 environment: { type: "none" }。
  • 不要把沙箱目录当持久存储:容器销毁后工作区文件即失效,关键产物必须发布为 Artifact 或同步回自有存储。
  • 凭证留在网关与短期令牌里:对外部数据库、支付或部署系统的访问,优先通过最小权限工具或短期签发令牌暴露,避免把长效高权密钥直接塞进沙箱环境变量。

参考资料