OpenAI Agents JS v0.10.0 发布：GPT-5.4-mini 成为默认模型，Sandbox Agents 引领沙箱 Agent 新时代

发布时间：2026年5月7日
来源：GitHub @openai/openai-agents-js

前言

2026年5月7日，OpenAI 正式发布了 openai-agents-js v0.10.0 版本，这是该 JavaScript/TypeScript 多智能体框架自 v0.9.0 以来的又一次重大更新。在过去一周内（5月5日~7日），该仓库密集发布了 v0.9.0 → v0.9.1 → v0.10.0 三个版本，节奏史无前例。v0.10.0 更是直接将 SDK 默认模型从 GPT-4.1 切换为 GPT-5.4-mini，并正式确立了 Sandbox Agents（沙箱 Agent）这一 Beta 功能的生态地位。

本文将逐条解读本次更新的核心变化、技术原理、适用场景，以及对 JavaScript/TypeScript 生态中 AI Agent 开发的深远影响。

一、默认模型切换：GPT-5.4-mini 时代来临

1.1 变化内容

在 v0.10.0 之前，openai-agents-js 的默认模型是 GPT-4.1。升级后，SDK 默认模型变更为 gpt-5.4-mini，这意味着所有未显式指定模型的 Agent 和 Run，在不修改任何代码的情况下，将自动使用 GPT-5.4-mini 作为推理模型。

官方说明指出：GPT-5.4-mini 相比 GPT-4.1 在多数使用场景下表现更优，这一结论基于 GitHub PR #1248 中的详细评测报告。

1.2 GPT-5.4-mini 的隐含默认值

由于新默认模型是 GPT-5 系列模型，因此隐式的默认配置也会应用 GPT-5 的标准参数：

这两个隐含参数对 Agent 行为有直接影响：

• reasoning.effort="none" 意味着 Agent 不会使用 GPT-5 的 extended thinking（长思考）能力，响应速度更快，适合工具调用类任务
• verbosity="low" 意味着模型输出更简洁，减少 token 消耗

1.3 如何保持原有行为

如果开发者在升级后发现行为变化不希望发生，有三种方式维持原有默认：

// 方式一：在 Agent 配置中显式指定模型
const agent = new Agent({
  model: "gpt-4.1",  // 显式指定
  instructions: "你是一个助手..."
});

// 方式二：在 RunConfig 中指定模型
const result = await run(agent, userInput, {
  model: "gpt-4.1"
});

// 方式三：通过环境变量覆盖
// .env
OPENAI_DEFAULT_MODEL=gpt-4.1

1.4 技术解读

这一变更的核心驱动力是 GPT-5 系列在成本效益上的显著优势。GPT-5.4-mini 作为 mini 级别模型，在保持较高智能水平的同时，大幅降低了每次 API 调用的成本。对于需要频繁调用 Agent 的生产环境，每月节省的成本可达数十美元至数百美元不等。

此外，reasoning.effort="none" 的默认设定说明 OpenAI 官方判断：大多数 Agents SDK 的典型使用场景（工具调用、多步骤推理）并不需要 GPT-5 的长思考能力，关闭该能力可以显著降低延迟和 token 消耗。

二、maxTurns 配置：turn limit 控制权回归开发者

2.1 变化内容

v0.10.0 新增了 maxTurns=null 配置项，允许开发者完全关闭 Agents SDK 的默认 turn 限制。

此前，SDK 默认 DEFAULT_MAX_TURNS = 10，即默认情况下 Agent 最多与环境交换 10 轮对话即会触发 MaxTurnsError 并终止运行。这对于短任务没有问题，但对于需要长时间运行的复杂任务（如代码重构、文档批量处理），10 轮的硬限制往往过于严格。

2.2 新行为对比

// v0.10.0 之前：默认最多 10 轮，无法关闭
const result = await run(agent, userInput);

// v0.10.0+：显式设置 null 即可解除限制
const result = await run(agent, userInput, {
  maxTurns: null  // 解除轮数上限
});

// 保留原有默认行为（10 轮上限）
const result = await run(agent, userInput, {
  maxTurns: 10  // 显式声明，等同于旧版默认
});

// 自定义上限
const result = await run(agent, userInput, {
  maxTurns: 50
});

2.3 技术解读

