One core.Many agents._

Between an agent that works in a terminal and an agent a product can call, there is a whole layer of engineering. OpenAgentCore is that layer.

Choose the model, the agent and the machine separately.

They are three different decisions. Each Session names its harness, its model provider and its Environment; Core validates the combination before anything runs.

 1from openai import OpenAI
 2
 3client = OpenAI()  # OPENAI_BASE_URL → your Core
 4
 5session = client.beta.agents.sessions.create(
 6    environment={"type": "openai_hosted"},
 7    input="Fix the failing test and explain the change.",
 8    extra_body={
 9        "agent": {"model": MODEL, "x_agents_core": {"harness": "codex"}},
10        "x_agents_core": {"model_provider": {
11            "protocol": "responses",
12            "base_url": BASE_URL, "api_key": API_KEY,
13        }},
14    },
15)

• [api]

  Same API as OpenAI

  Point the official OpenAI SDK, or plain HTTP, at your installation. No new client to learn.

• [agent]

  Your choice of agent

  Each Session runs a native harness: Codex, Claude Code or MiniMax Code, with the model provider you configure.

• [machine]

  Your choice of machine

  A managed sandbox (Docker, microsandbox or E2B), or your own Linux, macOS or Windows machine.

• [swap]

  Every part is replaceable

  Sandboxes, harnesses and model providers plug in through defined protocols. Swap one without touching Core.

Every part plugs in through a protocol.

Core keeps durable execution state and schedules work. The Runtime prepares the Environment and starts the native harness. The harness calls the model and tools, and reports back through the Runtime.

ecosystemcomponentsapi namespaces

A run becomes a Session you can manage.

A Session is a continuing piece of agent work; a Turn is one input executed inside it. Both have identities and durable state. Four rules decide what "running", "waiting", "cancelled" and "failed" mean.

• client ──────╳  disconnect
  turn   ━━━━━━━━━━━━━━▶ completed

  Connection ≠ work

  Closing the stream only removes an observer. Submitted work stays with the execution system.

• POST  Idempotency-Key: a1f ──▶ turn_01
  POST  Idempotency-Key: a1f ──▶ turn_01

  Retries have identity

  Supported submission paths carry a stable key, so a lost response never creates the work twice.

• cancel ──▶ turn  in_progress
         ──▶ turn  cancelled  ✓ confirmed

  Cancel has a receipt

  Closing output proves nothing. Core confirms the target Turn's execution and cleanup.

• turn        ━━━━┫
  executor    ━━━━━━━━┫
  environment ━━━━━━━━━━━━━┫

  Execution ≠ machine

  A Turn ending, the executor closing and the Environment being reclaimed are separate lifecycles.

!Recovery has limits, and they are explicit: an unknown outcome is never reported as success.

What you still own, depending on how you build.

State belongs to the infrastructure.Intelligence belongs to the harness.

The choices behind the design.

1. 01

   Native harnesses, with their constraints

   The Runtime and the native harness run inside the Environment; Core holds the durable control plane. Native engines are reused as-is, so the Environment, native history and recovery still matter.

2. 02

   One protocol, real differences

   A capability one harness supports is not silently granted to another. Core checks each combination before running, rejects what is unsupported and records what is unverified.

3. 03

   Simple for the caller

   Callers think in tasks, input, state and results. Machine connections, native executors and cleanup belong behind clear component boundaries. The interface is the product.

Version 1 is the foundation.

OpenAgentCore is pre-release; support is qualified per harness, environment and operation. The next layers we are working toward:

1. harness

   Agent loop, decoupled

   Run the agent loop on the server and tool execution on a local machine or a cloud sandbox, with enterprise authorization at the tool layer.

2. compute

   Faster, denser compute

   Separate compute from storage, restore state quickly and scale sandbox capacity on demand.

3. storage

   More storage backends

   S3, OSS, shared file systems and agent-native file systems.

4. apps

   Applications on the Agents API

   Keep building real products on the public API, the same way any application uses it.

Everything is in the docs.

21 pages, listed straight from the repository's docs.json. New guides appear here when they are added.