Skip to main content
AraRuntimeClient gives you programmatic access to a running Ara session. Send messages through the full agent loop, execute tools directly in the sandbox, and inspect the agent’s capabilities — all from Python or the CLI.

​
Setup

pip install ara-sdk

from ara_sdk import AraRuntimeClient

rt = AraRuntimeClient.from_env()
Required environment:
  • ARA_API_KEY — your user API key (Settings > System > API Key in the Ara app)
  • ARA_API_BASE_URL — optional, defaults to https://api.ara.so

​
Send messages: chat()

Send a message through the full agent loop — the same code path as typing in the Ara UI. The agent picks tools, executes them against the sandbox, and returns the response with a trace of everything it did. 
result = rt.chat(message="Create a Python script that prints hello world")

print(result["text"])       # "I've created the script..."
print(result["tool_calls"]) # [{"name": "write_file", "args": {...}, "result": "..."}]
Returns: 
{
    "text": "final assistant response",
    "tool_calls": [
        {"name": "write_file", "args": {"path": "hello.py", "content": "..."}, "result": "File written."},
    ],
    "reasoning": "..."  # present when the model produces reasoning
}
Parameters:
ParameterTypeDefaultDescription
messagestrrequiredThe message to send
modelstr""Model override (e.g. "openai/gpt-4o")
conversation_idstr""Continue a specific conversation
timeoutint120Request timeout in seconds

​
Run tools: execute_tool()

Run any sandbox tool directly — read files, execute commands, list automations, etc. This bypasses the LLM and calls the tool immediately. 
# Read a file from the sandbox
result = rt.execute_tool(
    session_id="sess-...",
    tool_name="read_file",
    args={"path": "/root/.ara/memory/USER.md"},
)

# Run a shell command
result = rt.execute_tool(
    session_id="sess-...",
    tool_name="exec",
    args={"command": "ls -la /root/.ara/workspace"},
)

# List automations
result = rt.execute_tool(
    session_id="sess-...",
    tool_name="automation_list",
    args={},
)
Available tools: read_file, write_file, edit_file, list_dir, exec, search_files, glob, delete_file, web_search, web_fetch, automation_create, automation_list, automation_update, automation_delete.

​
Inspect state

​
capabilities()

caps = rt.capabilities(session_id="sess-...")
# Returns: session_id, session_type, sandbox_url_present, tools, skills, agents, control

​
skills()

skills = rt.skills(session_id="sess-...")
# Returns: {"session_id": "...", "skills": [...]}

​
tools()

tools = rt.tools(session_id="sess-...", kind="builtin")
# kind: "all" | "builtin" | "app" | "connector"
# Returns: {"tools": [{"name": "read_file", ...}, ...]}

​
control_actions()

actions = rt.control_actions(session_id="sess-...")
# Returns: {"actions": [{"id": "list_windows", ...}, ...]}

​
control_call()

Trigger a runtime control action. Requires the app UI to be open (active WebSocket connection). 
result = rt.control_call(
    session_id="sess-...",
    action="list_windows",
    args={},
)

​
CLI

The ara runtime CLI wraps the same methods. Requires ARA_API_KEY in environment. 
# Inspect
ara runtime capabilities --session sess-...
ara runtime skills list --session sess-...
ara runtime tools list --session sess-... --kind builtin

# Execute a tool
ara runtime tools execute --session sess-... --tool exec --arg command="echo hello"

# Control (requires app UI open)
ara runtime control actions --session sess-...
ara runtime control call --session sess-... --action list_windows

​
Practical example: verify agent behavior

Use chat() + execute_tool() to test agent behavior without the UI: 
from ara_sdk import AraRuntimeClient

rt = AraRuntimeClient.from_env()
session_id = "sess-..."  # your active session

# Send a message and check what tools the agent used
result = rt.chat(message="My name is Adi and I prefer dark mode")
print(f"Response: {result['text']}")
for tc in result["tool_calls"]:
    print(f"  Tool: {tc['name']}({tc['args']})")

# Verify the agent saved to memory
user_md = rt.execute_tool(
    session_id=session_id,
    tool_name="read_file",
    args={"path": "/root/.ara/memory/USER.md"},
)
print(f"USER.md: {user_md}")