SDK Reference - Ara Docs

Use /sdk/quickstart for first-run setup. This page is the exact public surface for current ara_sdk.

Detailed pages

For grouped, method-focused troubleshooting pages:

Exported surface (`ara_sdk`)

from ara_sdk import (
    App,
    AraClient,
    AraRuntimeClient,
    Secret,
    entrypoint,
    fastapi_endpoint,
    file,
    invoke,
    local_file,
    runtime,
    run_auth_cli,
    run_runtime_cli,
    sandbox,
    schedule,
    scheduler,
    # optional adapter helpers
    command_adapter,
    langchain_adapter,
    langgraph_adapter,
    agno_adapter,
    git_artifact,
    tarball_artifact,
    event_envelope,
)

App primitives

`App(...)`

Defines app identity from a DNS-safe project_name (name + slug)
Accepts project name as App("my-app") or App(project_name="my-app")
Carries defaults (interfaces, runtime_profile)
Emits a manifest with agent + compatibility workflows

`@app.agent(...)`

Primary runnable primitive.

id (optional; defaults to function name)
entrypoint
skills (tool allow-list)
schedules (from schedule.cron/every)
optional handoff_to, runtime, sandbox, always_on
decorated function should accept a single input: dict parameter and return prompt text (str)

`@app.schedule(...)`

Decorator-based scheduling for static jobs attached to @app.agent(...) or @app.tool(...).

Trigger fields: cron= and at=[...]
at supports HH:MM, 5-field cron strings, or ISO timestamps (Z/UTC recommended for one-shot runs)
Multiple trigger styles can be combined in a single decorator
id is optional; when omitted, the SDK auto-generates a stable schedule id
Optional run= overrides target; default target is the decorated agent/tool

`@fastapi_endpoint(...)`

Expose an agent as an HTTP endpoint in the app manifest.

Supports one method per declaration (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)
Supports auth modes: none, header, bearer, hmac
Default label comes from function name (slugified)
Request body is forwarded to runtime under input["input"] to avoid key collisions with gateway metadata

`@app.tool(...)`

Single primitive for model schema + runtime execution.

Exposes OpenAI-style function schema to the model
Embeds deterministic Python source + callable metadata for runtime tool execution

Schedule builders

`invoke.agent(...)` / `invoke.tool(...)`

Target definitions used by schedules.

`schedule.cron(...)` / `schedule.every(...)`

Schedule spec builders used in @app.agent(..., schedules=[...]) and scheduler.create/upsert(...).

`scheduler.create(spec)` / `scheduler.upsert(spec)`

Builds automation_create payloads from the same schedule spec shape.

Runtime helpers

`runtime(...)`

Builds runtime profile fields:

files/startup/image/resources
env
secrets (Secret.from_name, from_dict, from_dotenv)

`sandbox(...)`

Builds sandbox placement/spawn policy shape.

`entrypoint(...)`, `file(...)`, `local_file(...)`

Helpers for startup and runtime files.

`AraClient`

`deploy(...)`

deploy(
    activate=True,
    key_name=None,
    key_rpm=60,
    warm=False,
    warm_agent_id=None,
    on_existing="update",
)

Creates/updates app from manifest
Syncs local secret values to /apps/{app_id}/secrets
Mints and returns a runtime key (runtime_key in command result)
Optional warmup invoke via warm_agent_id

`run(...)` / `run_async(...)` / `run_status(...)` / `events(...)` / `logs(...)`

Target an app agent via agent_id
SDK sends both agent_id and compatibility workflow_id
logs() yields live runtime log rows for active runs (streaming, no history backfill)

CLI (`ara` app commands)

