Ara Python SDK

Ara is a managed platform for building and running long-lived AI agents in the cloud.

The ara-sdk is the Python layer for defining those agents and tools in code using a minimal authoring model. Ara runs the cloud runtime and operations, while the SDK focuses on compact job scripts.

Overview

To program on Ara, you compose workflows with two primitives: ara.Job(...) (system behavior) and @ara.tool (custom callable behavior registered into the app runtime).

Runtime flow:

              +------------------------------+
              | Messages (iMessage/SMS/RCS)  |
              +------------------------------+
                        ^
                        |
                        v
              +----------------------------------------------+
              |         Ara Cloud: 24/7 Agent Runtime        |
              |  - Routes job runs and tool calls            |
              |  - Maintains runtime context and state       |
              |                                              |
              |  +------------------------+                  |
              |  |   Sandbox / Computer   |                  |
              |  | - File system access   |                  |
              |  | - Executes tasks/tools |                  |
              |  +------------------------+                  |
              +-------------------+--------------------------+
                                  ^
                                  |
        +-------------------------+-------------------------+
        |                         |                         |
+------------------------+ +--------------------------+ +-----------------------------+
|   Built-in tools       | |    Connector tools       | |   SDK custom tools          |
| - File browse/edit     | | - Enabled in app.ara.so  | | - Python functions via      |
| - Program execution    | | - External integrations  | |   @ara.tool                 |
+------------------------+ +--------------------------+ +-----------------------------+

Quickstart:

pip install ara-sdk

import ara_sdk as ara

@ara.tool
def utc_now() -> dict:
    from datetime import datetime, timezone
    return {"utc_time": datetime.now(timezone.utc).isoformat()}

ara.Job(
    "hello-hourly-agent",
    system_instructions=(
        "Reply with one short hello message and include UTC time. "
        "If linq_send_message is available and a phone route is paired, "
        "send the same message there once."
    ),
)

Connector tools are enabled by default. To disable connector access for a job, pass allow_connector_tools=False.

Terminology:

Jobs: deployable execution declarations (ara.Job(...)).
Tools: callable capabilities (SDK Python tools, connector tools, built-in runtime tools).
Connectors: external integration toolkits (for example Gmail, Slack, Calendar).
Secrets: runtime credentials consumed by tool code (ara.secret("KEY")).
API keys: control-plane/runtime auth keys used by CLI/SDK (ARA_API_KEY, runtime/app keys).

Non-interactive auth (no ara auth login) is supported via ARA_API_KEY:

ARA_API_KEY="<your_key>" ara deploy app.py
ara run app.py

Runtime CLI commands also use the same auth source (ara auth login credentials or ARA_API_KEY) and do not require separate runtime/API-session tokens:

ara runtime session start
ara runtime tools available --session <session_id>
ara runtime session exec --command "ls -la /root/.ara/workspace"
ara runtime files read --path notes/todo.txt
ara runtime files write --path notes/todo.txt --content "updated from cli"
ara runtime files upload --local ./draft.md --path notes/draft.md
ara runtime files download --path notes/draft.md --output ./draft-copy.md

ara runtime files * targets your active personal session directly, so it does not take a --session flag.

You can self-update the CLI with:

ara --update

The updater prefers global tool-manager installs (uv/pipx) when available, with pip fallback.

Run maintained examples

Examples: github.com/Aradotso/ara-python-sdk/tree/main/examples

FAQ

What is the difference between Ara and `ara-sdk`?

Ara is the managed control/runtime plane (execution, lifecycle, policy, observability), while ara-sdk is the authoring layer for job behavior (tools + instructions). You define Python app logic; Ara handles runtime operations you would otherwise run as custom infrastructure.

Does “24/7 runtime” mean I pay for permanently hot compute?

Not inherently. The runtime is always available as the service boundary, but sandbox/task compute can activate on demand from schedules, events, and API calls. Practical cost and footprint depend on your trigger frequency and runtime policy. Note: today usage is billed under your existing Pro or Ultra subscription.

How should I think about `Job`, `@tool`, and `secret(...)`?

Use Job(...) as the top-level app declaration, @tool for deterministic capability execution, and secret("KEY") when a tool requires credentials. Schedules are configured in app.ara.so UI to avoid code/UI drift.

How do connectors work in `Job(...)`?

Connector tools are enabled by default (allow_connector_tools=True). Set allow_connector_tools=False for strict mode, then explicitly scope allowed connector actions with skills=[ara.connectors.<toolkit>[.<action>]].

Do tools have to return a `dict`?

No. Tool functions can return any JSON-serializable value (dict, list, str, int, float, bool, or None). The runtime serializes structured values to JSON and provides tool output back to the model as text.

How do I handle secrets and environment safely at scale?

Declare required credentials in code with secret("KEY") and provide values through Ara secret sync at deploy time (or pre-provisioned app secrets). Keep all secret values out of source control.

Do I need public endpoints to use Ara?

No. The minimal SDK is job-first; public endpoint wiring is not part of this authoring surface.

Release files for ara-sdk 0.1.58

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ara-sdk 0.1.58
File	Size	Uploaded
ara_sdk-0.1.58.tar.gz	61.0 kB	Apr 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ara-sdk 0.1.58
File	Interpreter	ABI	Platform	Reset
ara_sdk-0.1.58-py3-none-any.whl 51.7 kB Apr 20, 2026	Python 3	none	any	Details

Total release size: 112.7 kB

Release files / ara_sdk-0.1.58.tar.gz

Download URL	ara_sdk-0.1.58.tar.gz
Size	61.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`eb423578ae55b86993532764b6e16d8b9302faba42428157d23f18608e9bec53`
BLAKE2b-256 checksum How to use checksums	`57d17b80d208f9b2f6abecf8b23bf46fe61d3871ba37338eb99211c01bcde188`
Upload date	Apr 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.12`

Release files / ara_sdk-0.1.58-py3-none-any.whl

Download URL	ara_sdk-0.1.58-py3-none-any.whl
Size	51.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8d305fc25c189f1e5f84125c4f6648128a70c6484efea48850b6fe9f3cc93315`
BLAKE2b-256 checksum How to use checksums	`353f913c011cee9538bc9322f1cc84c946d0917d9ea66ec99088b92d0df4097e`
Upload date	Apr 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.12`