> ## 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 runtime

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](https://docs.ariacompute.com/api-reference/agent/introduction.md).

## Installation

| Language | Install |
| - | - |
| Python | `pip install ariacompute-agent` |
| TypeScript | `npm i @ariacompute/agent` |
| Rust | `cargo add ariacompute-agent` |
| Swift | `pod 'AriaComputeAgent'` |
| Kotlin | `implementation("com.ariacompute:agent:+")` |

## Connection and configuration

```bash theme={null}
export ARIA_AGENT_BASE_URL=https://agent.ariacompute.com
export AGENT_CLOUD_API_KEY=sk_aria_your_agent_api_key
```

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.

> [!WARNING]
>
> Do not treat `AGENT_ALLOW_UNENFORCED_EGRESS` as a normal setting: it disables egress enforcement. Use `proxy` or `network` in production.

## Concepts

| Concept | Meaning |
| - | - |
| Agent | A long-lived entity binding a model, instructions and tools |
| Session | A persisted interaction trail with state and messages |
| Turn | One model call plus its tool-call loop |
| Memory | Cloud `context_fragments` (Postgres + pgvector); local SDKs can use aria memo |
| Governance | Fail-closed egress, audit, metering and credential substitution |

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

```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/ariamodel-small","name":"triage","instructions":"You are a refund assistant.","tools":[]}'
```

## 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.

```python Python theme={null}
# pip install ariacompute-agent
import asyncio, os
from ariacompute_agent import Agent, ClientOptions, Runner, Session, function_tool

client = ClientOptions(
    base_url=os.environ.get("ARIA_AGENT_BASE_URL", "https://agent.ariacompute.com"),
    api_key=os.environ.get("AGENT_CLOUD_API_KEY"),
)

@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."

agent = Agent(name="History tutor", instructions="Be concise.", model="gpt-4o-mini",
              tools=[history_fun_fact], client=client, memory_backend="both",
              memo_db="~/.ariacompute/memo.db")

async def main() -> None:
    session = Session.create(agent, client)
    first = await Runner.run(agent, "When did the Roman Empire fall?", session=session)
    print(first.final_output)
    session.memorize("user_name", "Ada")
    print((await Runner.run(agent, "What is my name?", session=session)).final_output)
    print(session.recall("user_name"))                     # -> "Ada"
    print(session.recall("user_name", backend="local"))    # local aria memo only
    streamed = await Runner.run_streamed(agent, "Tell me something surprising", session=session)
    async for event in streamed.events:
        if event["type"] == "agent.turn.output_text.delta":
            print(event["delta"], end="")

asyncio.run(main())
```

```rust Rust theme={null}
// cargo add ariacompute-agent
use aria_agent_ffi::{AriaAgent, AriaAgentConfig, ClientOptions, MemoryConfig, StreamListener, StreamEvent};

struct Printer;
impl StreamListener for Printer {
    fn on_event(&self, event: StreamEvent) {
        match event.kind.as_str() {
            "agent.turn.output_text.delta" => print!("{}", event.delta.unwrap_or_default()),
            _ => {}
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Cloud client: HTTP only — no runtime or provider key on device.
    let agent = AriaAgent::new(AriaAgentConfig {
        name: "History tutor".into(),
        instructions: Some("Be concise.".into()),
        model: None,
        id: None,
        client: Some(ClientOptions {
            base_url: Some("https://agent.ariacompute.com".into()),
            api_key: Some(std::env::var("ARIA_AGENT_API_KEY")?),
            beta_header: None,
        }),
        memory: Some(MemoryConfig { backend: Some("both".into()), memo_bin: None,
                                    memo_db: Some("~/.ariacompute/memo.db".into()) }),
    })?;
    let session = agent.create_session()?;
    session.memorize("user_name".into(), "Ada".into(), None)?;
    println!("{}", agent.run("What is my name?".into(), Some(session.clone()))?.final_output);
    println!("{:?}", session.recall("user_name".into(), Some("local".into()))?);
    let result = agent.run_streamed("Tell me something surprising".into(), Some(session),
                                    Box::new(Printer), None)?;
    println!("\n{}", result.final_output);
    Ok(())
}
```

```swift Swift theme={null}
// pod 'AriaComputeAgent'
import AriaComputeAgent

final class Printer: StreamListener {
    func onEvent(event: StreamEvent) {
        if event.kind == "agent.turn.output_text.delta" { print(event.delta ?? "", terminator: "") }
    }
}

do {
    let agent = try AriaAgent(config: AriaAgentConfig(
        name: "History tutor", instructions: "Be concise.", model: nil, id: nil,
        client: ClientOptions(baseUrl: "https://agent.ariacompute.com",
                              apiKey: ProcessInfo.processInfo.environment["ARIA_AGENT_API_KEY"],
                              betaHeader: nil),
        memory: MemoryConfig(backend: "both", memoBin: nil, memoDb: "~/.ariacompute/memo.db")
    ))
    let session = try agent.createSession()
    try session.memorize(key: "user_name", value: "Ada", backend: nil)
    print(try agent.run(input: "What is my name?", session: session).finalOutput)
    print(try session.recall(key: "user_name", backend: "local") ?? "")
    let result = try agent.runStreamed(input: "Tell me something surprising", session: session,
                                       listener: Printer(), maxTurns: nil)
    print(result.finalOutput)
} catch {
    print(error)
}
```

```kotlin Kotlin theme={null}
// implementation("com.ariacompute:agent:+")
import com.ariacompute.agent.uniffi.aria_agent_ffi.*

fun main() {
    // Cloud client: HTTP only — no runtime embedded in the app.
    val agent = AriaAgent(AriaAgentConfig(
        name = "History tutor", instructions = "Be concise.", model = null, id = null,
        client = ClientOptions(baseUrl = "https://agent.ariacompute.com",
            apiKey = System.getenv("ARIA_AGENT_API_KEY"), betaHeader = null),
        memory = MemoryConfig(backend = "both", memoBin = null, memoDb = "~/.ariacompute/memo.db")
    ))
    val session = agent.createSession()
    session.memorize("user_name", "Ada", null)
    println(agent.run("What is my name?", session).finalOutput)
    println(session.recall("user_name", "local"))
    val result = agent.runStreamed("Tell me something surprising", session,
        object : StreamListener { override fun onEvent(event: StreamEvent) = println(event.kind) }, null)
    println(result.finalOutput)
}
```

```typescript TypeScript theme={null}
// npm i @ariacompute/agent
import { Agent, run, runStreamed, Session, tool } from "@ariacompute/agent";

const client = {
  baseUrl: process.env.ARIA_AGENT_BASE_URL ?? "https://agent.ariacompute.com",
  apiKey: process.env.AGENT_CLOUD_API_KEY,
};
const historyFunFact = tool({ name: "history_fun_fact", description: "Return a short history fact.",
  parameters: { type: "object", properties: {} } });
const agent = new Agent({ name: "History tutor", instructions: "Be concise.",
  model: "gpt-4o-mini", tools: [historyFunFact], client,
  memory: { ...client, backend: "both", memoDb: "~/.ariacompute/memo.db" } });

const session = await Session.create(agent, client);
await session.memorize("user_name", "Ada");
console.log((await run(agent, "What is my name?", { session })).finalOutput);
console.log(await session.recall("user_name", { backend: "local" }));
const streamed = await runStreamed(agent, "Tell me something surprising", { session });
for await (const event of streamed.events) {
  if (event.type === "agent.turn.output_text.delta") process.stdout.write(event.delta);
}
```

## 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](https://docs.ariacompute.com/sdks/engine-runtime.md)
* **OpenAI-compatible reasoning gateway (chat + policy)**: [aria-router](https://docs.ariacompute.com/sdks/router-runtime.md)


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