OpenAI Agents API正式发布

Agents API 让你的应用可以通过 OpenAI 托管的 API 访问 Codex 运行沙箱。

OpenAI 负责管理会话、编排、上下文压缩和恢复，而你的应用则提供工具并选择执行环境。

Agent 可以在一个沙箱中运行，在其中执行代码、编辑文件、连接到 MCP 服务器，并生成产物。

模型使用按所选模型的 API 费率计费。OpenAI 工具使用标准费率，OpenAI 托管的沙箱使用标准容器费率。

尝试以下完整示例：

在 OpenAI 托管的沙箱中创建并运行一个目录树脚本。

使用 subagent 比较发布说明，并将它们的发现合并为一个答案。

探索完整应用：

事件响应 Agent：调查警报并请求恢复操作的审批。

Slack Bot：使用已连接的企业工具调查请求。

数据分析师：用只读 SQL 回答数据仓库问题。

GitHub Issue 调查器：复现报告的 Bug 并在 GitHub 上分享发现。

文档审查员：使用策略技能和专家 Agent 审查文档。

Agents API 围绕四个核心概念构建：

Agent：提供给 Agent 使用的模型、指令、工具和 MCP 服务器。

Environment：一个可选的沙箱或计算机，Agent 在其中访问文件、加载技能和运行命令。

Session：一个持久的 Agent 实例，负责处理任务并响应输入。

Events 和 items：发送到 Agent 的输入以及会话期间产生的输出。

一个会话从开始到结束

从快速入门中的 OpenAI 托管沙箱开始：

创建一个会话。配置 Agent；OpenAI 为其配置环境。

分配任务。用户输入在环境就绪后开始一轮工作。

跟踪进度。流式传输输出或使用 Webhook 来了解 Agent 何时完成或需要输入。

继续或引导。向同一会话发送另一个任务，或在当前轮次中引导 Agent。

使用 OpenAI 托管会话时，你的应用发送输入并接收事件，而 OpenAI 运行 Agent 并配置和管理其沙箱。有关设置和限制，请参阅环境选项。

托管运行沙箱提供的功能

托管的 Codex 运行沙箱支持：

在沙箱中运行命令和代码。

应用相关的技能和指令。

通过工具或 MCP 连接到外部数据。

在 Agent 工作时引导它。

总结之前的工作以管理其上下文窗口。

将工作分解为子任务并委托给 subagent。

从上次中断的地方恢复会话。

有关 API 密钥权限和 SDK 设置，请查看快速入门前提条件。在创建会话时配置以下功能：

import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp",
        },
      },
      { type: "web_search" },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 4 },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
        },
      ],
    },
  ],
});
console.log(session.id);

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {
                    "type": "http",
                    "server_url": "https://developers.openai.com/mcp",
                },
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
                }
            ],
        }
    ],
)
print(session.id)

import (
	"context"
	"fmt"
	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra"),
	Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
	Tools: []openai.AgentToolParamUnion{openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
		openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs",
			Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},
		openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}}},
	MultiAgent: openai.MultiAgentConfigParam{Enabled: true,
		MaxConcurrentSubagents: openai.Int(4)}},
	Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace",
		CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},
	Input: openai.BetaAgentSessionNewParamsInputUnion{OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{openai.AgentSessionInputMessageParam{Content: []openai.InputContentParamUnion{openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}}}}}}})
if err != nil {
	panic(err)
}
fmt.Println(session.ID)

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "Use the OpenAI documentation MCP and web search to answer"
                                + " technical questions accurately. Delegate independent"
                                + " research tasks to subagents when useful.")
                        .addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
                        .addTool(
                            AgentToolParam.Mcp.builder()
                                .serverLabel("openai_docs")
                                .transport(
                                    McpTransportParam.Http.builder()
                                        .serverUrl("https://developers.openai.com/mcp")
                                        .build())
                                .build())
                        .addTool(AgentToolParam.WebSearch.builder().build())
                        .multiAgent(
                            MultiAgentConfigParam.builder()
                                .enabled(true)
                                .maxConcurrentSubagents(4L)
                                .build())
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/capabilities/skills"))
                        .build())
                .input(
                    "Research how to connect an MCP server to an OpenAI agent, check for recent"
                        + " updates, and summarize the recommended setup.")
                .build());
System.out.println(session.id());

require "openai"

client = OpenAI::Client.new

session = client.beta.agents.sessions.create(agent: {model: "gpt-6-astra",
                                                     instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
                                                     tools: [{type: "programmatic_tool_calling"},
                                                       {type: "mcp",
                                                        server_label: "openai_docs",
                                                        transport: {type: "http",
                                                                    server_url: "https://developers.openai.com/mcp"}},
                                                       {type: "web_search"}],
                                                     multi_agent: {enabled: true,
                                                                   max_concurrent_subagents: 4}},
  environment: {type: "self_hosted",
                workspace_directory: "/workspace",
                capability_directories: ["/workspace/capabilities/skills"]},
  input: [{role: "user",
           content: [{type: "input_text",
                      text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}]}])
puts session.id

curl -sS -X POST "https://api.openai.com/v1/agents/sessions" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
      "tools": [
        {
          "type": "programmatic_tool_calling"
        },
        {
          "type": "mcp",
          "server_label": "openai_docs",
          "transport": {
            "type": "http",
            "server_url": "https://developers.openai.com/mcp"
          }
        },
        {
          "type": "web_search"
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 4
      }
    },
    "environment": {
      "type": "self_hosted",
      "workspace_directory": "/workspace",
      "capability_directories": ["/workspace/capabilities/skills"]
    },
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
          }
        ]
      }
    ]
  }'

有关运行时比较，请参阅 Agents 概览。

Agents API 保留会话状态，因此你可以在多轮对话中继续工作，而无需重建对话上下文。不再需要时，可以删除会话和已发布的产物。Agents API 当前仅支持美国的数据驻留，不支持零数据保留（ZDR）。选择自托管沙箱并不会使 Agents API 获得 ZDR 资格。有关数据驻留和保留的详细信息，请参阅 OpenAI 平台中的数据控制。