From the Codex Harness to Cloud Agents: Using the Agents API

In the Codex architecture post, I mapped the runtime around the model: the loop, tools, permissions, context, and conversation state. OpenAI’s Agents API announcement, published on September 10, 2026, makes that architecture available through a managed service.

The connection is direct: the Agents API runs a Codex harness for your application. OpenAI operates that runtime; you supply the task and integrations, and choose where code executes. This post follows that boundary from an API request to a repository in your own environment, then revisits the Astra planner and Sol implementer example from the original guide. Agents API overview

Where the existing architecture fits

There are two deployment choices worth keeping separate. You can operate Codex yourself and integrate through its CLI, SDK, or App Server. Alternatively, you can use the Agents API and let OpenAI operate the harness. The public repository explains the foundation, but it does not establish that the hosted service runs the exact commit inspected in the earlier article.

Our source snapshot already contains the executor machinery for remote environments. Its codex-exec-server crate handles process and filesystem operations and documents remote registration and relay requirements. That supports the architectural connection; compatibility with a live hosted service still depends on the installed executor and service. Pinned executor source

The architecture documentation separates the application server, harness, and environment. The application submits work, consumes events, and handles custom function tools. The environment supplies compute and files when a task needs them.

codex app-server and codex exec-server have different jobs. App Server exposes Codex conversation and application operations. The execution server supplies process and filesystem capabilities to a harness. The Agents API uses its own HTTP resources and event types, so the previous guide’s App Server messages should be mapped to the new interface deliberately. App Server documentation

Choose where the agent works

These are execution choices. OpenAI operates the harness in all three. Remote MCP tools can be called from the service; application-defined functions need your application to run the function and return its result. Architecture

For the hosted option, packages and supplied files are prepared before setup commands. A setup failure prevents the agent from starting. Environment templates reuse configuration; they do not preserve a live workspace. OpenAI-hosted sandboxes

Connect a repository through the executor

Consider the illustrative CSV export bug from the original guide: a name containing a comma causes incorrect columns. Assume an application has prepared an isolated checkout at /workspace, installed its test dependencies, and obtained a bounded implementation brief. The example paths below stand in for that application’s repository.

First, create the session from your backend. The documented prerequisites are an application key with api.agents.read, api.agents.write, and api.responses.write, plus an OpenAI SDK version that exposes beta.agents. The SDK supplies the beta header; direct HTTP requests require OpenAI-Beta: agents=v1. Keep the application key outside the execution environment. Quickstart

Prepare the checkout, dependencies, and executor before creating the session because queued initial input waits up to five minutes for the environment to connect. Sandbox lifecycle

import OpenAI from "openai";

const client = new OpenAI();

// Illustrative paths. A prepared checkout and dependencies must exist at /workspace.
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-5.6-sol",
    reasoning: { effort: "medium" },
    multi_agent: { enabled: false },
    instructions:
      "Change only the assigned source and test files; save the requested patch and report separately. Run relevant tests and report the evidence.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text:
            "Fix CSV quoting in illustrative src/exportCsv.js and test/exportCsv.test.js. Preserve the exported API. Cover commas, quotes, and newlines. Write the patch and report to /workspace/outputs. Do not publish or merge.",
        },
      ],
    },
  ],
});

if (session.environment?.type !== "self_hosted") {
  throw new Error("Expected a self-hosted environment");
}

console.log({
  sessionId: session.id,
  environmentId: session.environment.id,
  remoteUrl: session.environment.remote_url,
});

The session holds configuration and conversation state. Save the session ID and environment details, then open the session’s event stream before starting the executor. The initial input is already queued and can wait for the environment connection. Creating the session does not prove that a checkout exists, that an executor is connected, or that a patch has been produced. Sessions

The prepared environment should already contain the executor version recommended by the current guide. At the time of writing, that guide uses @openai/codex@alpha. Supply a restricted environment key as CODEX_API_KEY. After creating the session and opening its event stream, connect using the returned environment ID and remote URL. Self-hosted setup