ara deploy app.py [--activate true|false] [--key-name NAME] [--rpm 60] [--warm true|false] [--warm-agent AGENT_ID] [--on-existing update|error]
ara up app.py     [--activate true|false] [--key-name NAME] [--rpm 60] [--warm true|false] [--warm-agent AGENT_ID] [--on-existing update|error]
ara auth login [--api-base-url URL] [--api-key KEY] [--provider google] [--timeout-seconds 180] [--auth-flow poll] [--no-browser] [--supabase-url URL] [--supabase-anon-key KEY]
ara auth whoami [--api-base-url URL]
ara auth rotate [--api-base-url URL]
ara auth logout
ara start
ara status
ara stop
ara connect "ara://connect?token=..."
ara ssh-proxy --token SHORT_LIVED_PROXY_TOKEN
ara runtime session start
ara runtime session status
ara runtime session stop
ara run app.py [--agent AGENT_ID] [--message TEXT] [--input key=value ...] [--runtime-key KEY] [--app-header-key KEY]
ara run-async app.py [--agent AGENT_ID] [--message TEXT] [--input key=value ...] [--response-mode poll|webhook] [--callback-url URL] [--callback-secret SECRET] [--runtime-key KEY] [--app-header-key KEY]
ara events app.py [--agent AGENT_ID] [--event-type TYPE] [--channel CHANNEL] [--source SOURCE] [--message TEXT] [--input key=value ...] [--metadata key=value ...] [--runtime-key KEY] [--app-header-key KEY]
ara run-status app.py --run-id RUN_ID [--runtime-key KEY] [--app-header-key KEY]
ara logs app.py [--runtime-key KEY] [--app-header-key KEY]
ara setup app.py
ara setup-auth app.py
ara invite app.py --email user@example.com [--role viewer|operator|editor] [--expires-hours 168]

Runtime logs

ara logs app.py / AraClient.logs() are realtime streams only; they do not return historical logs.
Start the logs stream first, then trigger run/run-async in another terminal.
Persist locally with shell piping: ara logs app.py | tee app.logs
If the stream is connected but prints nothing, verify auth key selection and confirm the runtime path emits log events for your app/run.

`AraRuntimeClient`

Session-scoped client for interacting with a running Ara session. Uses ARA_API_KEY (user API key). See /sdk/runtime-client for full guide.

`chat(...)`

chat(message: str, model: str = "", conversation_id: str = "", timeout: int = 120) -> dict

Send a message through the full agent loop (LLM + tools + sandbox + memory). Returns:

{"text": "...", "tool_calls": [{"name": "...", "args": {...}, "result": "..."}]}

`execute_tool(...)`

execute_tool(session_id: str, tool_name: str, args: dict, agent_id: str = "") -> dict

Run any sandbox tool directly (read_file, write_file, exec, automation_list, etc.)

`capabilities(...)` / `skills(...)` / `tools(...)`

Inspect the agent’s runtime state — available tools, loaded skills, session capabilities.

`control_actions(...)` / `control_call(...)`

List and trigger runtime control actions. control_call requires an active WebSocket connection (app UI open).

Auth/env notes

Control plane credentials are resolved in this order:
1. ARA_API_KEY
2. ARA_ACCESS_TOKEN (legacy fallback)
3. ara auth login credentials from ~/.ara/credentials.json
Runtime calls (including logs) use runtime key or app-header key (X-Ara-App-Key)
FastAPI endpoint calls (/v1/apps/{app_id}/endpoints/{endpoint_label}) use endpoint-specific auth from manifest (none|header|bearer|hmac)
ara auth login stores Supabase JWT + refresh token locally and ara auth logout clears that file
AraRuntimeClient uses ARA_API_KEY for session-scoped access
interfaces.inherit_owner_tools defaults to false

SDK

SDK Detailed

​Detailed pages

​Exported surface (ara_sdk)

​App primitives

​App(...)

​@app.agent(...)

​@app.schedule(...)

​@fastapi_endpoint(...)

​@app.tool(...)

​Schedule builders

​invoke.agent(...) / invoke.tool(...)

​schedule.cron(...) / schedule.every(...)

​scheduler.create(spec) / scheduler.upsert(spec)

​Runtime helpers

​runtime(...)

​sandbox(...)

​entrypoint(...), file(...), local_file(...)

​AraClient

​deploy(...)

​run(...) / run_async(...) / run_status(...) / events(...) / logs(...)

​CLI (ara app commands)

​Runtime logs

​AraRuntimeClient

​chat(...)

​execute_tool(...)

​capabilities(...) / skills(...) / tools(...)

​control_actions(...) / control_call(...)

​Auth/env notes