Repository Public
1# Agents API23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45The Agents API gives your application access to the Codex harness through an OpenAI-managed API.67OpenAI manages sessions, orchestration, context compaction, and recovery while your application provides tools and chooses its execution environment.89Agents can operate in a sandbox where they can execute code, edit files, connect to MCP servers, and produce artifacts.1011## Pricing1213Model usage is billed at the selected model's [API rates](https://developers.openai.com/api/docs/pricing). OpenAI tools use their [standard rates](https://developers.openai.com/api/docs/pricing#built-in-tools), and OpenAI-hosted sandboxes use standard [container rates](https://developers.openai.com/api/docs/pricing#built-in-tools).1415## Try an example1617Try these complete examples:1819- [Create and run a directory-tree script](https://developers.openai.com/api/docs/guides/agents-api/quickstart#1-run-a-task) in an OpenAI-hosted sandbox.20- [Compare release notes with subagents](https://developers.openai.com/api/docs/guides/agents-api/multi-agent#example-compare-release-notes) and combine their findings into one answer.2122Explore complete applications:2324- [Incident response agent](https://developers.openai.com/cookbook/examples/agents_api/apps/sev_bot/readme): investigate alerts and request approval for recovery actions.25- [Slack bot](https://developers.openai.com/cookbook/examples/agents_api/apps/slack_bot/readme): investigate requests using connected workplace tools.26- [Data analyst](https://developers.openai.com/cookbook/examples/agents_api/apps/data_analyst/readme): answer warehouse questions with read-only SQL.27- Use the [GitHub issue investigator](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/apps/github_issues) to reproduce reported bugs and share findings on GitHub.28- Use the [document reviewer](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/apps/document_review) to review documents with policy skills and specialist agents.2930## Core concepts3132The Agents API is built around four main concepts:3334- **Agent:** The model, instructions, tools, and MCP servers available to the agent.35- **Environment:** An optional sandbox or computer where the agent accesses files, loads skills, and runs commands.36- **Session:** A durable instance of an agent that works on tasks and responds to input.37- **Events and items:** The inputs sent to an agent and the output produced during a session.3839### A session from start to finish4041Start with an OpenAI-hosted sandbox in the [quickstart](https://developers.openai.com/api/docs/guides/agents-api/quickstart):42431. **Create a session.** Configure the agent; OpenAI provisions its environment.442. **Give it a task.** User input starts a turn of work once the environment is ready.453. **Follow progress.** Stream output or use webhooks to learn when the agent finishes or needs input.464. **Continue or steer.** Send another task to the same session, or guide the agent during its current turn.4748With an OpenAI-hosted session, your application sends input and receives events, while OpenAI runs the agent and provisions and manages its sandbox. See [environment options](https://developers.openai.com/api/docs/guides/agents-api/configuration#environment-settings) for setup and limitations.4950<picture>51 <source52 media="(max-width: 640px)"53 srcSet="/images/api/agents-api/overview-1-mobile.webp"54 width="680"55 height="1288"56 />57 <img src="https://developers.openai.com/images/api/agents-api/overview-1.webp"58 width="1400"59 height="552"60 alt="Your application starts sessions and receives events and output from the Agents API. OpenAI runs the managed Codex harness and provisions and manages its sandbox."61 loading="lazy"62 />63</picture>6465## What the managed harness provides6667The managed Codex harness supports:6869- Running commands and code in a sandbox.70- Applying relevant skills and instructions.71- Connecting to external data through tools or MCP.72- Steering the agent while it works.73- Summarizing previous work to manage its context window.74- Breaking work into subtasks and delegating to subagents.75- Resuming a session where it left off.7677Check the [quickstart prerequisites](https://developers.openai.com/api/docs/guides/agents-api/quickstart#prerequisites) for API-key permissions and SDK setup. Configure these capabilities when you create a session:7879Configure managed-harness capabilities8081```javascript82import OpenAI from "openai";8384const client = new OpenAI();8586const session = await client.beta.agents.sessions.create({87 agent: {88 model: "gpt-6-astra",89 instructions:90 "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",91 tools: [92 { type: "programmatic_tool_calling" },93 {94 type: "mcp",95 server_label: "openai_docs",96 transport: {97 type: "http",98 server_url: "https://developers.openai.com/mcp",99 },100 },101 { type: "web_search" },102 ],103 multi_agent: { enabled: true, max_concurrent_subagents: 4 },104 },105 environment: {106 type: "self_hosted",107 workspace_directory: "/workspace",108 capability_directories: ["/workspace/capabilities/skills"],109 },110 input: [111 {112 role: "user",113 content: [114 {115 type: "input_text",116 text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",117 },118 ],119 },120 ],121});122console.log(session.id);123```124125```python126from openai import OpenAI127128client = OpenAI()129130session = client.beta.agents.sessions.create(131 agent={132 "model": "gpt-6-astra",133 "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",134 "tools": [135 {"type": "programmatic_tool_calling"},136 {137 "type": "mcp",138 "server_label": "openai_docs",139 "transport": {140 "type": "http",141 "server_url": "https://developers.openai.com/mcp",142 },143 },144 {"type": "web_search"},145 ],146 "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},147 },148 environment={149 "type": "self_hosted",150 "workspace_directory": "/workspace",151 "capability_directories": ["/workspace/capabilities/skills"],152 },153 input=[154 {155 "role": "user",156 "content": [157 {158 "type": "input_text",159 "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",160 }161 ],162 }163 ],164)165print(session.id)166```167168```go169import (170 "context"171 "fmt"172 "github.com/openai/openai-go/v3"173)174175ctx := context.Background()176client := openai.NewClient()177session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra"),178 Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),179 Tools: []openai.AgentToolParamUnion{openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},180 openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs",181 Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},182 openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}}},183 MultiAgent: openai.MultiAgentConfigParam{Enabled: true,184 MaxConcurrentSubagents: openai.Int(4)}},185 Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace",186 CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},187 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."}}}}}}})188if err != nil {189 panic(err)190}191fmt.Println(session.ID)192```193194```java195import com.openai.client.OpenAIClient;196import com.openai.client.okhttp.OpenAIOkHttpClient;197import com.openai.models.beta.agents.AgentToolParam;198import com.openai.models.beta.agents.EnvironmentParam;199import com.openai.models.beta.agents.McpTransportParam;200import com.openai.models.beta.agents.MultiAgentConfigParam;201import com.openai.models.beta.agents.sessions.SessionCreateParams;202import java.util.List;203204OpenAIClient client = OpenAIOkHttpClient.fromEnv();205var session =206 client207 .beta()208 .agents()209 .sessions()210 .create(211 SessionCreateParams.builder()212 .agent(213 SessionCreateParams.Agent.builder()214 .model("gpt-6-astra")215 .instructions(216 "Use the OpenAI documentation MCP and web search to answer"217 + " technical questions accurately. Delegate independent"218 + " research tasks to subagents when useful.")219 .addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())220 .addTool(221 AgentToolParam.Mcp.builder()222 .serverLabel("openai_docs")223 .transport(224 McpTransportParam.Http.builder()225 .serverUrl("https://developers.openai.com/mcp")226 .build())227 .build())228 .addTool(AgentToolParam.WebSearch.builder().build())229 .multiAgent(230 MultiAgentConfigParam.builder()231 .enabled(true)232 .maxConcurrentSubagents(4L)233 .build())234 .build())235 .environment(236 EnvironmentParam.SelfHosted.builder()237 .workspaceDirectory("/workspace")238 .capabilityDirectories(List.of("/workspace/capabilities/skills"))239 .build())240 .input(241 "Research how to connect an MCP server to an OpenAI agent, check for recent"242 + " updates, and summarize the recommended setup.")243 .build());244System.out.println(session.id());245```246247```ruby248require "openai"249250client = OpenAI::Client.new251252session = client.beta.agents.sessions.create(253 agent: {254 model: "gpt-6-astra",255 instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",256 tools: [257 { type: "programmatic_tool_calling" },258 {259 type: "mcp",260 server_label: "openai_docs",261 transport: {262 type: "http",263 server_url: "https://developers.openai.com/mcp"264 }265 },266 { type: "web_search" }267 ],268 multi_agent: {269 enabled: true,270 max_concurrent_subagents: 4271 }272 },273 environment: {274 type: "self_hosted",275 workspace_directory: "/workspace",276 capability_directories: ["/workspace/capabilities/skills"]277 },278 input: [279 {280 role: "user",281 content: [282 {283 type: "input_text",284 text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."285 }286 ]287 }288 ]289)290puts session.id291```292293```bash294curl -sS -X POST "https://api.openai.com/v1/agents/sessions" \295 -H "OpenAI-Beta: agents=v1" \296 -H "Authorization: Bearer $OPENAI_API_KEY" \297 -H "Content-Type: application/json" \298 -d '{299 "agent": {300 "model": "gpt-6-astra",301 "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",302 "tools": [303 {304 "type": "programmatic_tool_calling"305 },306 {307 "type": "mcp",308 "server_label": "openai_docs",309 "transport": {310 "type": "http",311 "server_url": "https://developers.openai.com/mcp"312 }313 },314 {315 "type": "web_search"316 }317 ],318 "multi_agent": {319 "enabled": true,320 "max_concurrent_subagents": 4321 }322 },323 "environment": {324 "type": "self_hosted",325 "workspace_directory": "/workspace",326 "capability_directories": ["/workspace/capabilities/skills"]327 },328 "input": [329 {330 "role": "user",331 "content": [332 {333 "type": "input_text",334 "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."335 }336 ]337 }338 ]339 }'340```341342343344345346For a runtime comparison, see the [Agents overview](https://developers.openai.com/api/docs/guides/agents#compare-agent-runtimes).347348The Agents API retains session state so you can continue work across turns without349 rebuilding the conversation context. You can delete sessions and published350 artifacts when you no longer need them.351 The Agents API currently supports data residency only in the United States and352 does not support Zero Data Retention (ZDR). Choosing a self-hosted sandbox does353 not make the Agents API ZDR-eligible. See [Data controls354 in the OpenAI platform](https://developers.openai.com/api/docs/guides/your-data#storage-requirements-and-retention-controls-per-endpoint)355 for details on data residency and retention.