index.md

title	OpenAI compatibility

Core implements the OpenAI Agents API pinned below. This ledger lists each resource's coverage, every difference from the official service and the known gaps.

The target is the complete API (public API rule). API namespaces and credentials says who calls which API, and the Agents API guide shows how to use it.

Pinned baseline

File	Contents
upstream.json	The pin: openai-python 3.13.0 at commit d7c41ef, resources under beta/agents, Beta header agents=v1
upstream/openapi.json	Unmodified official OpenAPI 3.1 at commit 046a2a0f325bf11f97966f2729219f27281ba71e, published on 2026-09-10. Its 58 Agents, Vaults, Files and Skills operations match the pinned SDK route set. upstream.json records the SHA-256 checksum
upstream-routes.json	The normalized method/path inventory generated from the official schema
openapi.yaml	The official public contract with Core's x_agents_core extension on Agent and Session request/response objects
go-bindings.json	Go names, field representations, encoding order and stored projections; it does not define official field membership, enums or constraints

The official source and existing service have these recorded differences: Agents authentication errors can return a null code; empty Files pages return null first_id and last_id; File resources can return null expires_at and status_details. The source declares those fields non-null. The official-client response validator allows null only for these named fields and otherwise validates OpenAPI 3.1 response schemas. Files and Skills operations omit error responses in the source, so those error bodies use the upstream shared ErrorResponse schema. API behavior and raw HTTP tests qualify service behavior; the published schema retains the official definitions.

Evidence for a status comes from the pinned official SDK and raw HTTP against the running service, as CONTRIBUTING requires.

Coverage by resource

Implemented means every operation serves the pinned shapes; limits that remain are listed under known gaps. Partial names what is missing.

Resource	Operations	Status	Contract
Agents	create, retrieve, update, list, delete	Implemented. Every pinned setting is saved; Session admission runs a subset	Agents
Sessions	create (JSON or stream), retrieve, update, list, delete	Implemented. Update takes metadata only; deletion requires an idle or failed Session	Sessions, creation streaming
Session events	create, stream	Partial: messages with text and images, cancellation, function results; the stream is live only	Sessions, events and history, message content
Turns	retrieve, list	Implemented; Session Turn routes hold root Turns only	Turns and Items
Items	list	Partial: messages, commands, MCP calls, functions, web search, reasoning and Subagent coordination Items; other native variants are not projected	Turns and Items
Artifacts	retrieve, list, delete, content	Implemented	Environment files and Artifacts
Subagents	retrieve, list; Items; Turns retrieve and list; Turn Items	Partial: read-only child work; no live child progress or optional native operations	Subagents
Environments	retrieve	Implemented; Session-scoped (ownership). The pinned contract rejects environment.environment_id; existing hosted Environments cannot be attached across Sessions. Workspaces shared across Sessions belong to the application (Projects own assets)	Environments
Environment files	create, list	Implemented; the list is not recursive	Environment files and Artifacts
Environment Templates	create, retrieve, update, list, delete	Implemented; execution limits are listed under known gaps	Environment Templates
Vaults	create, retrieve, list, delete	Implemented	Vaults and Credentials
Vault Credentials	create, retrieve, update, list, delete	Implemented for static_bearer and mcp_oauth	Vaults and Credentials
Files	create, retrieve, list, delete, content	Implemented for purpose=user_data; content download is rejected	Files and Skills
Skills and Skill versions	create, retrieve, update, list, delete, content	Implemented	Files and Skills

Which operation each Harness supports on each placement is in the Harness capabilities. API behavior holds the rules that apply across resources: requests, errors and lists.

Core's own fields sit inside x_agents_core (Core extensions). The Core administration API (/core/v1) and the machine API (/api/v1) are not part of the Agents API.

Differences from OpenAI

Each item is Core's deliberate or native behavior where the official service behaves otherwise. The linked rule states the exact behavior.

Requests and errors (API behavior)

• Core sends no OpenAI-Organization or OpenAI-Project response headers.
• HEAD on the event stream, on content downloads and on the Environment files list returns 405.
• A JSON array body is rejected; the official service reads [] as {}.
• U+0000 in a stored string returns 400; the official service stores it.
• Not-found messages never name the resource; Core quotes a full metadata key where the official message abbreviates it.
• Resource IDs are UUIDs; official IDs carry a type prefix, such as sess_ for Sessions.
• UUID identifiers also resolve in other spellings, such as uppercase or braces.
• The Files routes keep a local unsupported_parameter code for a repeated query key.
• Core has no CORS handling; the official service sends CORS headers.

