SDK Overview

Python SDK links: GitHub repository · ara-sdk on PyPI

​

Core model

1. Define with App(project_name), @app.agent, @app.tool, @app.schedule, @fastapi_endpoint, and runtime helpers (runtime, sandbox, Secret)
2. Schedule with @app.schedule(...) (or schedule.cron/every(...)) and target builders invoke.agent(...) / invoke.tool(...)
3. Operate with AraClient (deploy, run, run_async, events, setup) or standalone ara <command> app.py

​

Basic primitives

• App(...): app identity + defaults (interfaces, runtime_profile) where project_name is DNS-safe ([a-z0-9-])
• @app.agent(...): runnable unit; agent id defaults to function name, and function returns the runtime prompt string
• @app.schedule(...): attach static schedules directly to an agent/tool declaration (cron, at)
• @fastapi_endpoint(...): expose an agent behind a manifest-driven HTTP endpoint (none, header, bearer, hmac)
• @app.tool(...): model-facing function schema + deterministic Python source executed by runtime; id defaults to function name and description uses the function docstring
• schedule + invoke: one schedule shape for static definitions and dynamic creation payloads
• scheduler.create(...): builds automation_create payloads from the same schedule spec
• ara CLI / AraClient: deploy and invoke app agents

​

Recommended pattern

from ara_sdk import App, fastapi_endpoint

app = App("ops-assistant")

@app.tool()
def send_email(to: str, subject: str, body: str) -> dict:
    """Send one email."""
    return {"ok": True, "to": to}

@app.schedule(cron="0 9 * * *", at=["14:30", "2026-04-11T16:45:00Z"])
@app.agent(
    entrypoint=True,
    skills=["send_email", "automation_create", "automation_list", "automation_delete"],
)
def ops_agent(input: dict) -> str:
    """Handle ops requests and automations."""
    message = str(input.get("message") or "")
    return f"Handle this request and use tools when needed: {message}"


@app.schedule(cron="0 * * * *")
@app.tool()
def cleanup_cache(path: str = "/tmp/cache") -> dict:
    return {"ok": True, "path": path}


@app.agent()
@fastapi_endpoint(method="POST", path="/ops/webhook", auth="hmac")
def ops_webhook(input: dict) -> str:
    body = input.get("input") if isinstance(input, dict) else {}
    return f"Validate webhook and process payload: {body}"

​

FAQ

​

Runtime auth model

• Control plane calls (/apps/*) use:
  1. ARA_API_KEY
  2. legacy ARA_ACCESS_TOKEN
  3. credentials from ara auth login (~/.ara/credentials.json)
• Runtime invoke calls (/v1/apps/{app_id}/run, /v1/apps/{app_id}/events) use runtime key and/or app header key auth
• FastAPI endpoint calls (/v1/apps/{app_id}/endpoints/{endpoint_label}) use per-endpoint auth (none|header|bearer|hmac)
• deploy mints and returns a runtime_key; export it as ARA_RUNTIME_KEY (or pass --runtime-key)
• setup-auth mints and returns an app_header_key; export it as ARA_APP_HEADER_KEY (or pass --app-header-key)
• ara start, ara status, and ara stop are global aliases for ara runtime session start|status|stop
• ara auth logout clears stored CLI auth credentials
• Local secret declarations are synced on deploy via /apps/{app_id}/secrets
• Connector inheritance for app-runtime turns is isolated by default (interfaces.inherit_owner_tools=false)

​

Where to go next