OpenAI Agents API
TL;DR Highlight
OpenAI launched a managed agents API handling sessions, context compaction, and recovery.
Who Should Read
Backend developers who find building and operating their own agent harness too burdensome
Core Mechanics
- Codex harness offered as an API
- The Agents API exposes an OpenAI-managed Codex harness (the agent runtime) through an API.
- OpenAI handles sessions, orchestration, context compaction, and recovery.
- Your app provides tools and picks the execution environment.
- Four core concepts
- An Agent bundles the model, instructions, tools, and MCP servers.
- An Environment is an optional sandbox or computer for files, skills, and commands.
- A Session is a durable agent instance that keeps working on tasks.
- Events and items are the inputs and outputs.
- What the harness gives you out of the box
- It runs commands and code in a sandbox.
- It supports skills, external data via MCP, and steering mid-turn.
- It summarizes prior work for context, delegates to subagents, and resumes sessions.
- Session flow: create, task, follow, continue
Community Reactions
- Self-hosted sandbox seen as a plus
- One comment noted you can self-host the sandbox, which could ease switching providers.
- Other comments raised heavy lock-in concerns.
- Remote agent seen as backwards
- A commenter said the hard part is giving agents access to local data, and a remote agent reaching into your infra makes it worse.
- They would rather run the agent locally with remote hosted sandboxes.
- Data retention flagged as unclear
- A commenter pointed out a note saying it isn't eligible for Zero Data Retention.
- They worried the don't-train toggle covers only user-visible inputs and outputs, not reasoning traces.
- Mixed build-vs-buy experience
- One commenter built sandbox and Slack integrations with the OpenAI agents SDK and kept strict control over what was exposed.
- Another argued teams can't keep pace with API changes, so they end up on hosted abstractions.
- A commenter said the example GitHub links first 404ed, then were fixed to openai-cookbook.
How to Apply
- Run the docs-MCP session example
- Run the session-creation code below with your API key and print session.id.
- Replace the question with one from your own service.
- Compare responsibilities with your own harness
- List which of session storage, context compaction, and recovery you built yourself.
- Mark which overlap with the Agents API built-ins.
- Check data retention terms first
- If customer data will flow in, verify the Zero Data Retention ineligibility note before adopting.
- Use the self-hosted sandbox option and keep access minimal.
- Try one parallel subagent task
- Pick an independent research task and enable multi_agent.
- Set max_concurrent_subagents to 4 and check that results merge into one answer.
Try It
# Run in a terminal (pip install openai; needs an OpenAI API key and Agents API beta access)
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": "{{question}}"}]}],
)
print(session.id)
# Next: change the question, turn multi_agent off, and compare results.Terminology
Related Papers
Same Simulation, Different Evidence: Where Retrieved Tool Output Costs LLM Agents Accuracy
Saving long tool output to files cut GPT-5.1 accuracy by 11.3 points; naming the authoritative file restored it.
Fake News, Real Crashes: Information Injection Attacks on LLM Financial Trading Agents
Fake headlines hijacked LLM trading agents 62% of the time versus 14% for prompt injection.
Harness Engineering 101: The LLM is the brain, the harness is the body
An agent is a loop managing a JSON array; 16 chapters build one from scratch
Harness2 by Google Research – Recursive Agent Harnessing
Recursively refining the harness with fixed model weights raised benchmark scores by up to 11.8 points.
Ousted Savannah police officer gave ICE agent husband access to Flock system
A police officer shared her Flock login with her ICE-agent husband; an audit found 983 searches and she was fired
Tmux and Claude Code: Sessions, Send-Keys, and the Ceiling
Running Claude Code agents in tmux works well, but limits appear around four agents.