The Agents API provides your application with access to the Codex harness via an OpenAI-managed API. OpenAI handles session management, orchestration, context compaction, and recovery, while your application supplies tools and selects its execution environment.
Agents can operate within a sandbox, enabling them to execute code, edit files, connect to MCP servers, and produce artifacts.
Pricing
Model usage is billed according to the selected model's API rates. OpenAI tools use their standard rates, and OpenAI-hosted sandboxes utilize standard container rates.
Try an example
Explore these complete examples:
- Create and run a directory-tree script in an OpenAI-hosted sandbox.
- Compare release notes with subagents and consolidate their findings into a single response.
Explore complete applications:
- Incident response agent: Investigate alerts and request approval for recovery actions.
- Slack bot: Investigate requests using connected workplace tools.
- Data analyst: Answer warehouse questions using read-only SQL.
- GitHub issue investigator: Reproduce reported bugs and share findings on GitHub.
- Document reviewer: Review documents with policy skills and specialist agents.
Core concepts
The Agents API is structured around four primary concepts:
- Agent: The model, instructions, tools, and MCP servers available to the agent.
- Environment: An optional sandbox or computer where the agent accesses files, loads skills, and executes commands.
- Session: A persistent instance of an agent that works on tasks and responds to input.
- Events and items: The inputs sent to an agent and the output produced during a session.
A session from start to finish
Begin with an OpenAI-hosted sandbox in the quickstart:
- Create a session. Configure the agent; OpenAI provisions its environment.
- Assign a task. User input initiates a work turn once the environment is ready.
- Monitor progress. Stream output or use webhooks to be notified when the agent completes its task or requires input.
- Continue or guide. Send another task to the same session or direct the agent during its current turn.
With an OpenAI-hosted session, your application sends input and receives events, while OpenAI manages the agent's execution and its sandbox.
What the managed harness provides
The managed Codex harness supports:
- Executing commands and code within a sandbox.
- Applying relevant skills and instructions.
- Connecting to external data through tools or MCP.
- Steering the agent during its operation.
- Summarizing previous work to manage its context window.
- Decomposing work into subtasks and delegating to subagents.
- Resuming a session from its previous state.
Refer to the quickstart prerequisites for API key permissions and SDK setup. Configure these capabilities when creating a session:
Configure managed-harness capabilities
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": 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." } ] } ] }'
For a runtime comparison, see the Agents overview.
The Agents API preserves session state, allowing you to continue work across turns without rebuilding the conversation context. You can delete sessions and published artifacts when they are no longer needed.
The Agents API currently supports data residency only in the United States and does not offer Zero Data Retention (ZDR). Opting for a self-hosted sandbox does not render the Agents API ZDR-eligible. Consult Data controls in the OpenAI platform for detailed information on data residency and retention.