maxTurns 本质上控制的是 Agent 与外部环境（用户/Tool 输出）之间的对话轮次，而非 LLM 内部的 token 数量或思维链长度。解除该限制后，Agent 可以进行任意多轮的工具调用和推理，只要 LLM 的 context window 未满即可。

这对以下场景尤为重要：

• 自动化代码重构：需要多轮文件读取→分析→修改循环
• 批量文档处理：Agent 需要对多个文件依次执行操作
• 复杂调试任务：需要反复运行测试→分析结果→修改代码的长循环

三、Tool 执行并发控制：SDK 层面的调度优化

3.1 变化内容

v0.10.0 引入了 SDK 层面的函数工具执行并发配置：

const result = await run(agent, userInput, {
  toolExecution: {
    maxFunctionToolConcurrency: 5  // 最多同时运行 5 个函数工具
  }
});

这是一个纯 SDK 侧的配置，与 Provider（OpenAI API）的 ModelSettings.parallelToolCalls 是两个独立的概念：

3.2 技术解读

Provider 层面的 parallelToolCalls 告诉 LLM：”你可以在一次响应中调用多个工具”，但这不保证这些工具会在同一时刻执行。SDK 收到响应后，仍然可能串行执行这些工具。

SDK 层面的 maxFunctionToolConcurrency 则直接控制：”同一时刻最多有几个函数工具在运行”。这对于以下场景至关重要：

• I/O 密集型工具：如同时发起多个 HTTP 请求，并发执行可大幅提速
• 有状态资源竞争：如同时打开多个文件编辑器可能产生锁竞争，需要限制并发
• 成本控制：限制并发可以避免在复杂任务中无节制地调用工具

四、MCP 工具命名：解决跨服务器名称冲突

4.1 变化内容

新增 MCPConfig.includeServerInToolNames 配置项，当设为 true 时，SDK 会在 MCP 工具名称前加上 MCP 服务器名称作为前缀，避免不同 MCP 服务器上同名工具发生冲突。

import { Agent } from '@openai/agents';

const agent = new Agent({
  name: "我的助手",
  mcpServers: [
    {
      name: "filesystem",
      server: myFilesystemMCP,
      includeServerInToolNames: true
    },
    {
      name: "github",
      server: myGitHubMCP,
      includeServerInToolNames: true
    }
  ]
});

4.2 技术解读

MCP（Model Context Protocol）是 AI Agent 连接外部工具的标准协议。不同的 MCP 服务器可能实现相同名称的工具——例如两个 MCP 服务器都有 read_file 操作。开启 includeServerInToolNames 后，工具名会带上服务器前缀（如 filesystem__read_file 和 github__read_file），LLM 就能准确区分和调用。

该参数与 Python SDK 的 MCPConfig 保持一致，标志着 OpenAI 开始将 JS SDK 与 Python SDK 的 API 对齐，两个语言的 Agent 开发者未来可以更无缝地迁移和参照彼此的代码。

五、Sandbox Agents（Beta）：沙箱 Agent 时代正式开启

以下功能主要在 v0.9.0 中引入，v0.10.0 继续完善，本节做完整解读。

5.1 什么是 Sandbox Agents

Sandbox Agents 是 v0.9.0 正式引入的 Beta 功能，是 openai-agents-js 框架面向”长时任务、持久工作区”场景的核心升级。

传统 Agent 的典型工作流程是：接收输入 → 执行推理 → 调用工具 → 返回结果 → 结束。整个过程是一次性的、无状态的。Sandbox Agents 则在此基础上增加了：

• 持久化工作区（Workspace）：Agent 可以在文件系统中创建、编辑、删除文件
• 沙箱执行环境：隔离的运行环境，支持 Docker、本地进程或云端沙箱
• 跨 Run 会话恢复（Resume）：Agent 可以中断后从上次断点继续工作
• 快照与记忆（Snapshots & Memory）：Agent 可以保存和恢复工作状态
• 内置文件系统/Shell 工具：Agent 可以执行 bash 命令、编辑文件、查看目录

5.2 核心新增组件

5.2.1 SandboxAgent

import { SandboxAgent } from '@openai/agents/sandbox';

const agent = new SandboxAgent({
  name: "代码助手",
  description: "可以读写文件、运行命令的代码助手",
  defaultManifest: { /* ... */ },
  baseInstructions: "你是一个全栈工程师，可以读写项目文件。",
  capabilities: ["filesystem", "shell", "patching"],
});

