OpenAI Agents API Public Beta: Session Code, Environments and Tool Controls

OpenAI’s Agents API is a public beta for running cloud agents with the Codex harness. The launch page shows a JavaScript session call that names an agent model, tools, vaults, an execution environment and input. It also describes OpenAI-hosted sandboxes, customer infrastructure and partner environments, with automatic compaction, tool search, programmatic tool calls and multi-agent support.

The published JavaScript shape

This is the request shape OpenAI shows in its announcement. It is source-checked but unexecuted here; replace the placeholder vault and MCP values with resources that your project is authorised to use.

import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{
      type: "mcp",
      server_label: "observability",
      transport: {
        type: "http",
        server_url: "https://observability.example.com/mcp"
      }
    }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 }
  },
  vault_ids: ["vault_YOUR_VAULT_ID"],
  environment: {
    type: "openai_hosted",
    capability_directories: ["/workspace/capabilities/skills"]
  },
  input: "Investigate the weekly campaign anomaly and save evidence."
});

Test status: this code mirrors the official launch example and was not executed. The article does not invent a returned session schema or claim that the placeholder MCP server exists.

Choose the environment before choosing tools

OpenAI says the agent can run in an OpenAI-managed sandbox, on a team’s own infrastructure or through partner environments. That decision controls files, secrets, network access, compute, cold starts, cost and who can inspect artifacts. Write the environment decision before adding a tool.

• OpenAI hosted: fast start, managed sandbox and configurable files/packages/skills/plugins.
• Your infrastructure or VPC: more control over data and network boundaries, with your own operational burden.
• Partner sandbox: a provider-specific compute, storage and secret model that needs its own review.

Tool controls that matter

The announcement names MCP, custom functions, web search, tool search and programmatic tool calls. Tool search can load relevant definitions when needed; programmatic calls can run and filter work in code. These features reduce context overhead but increase the importance of an allowlist.

1. Begin with read-only tools and a disposable environment.
2. Pin the MCP server URL, authentication method, allowed functions and data classes.
3. Store tool inputs and outputs with the task trace.
4. Require approval for email, Slack, deployment, campaign, CRM or file-write actions.
5. Test what happens when a tool is unavailable, returns partial data or asks for a secret.

Compaction and subagents are not quality guarantees

OpenAI says the harness automatically compacts earlier context as a session approaches its limit and can delegate to up to three concurrent subagents. Make the acceptance criteria, source list and final output path explicit so a compacted session can be checked. A subagent result is evidence to review, not an approval to publish or change a production system.

Pricing and beta boundary

OpenAI says there is no additional Agents API fee; developers pay for the tokens and tools their agents use. That is not a fixed cost per task. Estimate model tokens, tool calls, environment time and human review from a representative run. The product is public beta, so pin versions where possible and keep a fallback path.

Write the preflight contract before adding tools

Test the beta with a bounded task

1. Use a read-only repository or disposable workspace and a question with a known answer.
2. Start with one tool. Save the request, tool definition, inputs, outputs and environment type.
3. Enable compaction or delegation only after the single-agent trace is understandable. Compare the final result with the same acceptance criteria.
4. Remove secrets and customer data from the first run. Add a write-capable tool only after the reviewer can explain the tool trace.
5. Estimate tokens, tool calls, environment time and human review from a representative run; the announcement does not establish a fixed per-task price.

Failure modes that change the decision

• Wrong environment: a hosted sandbox may not have the private network or secret boundary expected by the task. Stop before adding a credential.
• Unpinned MCP endpoint: a server or function can change outside the agent prompt. Pin the URL, auth method and allowed operations.
• Compaction loss: a compacted session may omit an early constraint. Repeat the acceptance criteria in the final task and inspect the trace.
• Subagent drift: three parallel subagents can return inconsistent evidence. Define the handoff schema and require a final reviewer to reconcile it.
• Beta dependency: the public-beta surface can change. Keep a fallback script or manual path and record the package/model version used.

DMT’s agent-harness guide owns context, state and evaluation controls. Its scheduled-work governance guide covers permissions and monitoring for recurring work. Use those pages for adjacent controls; this article owns the public-beta session API and environment/tool choice.

FAQ: questions readers ask

Does the Agents API run only in OpenAI’s sandbox?

No. OpenAI describes OpenAI-hosted, customer-infrastructure and partner environments. The environment choice changes the operational and data boundary.

How many subagents can the example use?

OpenAI’s announcement shows multi-agent support with a maximum of three concurrent subagents in the documented example.

Is there an extra Agents API fee?

OpenAI says there is no additional Agents API fee, but model tokens, tools, environment usage and human review still contribute to the task cost.

Source note: Endpoint shape, model/tools/environment fields, hosted options, compaction, tool search, MCP/functions/web search, three-subagent example and pricing statement come from OpenAI’s September 10 announcement. Code is illustrative and unexecuted.

Sources: OpenAI Agents API announcement