OpenAI Agents API:托管型 Codex 会话与沙箱能力

OpenAI Agents API

在使用 OpenAI 托管（hosted）的会话（session）时，你的应用负责发送输入（input）并接收事件（events），而 OpenAI 负责运行 agent、配置并管理其沙箱（sandbox）。关于配置方式和限制，请参阅环境选项。

托管运行框架提供的能力

托管的 Codex 运行框架（harness）支持：

- 在沙箱中运行命令和代码。
- 应用相关的技能（skills）和指令（instructions）。
- 通过工具（tools）或 MCP 接入外部数据。
- 在 agent 工作的过程中对其进行引导（steering）。
- 总结先前的工作以管理其上下文窗口（context window）。
- 将工作拆分为子任务并委派给子 agent（subagent）。
- 从中断处恢复一个会话。

关于 API 密钥权限和 SDK 设置，请查看快速入门的前置条件。下面的示例展示如何在创建会话时配置这些能力。

配置托管运行框架的能力

Python

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"

:},}, 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.",