# CODEX_API_KEY is supplied through environment secret injection.
# Preparation, before session creation:
npm install -g @openai/codex@alpha
# Start after session creation and after opening the event stream:
codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

The prepared /workspace checkout is a precondition; these commands do not create it.

The executor registers and makes outbound connections to the service, then receives execution requests over the connection. The remote URL must be used unchanged. Each self-hosted session receives its own environment ID and needs its own executor. Connection contract

Keep the executor running while work is pending. Your application should save the session-to-compute mapping and coordinate startup and shutdown with incoming requests. Deleting a session does not stop self-hosted compute. Replacing compute while retaining an environment ID does not restore the old files. Sandbox lifecycle

Watch the outcome and collect the patch

Subscribe to the event stream before sending subsequent input. Follow the root turn’s completion, failure, or cancellation, and inspect its saved messages and tool results. An idle session or a closed stream does not prove that the task succeeded. Streams do not replay missed events. Reconnect and buffer incoming events, retrieve the session and saved items, then merge buffered updates by item ID. Events and items

File retrieval depends on the environment. For self_hosted, collect the patch and report using your provider’s file API or mounted filesystem. Writing into /workspace/outputs does not publish self-hosted files through the Artifacts API. In openai_hosted, files under that directory are published as immutable artifacts when a turn completes. Those copies can outlive the sandbox. Files and artifacts

For this maintenance workflow, my application would retrieve the diff, run its acceptance checks, and present a reviewable change. Creating a pull request or merging it would be a separate application action with its own authority. This is a proposed workflow, not a claim that the example has completed a real repair.

Carry the Astra/Sol policy across carefully

The earlier guide uses Astra at high reasoning effort to plan and review, with Sol at medium effort for code changes. A local AGENTS.md instruction expresses that policy, while local role configuration and orchestration fields select models.

The Agents API supports built-in delegation through agent.multi_agent.enabled and max_concurrent_subagents. Its harness supplies the coordination tools. Subagents have their own context but share the session’s environment; they inherit configured MCP access and web-search settings. The current guide says subagents do not support application function tools. Multi-agent guide

There is a subtle detail in the reference: a create_subagent_call item can record requested model and reasoning_effort values. That is evidence of per-spawn requests, not a documented policy table that locks an implementer role to Sol. The session’s multi_agent configuration exposes enablement and concurrency controls. I would not treat the local TOML role map as automatically portable, or treat an observed request as proof that a policy was enforced. Agents reference

For an application that must enforce the split, I would make the application own the handoff:

1. Create an Astra/high planning session using supplied repository evidence or explicitly read-only tools.
2. Validate its brief, then create a separate Sol/medium implementation session with an isolated working checkout.
3. Retrieve the diff and test evidence, then submit them to Astra for review.
4. Create another bounded Sol task if corrections are required.

The API accepts agent-level model and reasoning.effort; the design above uses those fields on separate sessions. Disable built-in delegation in these sessions when routing must stay under the application’s control. Give the planner only the access it needs, and validate the returned configuration and work. The session-creation example above represents the worker step. This design still requires an application controller and integration testing. Agent configuration, configuration reference

Reuse instructions and tools, then test the boundary

Skills and plugins are a practical way to carry project knowledge into the environment. For self-hosted plugins, the guide documents registering each plugin root through environment.capability_directories. Existing sessions do not reload changed plugin tools; create a new session when testing a changed package. Treat local configuration keys and API fields as separate contracts. Plugins

Execution access deserves the same care as in the original harness guide. Agent-generated code can use the files, credentials, and network exposed to its environment. Separate workloads and keep broad application credentials outside the sandbox. The executor key is deliberately narrower. Sandbox security

The deployment choice changes who operates the harness. You still define the task, supply useful context, choose access, and decide whether the result is good enough to accept.

Read the original Codex architecture post or explore the full visual architecture guide for the runtime behind these API concepts.

Documentation checked September 12, 2026, during the public beta. Examples were checked against documentation and have not been run against an authenticated Agents API session. The application-controlled planner/worker flow is an architectural proposal. Account access and compatible SDK and executor versions must be verified before use.