Lists (lists)

• A deleted Agent used as a cursor returns 404; the official service still pages from it.
• A Turn cursor from another Session, a Credential cursor equal to its Vault ID, and a Skills cursor that is not a Skill ID return 404.
• Vault and Credential lists clamp a negative limit, as the pinned SDK describes; the official service returns 400.

Agents and Sessions (Agents, Sessions)

• A repeated Session creation with the same Idempotency-Key returns the original Session; the official service creates a new one.
• Omitted programmatic tool calling keeps the Harness's native behavior; the official default is on.
• An Agent without a web_search tool keeps the Harness's native search; the pinned contract does not define search without the tool.
• Claude Code on a workspace placement appends the Agent's instructions to its native system prompt and runs its native tool set. Its search has no cached mode and no domain, location or context-size settings.
• Claude Code drops whitespace-only text blocks natively and sends (no content) for an all-blank message; Codex delivers whitespace-only text unchanged.
• Claude Code runs a Skill's inline shell inside the Skill expansion, so the command produces no tool observation.
• Claude Code with live search on environment: none has only WebSearch, so search yields search actions and no page opens (web search).
• An omitted reasoning effort stays null instead of taking the model's default.
• Codex maps programmatic tool calling to its native code_mode, whose model-written scripts call the other tools; the feature is under development upstream.
• Codex rejects programmatic tool calling together with multi_agent.
• Codex runs without its native goals (create_goal, get_goal and update_goal), because an active goal starts turns of its own after the Turn ends (Codex Runtime).
• A Session's agent.tools omits tool_search declarations.
• Core rejects an inline authorization on a Session MCP transport, an Authorization entry in headers and a nonempty stdio env: credentials come only from Vaults (credential_id) and environment values only from the Environment (env_vars) (MCP).
• A stdio MCP server needs a workspace placement and the origin environment. Claude Code starts the server in its workspace directory, so cwd must equal it, with its whole process environment, which also holds the model provider key and other servers' Vault bearer tokens, and it needs allowed_tools null. MiniMax Code starts the server in its private home directory, so it rejects every stdio server (MCP).
• Core rejects nonempty MCP request_metadata, which no Harness can send, as well as a stdio server whose connection_origin is service, an empty credential_id and an empty allowed_tools name, which the pinned schema allows without defining their meaning (400 with the reason).
• Claude rejects an MCP server_url or headers value containing ${, because the native client expands ${VAR} in both from a process environment that holds Core-held credentials.
• Each Harness rejects the MCP labels its native client reserves, such as functions on Claude Code (MCP).
• An MCP server that cannot be reached is handled natively: an optional server's tools are missing and a required one fails the start (MCP). The official Item and Turn failure shapes are not reproduced.
• Deleting a Session right after an events 202 returns 409, because Core admits the Turn in the same transaction; the official service returns 200.
• Deleting a Session while its hosted Environment runs setup succeeds when no input is pending; the official service returns 409.

Input, events and history (Sessions, events and history, message content)

• Input to a none Session is admitted synchronously; Core does not emulate the official asynchronous admission window.
• An events request takes at most 64 events (send input); the official limit is 16384.
• A function result that resumes a waiting Turn emits turn.in_progress.
• A function call the native Harness abandons, such as a Subagent call dropped when the root closes or interrupts the child or a MiniMax Code call past its 120 s timeout, is withdrawn: it stops being a required action and a later result for it returns 409 conflict_error. The official API has no withdrawal.
• Attaching to the stream mid-Turn sends no catch-up Item snapshots.
• The Items list includes in-progress and incomplete output Items, and keeps a failed function result's submitted output.
• Error messages omit the call and executor IDs that official messages include, except that the unknown tool call message names its call_id.
• A failed Turn reports the model failure categories under their official names and sandbox_error for a Runtime that disconnected or failed its preparation. Every other Core failure, such as an unavailable Runtime, a missing model provider, a rejected input or a storage failure, reports internal_error. The message is a fixed sentence per code and never carries native text. Subagent Turns always report internal_error.
• An empty text part beside other text is accepted and stored.
• Empty input returns 400 invalid_request with a generic message and a null param; the official response is invalid_request_error with param input.
• Session usage is available as soon as every root Turn has settled; official reads lag by seconds.
• U+0000 in Harness output, such as command output, reads as U+FFFD; the official service keeps it.
• A reasoning Item carries what the Harness shows of its native reasoning: its native summary when it produces one, otherwise its native reasoning text, such as Codex raw reasoning or the thinking text the model API returns to Claude Code. Each native part is one summary_text part, and native reasoning without text is not reported, so Claude Code with the model provider's thinking.display omitted reports none. Codex streams the first native channel an item delivers, its summary or its raw reasoning text.

Environments and Templates (Environments)

• openai_hosted and Template capability_directories must lie inside /workspace; the official service also accepts system paths such as /etc (capability directories).
• env cannot set OPENAI_API_KEY, which Core reserves (env); the official service accepts it.
• A self_hosted Session without pending input requests no connection (activity); one unused official Session switched to requires_action with environment_connection about five minutes after creation, and its deletion then returned 409.
• A hosted Environment emits ready once, when its initialization completes, and not again before each later Turn as one official Session did. It also emits connected and disconnected, which that Session did not.
• A hosted Environment's connected and pending arrive in either order: Core journals connected when it observes the Runtime's connection and pending when initialization starts on that Runtime. ready follows both, so the last Environment event can read ready while the Environment is connected.

Files, Skills, Environment files and Artifacts (Files and Skills, Environment files and Artifacts)

• File uploads hold up to 512 MiB; the official limit is 512 MB. A purpose filter other than user_data returns an empty page.
• Skill version numbers are never reused, and uploads and deletions of one Skill run one at a time.
• Environment files work on self_hosted Environments, which the official service refuses.
• Creating an Environment file over an existing regular file returns the "must not traverse symlinks or overwrite existing files" message. A parent symbolic link that stays inside the workspace is followed, and a parent that escapes the workspace or is a regular file gets a generic 400; the official service rejects symbolic-link parents.
• File names hold 1–1,024 bytes; the official service accepts empty and longer names.
• A SKILL.md front-matter key other than name, description, license, compatibility and metadata is rejected; the official service accepts unknown keys (upload a bundle).

Vaults and Credentials (Vaults and Credentials)

• MiniMax Code runs public function calls one at a time, so the application sees one function_call at a time.
• MiniMax Code serves public functions as a native MCP server whose client fails a call after 120 s with no way to change it. After 120 s native reports the failure to the model, the call is withdrawn and the Turn continues.
• Vault and Credential status is stored privately and defaults to active; with no archive operation, lists without a filter include both statuses.
• An unknown or foreign Vault in vault_ids returns 404 "Resource not found."; the official message names the ID.
• An explicit null for OAuth access_token, refresh or token_endpoint_auth in an update keeps the stored value.
• A static token must be an RFC 6750 b64token to run; other stored tokens fail at dispatch.
• Vault metadata has a 64 KiB bound and no pair or length limits; names are 1–256 bytes after trimming.
• A Credential's mcp_server_url is stored and matched as sent; the official service lowercases its scheme and host.

Known gaps

Configuration and tools

• A reasoning.effort, reasoning.summary, service_tier, text.verbosity, web_search mode or setting or programmatic_tool_calling value that the selected Harness does not declare is saved but rejected at Session admission (Harness capabilities).
• Harness support for tools, structured output, deferred discovery, subagents and MCP differs by Harness and placement; see the Harness capabilities. MiniMax Code has no image input and accepts at most 32 KiB of instructions.
• Model-derived reasoning defaults are not resolved.

Execution and history

• The stream does not emit every pinned interim tool-output variant.
• Native Item variants beyond those listed under Turns and Items are not projected, and Items cannot be modified.
• A function result that cancellation prevents from being applied never appears as an Item.
• Pinned Codex can lose command output emitted before its stream subscription.
• Claude Code and MiniMax Code report no public usage.
• agent_message and interrupt_subagent_call Items are accepted by the Runtime protocol, but no Harness adapter produces them.
• Codex file changes have no official Item type (Turns and Items).
• Claude Code runs at most 64 messages in one Turn, counting its opening input (Runtime boundary); a Turn that receives more fails with internal_error.
• MiniMax Code receives a message that starts with / with a trailing blank line, because ACP otherwise runs it as an operator command.
• Core gives no crash-safe or exactly-once guarantee for native side effects; claimed work fails on restart without replay.
• file_id and detail on images are rejected; each Harness declares which image_url values it accepts (message content).

Environments and Templates

• Hosted workspace admission is limited by the tenant capacity policy and the input reservation deadline.
• MiniMax Code does not declare retained_native_history, so it cannot run on microsandbox, which keeps every Environment on workspace storage; Core rejects the Session (Harness capabilities).
• The model provider's port stays reachable at public addresses from the sandbox because the Harness runs there, and a private model provider host only when the network cap lists its name or a *. entry that covers it; under disabled the host's DNS server stays reachable on port 53; MCP connections from the Environment follow the deployment's network cap. E2B sandboxes cannot reach private networks, and 169.254.169.254 answers inside an E2B sandbox under every cap.
• disabled and restricted networking run on hosted Environments whose sandbox Provider can restrict egress, within the deployment's network cap; self_hosted Environments accept only enabled (network policy). The official API accepts an allowed_domains entry with a leading dot, such as .example.com, with unspecified meaning; Core rejects it.
• packages.system other than null or an empty list is rejected; system packages must be preinstalled.
• Environment.files lists the files recorded at Session creation; files created later through the Environment files API do not appear.
• Cold continuation does not restore process memory, background processes or temporary system-disk changes, and completed setup is not replayed (Environment persistence). On compatible microsandbox nodes with retained NFS storage, Codex and Claude Code are qualified for checkpoint transfer and for continuation after confirmed compute loss. Takeover of an unconfirmed old writer, host-crash durability and arbitrary crash-damaged history are unqualified.

Files and Environment files

• Files accept only purpose=user_data; other purposes, expires_after and the Uploads API are not supported.
• The Skills create route accepts a single files part, but the pinned SDK sends no part when files is one file instead of a list (upload a bundle).
• An Environment file write whose outcome is uncertain is never retried or recovered automatically; it blocks further writes and messages to the Session.

Vaults and Credentials

• There is no storage-key rotation or re-encryption.
• OAuth refresh happens only at dispatch: there is no refresh on a provider 401, no mid-Turn replacement and no withdrawal of a token already sent to a Runtime.
• Credential creation takes no Idempotency-Key.

Sessions

• Session deletion does not purge the stored history physically.
• Stream lifetimes for self_hosted, hosted and no-input creation, and the creation-stream retry, are Core's own choices.

Unverified against the official service

• The order of errors when one request has several faults, and error, default and payload-limit parity in general.
• A Subagent's function call: Core makes it a required action of the root Turn that runs the child, with turn_id set to that Turn, and publishes the child's function_call Item once as agent.session.turn.item.added with the child Turn ID and a null output_index; a result may name either Turn. The Turn is waiting and the Session requires_action while root output may continue, and the call_id equals the call_id of the child's function_call Item. Claude Code publishes the child's Items when the root Turn settles, after the required action.
• Whether the official service emits Environment pending and when: Core emits it when a hosted Environment's initialization starts, and the one official sample showed only ready, about 29 s after creation.
• Whether Subagent child Turns and pending Environment file writes block Session deletion.
• The official order between the pending-input error and an unknown result target.
• Whether a Session whose latest Turn failed accepts new input: Core starts a new Turn, and one official sample rejected the input.
• The event order when a waiting Turn resumes or is cancelled.
• A Turn with several pending function calls: Core lists them all in one requires_action; no official sample had parallel calls.
• Subagent task text and nesting: Core puts the native task prompt in the create_subagent_call content, while one official sample left it out; the agent_id of a nested child and the child's input Item have no official sample.
• Template env beside Session env: Core merges by key and the Session value wins (inheritance).
• Failure reasons for npm, initial-file and Skill installation have no official sample.
• Codex behavior for an empty text part beside text, and for images in failed function results or as remote references.
• Official HEAD behavior on the routes where Core returns 405.
• Environment Template hostname forms beyond exact hosts, and disabled combined with domains.
• Files purpose filtering and pagination while Files change; official Skill upload limits and error timing, and the error for a malformed Skill version.
• Environment file list defaults (limit 20, the workspace root as the default path, page-token invalidation), the 50 MiB file_id copy limit and the check order on create.
• Artifact capture of hard links, special files and a linked outputs directory, republication after changed bytes, and content headers and ranges.
• Vault and Credential error and retry semantics, pagination under concurrent writes, visibility after deletion, OAuth refresh timing and errors, and restricted-key scopes.