> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENT cloud agents

AGENT cloud agents are Aria Compute’s cloud **agent product**. They serve the **AGENT API** in the OpenAI **beta Agents** shape: you create agents, manage sessions, and persist state, with memory in Postgres + pgvector. Turns run under DeepSeek Harness (dsh) by default, with `native` available for self-hosted deployments. Call the cloud entrypoints directly (`https://agent.ariacompute.com`); all five SDKs are cloud clients and embed no runtime or provider key. SDK memory backends are `cloud`, `local` (aria memo, SQLite) or `both`.

## Agent concepts

The AGENT API exposes the OpenAI Agents resource shape. The core entities:

| Concept | Meaning |
| - | - |
| Agent | Long-lived entity bound to a model, instructions, and tools |
| Session | One interaction trace; persists state and messages |
| Turn | One model call + tool-call loop |
| Memory | Per-principal `context_fragments` (pgvector); local SDKs can use aria memo |
| Governance | Fail-closed egress, audit, metering and credential substitution |

The resource shape also includes events (including the `agent.turn.approval.*` and `agent.turn.usage` frames), projected session titles (child sessions readable through their parent) and subagents for multi-agent delegation. Streams terminate on `agent.turn.completed` or `agent.turn.failed`; there is no `[DONE]` sentinel.

## Cloud entrypoints

The cloud AGENT API base URLs are:

* International: `https://agent.ariacompute.com`
* China: `https://agent.ariacompute.cn`

The management plane covers health, API keys and memory. The data plane authenticates with `Authorization: Bearer <key>` (or `ApiKey <key>`) plus `OpenAI-Beta: agents=v1`; endpoints include `POST /v1/agents`, `POST /v1/agents/sessions`, and `POST /v1/agents/sessions/{session_id}/events[/stream]`. Read-only governance is available at `GET /v1/governance/status`, `/usage` and `/audit`.

## SDK access

The AGENT API is also callable through the JS and Python SDKs, which mirror the OpenAI Agents SDK. Define agents, bind tools, and start sessions and turns without hand-writing HTTP requests.

```bash theme={null}
curl -s https://agent.ariacompute.com/v1/agents \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer sk_aria_your_agent_api_key' \
  -H 'OpenAI-Beta: agents=v1' \
  -d '{
    "model": "ariacompute/gemma-4-e2b-it",
    "name": "triage",
    "instructions": "You are a refund support assistant.",
    "tools": []
  }'
```

## Memory, orchestration and approvals

The AGENT API adds **memory**, **orchestration** and **approvals** to the OpenAI Agents shape:

* **Memory**: per-principal `context_fragments` in pgvector for cross-session retrieval; aria memo (SQLite) on device.
* **Subagents**: delegate tasks within a turn; child sessions are isolated under `<parent>::sub::<id>`.
* **Teams and scheduled jobs**: teams are validated task DAGs with dependency-gated claims; jobs fire at `every_secs` / `at_ms` and advance the cursor before execution — see [Teams](https://docs.ariacompute.com/api-reference/agent/teams.md) and [Scheduled Jobs](https://docs.ariacompute.com/api-reference/agent/scheduled-jobs.md).
* **Approvals and permissions**: one tool pipeline checks `read_only` / `workspace_write` / `danger_full_access` presets; with no approval provider the call is refused and the reason is fed back to the model, never silently allowed.
* **Tool families and browser**: `fs` / `shell` / `jobs` / `terminal` / `skills` / `web` / `ask` / `plan` / `todo` / `memo` share one pipeline; the browser sandbox offers a six-image catalog.
* **Governed execution**: egress policy, audit events, metering and credential substitution form four fail-closed seams; `proxy` enforcement is the default, with an optional `network` mode that requires a sidecar.

## How to run

* **Cloud**: call the entrypoints listed above; all five SDKs are cloud clients.
* **[AGENT Runtime](https://docs.ariacompute.com/sdks/agent-runtime.md)**: self-hosting is optional (`aria-agent serve --bind 127.0.0.1:8848`). Configure the model with `GATEWAY_BASE_URL` / `GATEWAY_API_KEY` / `GATEWAY_MODEL` (no `OPENAI_*` fallback) and `AGENT_HARNESS=dsh` by default. Keep clear of aria-engine (`8080` / `8010` / `8011`) and aria-router (`8899`) ports.
* Related: [AGENT API introduction](https://docs.ariacompute.com/api-reference/agent/introduction.md), [ROUTER decision routing](https://docs.ariacompute.com/concepts/router-routing.md) (the agent layer inside the gateway), [AFM foundation models](https://docs.ariacompute.com/concepts/models.md).

## See also

* [Playground experience](https://docs.ariacompute.com/guides/playground.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.