5.2.2 Manifest

Manifest 是工作区的契约定义，控制 Agent 可以访问哪些文件、目录、Git 仓库等：

const manifest = new Manifest({
  syntheticFiles: ["generated_code/output.txt"],
  localDirs: ["./my-project"],
  gitRepos: ["./my-project/.git"],
  environment: { NODE_ENV: "production" },
  users: "alice",
  groups: ["developers"],
  mounts: [{ host: "./data", container: "/app/data" }]
});

5.2.3 SandboxRunConfig

将沙箱客户端、会话管理、快照配置整合到每次 Run 中：

const result = await run(agent, userInput, {
  sandbox: {
    client: new DockerSandboxClient(),
    snapshotLimit: "100MB",
    timeout: "10m"
  }
});

5.3 支持的沙箱后端

Sandbox Agents 支持多种执行后端，满足不同场景需求：

5.4 Workspace、Snapshots、Resume、Memory

Sandbox Agents 的四大高级功能：

Workspace（工作区）
Agent 在沙箱中有一个持久化的文件系统，可以：

• 创建和编辑任意文件
• 执行 shell 命令（ls、git、npm install 等）
• 生成产物（图片、PDF、代码产物等）

Snapshots（快照）
在任意时刻可以将工作区状态保存为快照：

const snapshot = await sandbox.createSnapshot();
// 返回快照 ID，后续可用于恢复

Resume（恢复）
Agent 可以从快照恢复继续工作：

const resumedResult = await sandbox.resume(snapshotId, {
  instruction: "继续完成上一轮未完成的重构任务"
});

Memory（记忆）
Agent 可以将重要信息写入持久化存储，在后续 Run 中读取：

// 在一个 run 中存储
await sandbox.memory.save("project_context", { lang: "TypeScript", version: "5.0" });

// 在下一个 run 中读取
const context = await sandbox.memory.load("project_context");

六、本周其他重要更新速览

6.1 v0.9.1（5月6日）

6.2 v0.9.0（5月5日）

除 Sandbox Agents 外，还更新了文档翻译流水线，由 GitHub Actions Bot 自动同步多语言文档。

七、升级建议与注意事项

7.1 必须检查的场景

升级到 v0.10.0 前，请确认以下场景是否受影响：

场景一：未显式指定模型的 Agent
如果你的 Agent 没有指定 model，升级后会自动切换到 GPT-5.4-mini。请根据实际表现决定是否需要回退。

场景二：依赖固定轮次上限
如果你的业务逻辑依赖 Agent 最多执行 10 轮，升级后显式设置 maxTurns: 10。

场景三：使用 MCP 服务器
如果你接入了多个 MCP 服务器，请确认是否需要开启 includeServerInToolNames 防止名称冲突。

7.2 升级步骤

# 升级到最新版
npm install @openai/agents@latest

# 或指定版本
npm install @openai/agents@0.10.0

结语

openai-agents-js v0.10.0 是近年来该框架最具里程碑意义的更新之一。默认模型切换到 GPT-5.4-mini 意味着 OpenAI 正式将 Agents SDK 与 GPT-5 系列深度绑定；Sandbox Agents 则补全了 JavaScript/TypeScript 生态中缺少官方沙箱 Agent 能力的空白。

随着 v0.9.0 ~ v0.10.0 的密集发布，OpenAI 正在用实际行动表明：多智能体框架不仅是 Python 端的专属战场，JavaScript/TypeScript 生态同样能得到第一时间的官方支持。对于全栈开发者和前端工程师而言，这意味着可以直接在 Node.js、Deno、Bun 甚至 Cloudflare Workers 中构建生产级 AI Agent 应用。

建议所有正在使用或关注 openai-agents-js 的开发者立即升级，并在生产环境中小规模验证后再全量部署。重点关注默认模型变化对现有 Agent 行为的影响，以及 Sandbox Agents 在自身业务场景中的实际效果。

参考链接

• GitHub 仓库：https://github.com/openai/openai-agents-js
• v0.10.0 Release：https://github.com/openai/openai-agents-js/releases/tag/v0.10.0
• Sandbox Agents 指南：https://openai.github.io/openai-agents-js/guides/sandbox-agents/
• Python SDK：https://github.com/openai/openai-agents-python