Skip to main content
AGENT exposes a cloud API in the OpenAI beta Agents shape and runs turns with DeepSeek Harness (dsh) by default. The Python, TypeScript, Rust, Swift and Kotlin SDKs are thin cloud clients of that API: no runtime, sandbox, tools or provider key is embedded on device. A self-hosted CLI is optional; see the AGENT API introduction.

Installation

Connection and configuration

For self-hosting, set GATEWAY_BASE_URL / GATEWAY_API_KEY / GATEWAY_MODEL together (there is no fallback to OPENAI_*). AGENT_HARNESS=dsh is the default; use AGENT_HARNESS=native for the in-process loop. DSH_BIN / DSH_HOME_ROOT / DSH_POOL_MAX / DSH_IDLE_TTL_SEC tune the child-process pool. Governed execution consists of four fail-closed seams: egress policy (AGENT_EGRESS_MODE), audit (AGENT_AUDIT_DIR), metering (AGENT_METERING_DB_PATH) and credentials (AGENT_CREDENTIAL_PROVIDER). The default AGENT_EGRESS_ENFORCEMENT=proxy needs no sidecar; network requires EGRESS_PROXY_IMAGE and CONTROL_PLANE_URL and fails closed at boot when either is missing.
Do not treat AGENT_ALLOW_UNENFORCED_EGRESS as a normal setting: it disables egress enforcement. Use proxy or network in production.

Concepts

Requests carry Authorization: Bearer <key> and OpenAI-Beta: agents=v1.

Language bindings

All five SDKs share the same shape: Agent → Session → run / runStreamed, with finalOutput or final_output on the result. memory.backend accepts cloud, local (aria memo CLI) or both; a per-call override wins.

Tool families and governance

Built-in tools are grouped into families: fs, shell, jobs, terminal, skills, web, ask, plan, todo and memo. The browser sandbox offers a six-image catalog (chromium, firefox, webkit, chrome, edge, brave). Every call passes through permission presets and approvals; approval frames arrive as agent.turn.approval.*. Read-only governance endpoints: GET /v1/governance/status (enforcement, metering, compression, credentials), GET /v1/governance/usage (records, tokens, compression), and GET /v1/governance/audit (optional kind / limit / cursor; full NDJSON export requires read_raw). Policy, credential and checkpoint writes require admin.

When to use aria-agent, aria-router or aria-engine

  • Agent scaffolding (tool calls and planning): aria-agent
  • Typed System One decisions only: aria-engine
  • OpenAI-compatible reasoning gateway (chat + policy): aria-router