Skip to main content
The AGENT API serves OpenAI beta Agents resources: create agents, manage sessions, run turns and stream agent.turn.* events. Turns run under DeepSeek Harness (dsh) by default; AGENT_HARNESS=native selects the in-process loop. State lives in Postgres + pgvector, with context_fragments scoped by principal. Every request must carry OpenAI-Beta: agents=v1. The five SDKs (Python, TypeScript, Rust, Swift, Kotlin) are cloud clients of this API and embed no runtime, sandbox, tools or provider key. Full examples are in the AGENT runtime guide.

Authentication

Bearer or ApiKey; governance endpoints need read/admin scope

Create an agent

Create an agent with a model, instructions and tools

Create a session

Start a session for an existing agent and track its state

API keys

Create, list and revoke API keys

Base URL

The China site uses https://agent.ariacompute.cn.

Authentication

Send the API key in Authorization (Bearer or ApiKey) and include the beta header:
Resolution order:
  1. A key equal to AGENT_CLOUD_API_KEY maps to the Admin principal.
  2. Otherwise the sha256 digest is looked up in api_keys.
  3. With no key: 401 when AGENT_CLOUD_API_KEY is set; otherwise open mode with the default principal.
Self-service keys are managed at /v1/api-keys and require admin scope.

Data-plane endpoints

Streams end with agent.turn.completed or agent.turn.failed; there is no [DONE] sentinel. Approvals and usage arrive in agent.turn.approval.* and agent.turn.usage frames — see the event stream.

Tool families and browser

Built-in tools are grouped as fs, shell, jobs, terminal, skills, web, ask, plan, todo and memo. The browser sandbox provides a six-image catalog (chromium, firefox, webkit, chrome, edge, brave). Declare tools in the tools array when creating an agent; calls pass through permission presets and approvals.

Governed execution (read-only)

The read-only endpoints need read scope; the full NDJSON export needs read_raw. Policy, credential and checkpoint writes need admin and are not exposed to browsers.

Error format

Errors return an HTTP status plus an OpenAI-shaped JSON envelope with a flat message field:

Versioning

The API is prefixed with /v1. Some routes are recognized but return HTTP 501 Not Implemented and have no dedicated page:
  • Vaults: GET|POST /v1/vaults, GET /v1/vaults/{vault_id}, GET /v1/vaults/{vault_id}/credentials
  • Environments: GET|POST /v1/agents/environments and the corresponding detail / file / template routes
  • Session artifacts: GET /v1/agents/sessions/{session_id}/artifacts
Implemented extension routes:
  • Session titles: docs
  • Agent teams (task DAGs with dependency gating): docs
  • Scheduled jobs (advance the cursor before execution): docs
  • Subagents: in-process delegation belongs to the turn runtime; the REST subagent routes and their current limits are described in list