Skip to main content

Quick Start

Get up and running with the AdaL Agent SDK in minutes.

Installation​

pip install git+https://github.com/SylphAI-Inc/adal-sdk.git

For local development:

git clone https://github.com/SylphAI-Inc/adal-sdk.git
cd adal-sdk
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Prerequisites​

Before using the SDK, ensure:

  1. AdaL CLI is installed — run adal --version to verify. If not installed, see the CLI Quickstart
  2. Authentication is complete — see below
  3. Python 3.10+ — run python --version to verify

Authentication​

The SDK supports two authentication methods:

Run adal once and complete browser sign-in. AdaL stores your credentials at ~/.adal/adal_oauth_creds.json. The SDK picks these up automatically — no extra configuration needed:

options = AdalAgentOptions(workspace=".")

Option 2: Explicit token (headless / CI)​

Pass a JWT directly via auth_token to bypass cached credentials. Copy the value of the access_token key from ~/.adal/adal_oauth_creds.json:

cat ~/.adal/adal_oauth_creds.json | python3 -c "import json,sys; print(json.load(sys.stdin)['access_token'])"
options = AdalAgentOptions(
    workspace=".",
    auth_token="<paste access_token here>",
)

This is useful for CI/CD pipelines or environments where running adal interactively isn't possible.

Your First Query​

The simplest way to use the SDK is the query() function:

import asyncio
from adal_agent_sdk import AdalAgentOptions, query


async def main():
    async for event in query(
        prompt="Summarize this workspace in three bullets.",
        options=AdalAgentOptions(
            workspace=".",
            permission_mode="yolo",  # auto-approve all tools
        ),
    ):
        event_type = event.get("type")
        if event_type == "assistant.message.completed":
            # The complete assistant reply — this is the answer you display.
            # An agent may emit this more than once per turn; concatenate them.
            print(event.get("message", {}).get("content", ""))
        elif event_type == "command.completed":
            print("✓ Done")
        elif event_type == "command.failed":
            print(f"✗ {event.get('error', {}).get('message', 'unknown error')}")


asyncio.run(main())

Save this as my_first_query.py and run:

python my_first_query.py

Understanding Events​

The SDK streams events as dictionaries. Parse each event and switch on its type field. Key event types:

Event TypeDescription
assistant.message.completedA complete assistant reply — the answer you display. May occur more than once per turn (e.g. text before and after a tool call); concatenate them.
thought.deltaAn incremental chunk of the agent's reasoning/thinking. Chunks sharing a thoughtId concatenate.
tool.startedThe agent invoked a tool (name, args, toolCallId).
tool.completedA tool call finished (status, result, toolCallId matching tool.started).
command.progressA transient human-readable status line (e.g. "Syncing workspace"). Safe to show as ephemeral progress.
ui.message.appendedA surfaced notice from the runtime (message.level is info / warn / error).
command.completedThe turn finished successfully. The stream closes next.
command.failedThe turn errored (a mid-stream failure, since HTTP already returned 200).

For a minimal integration you only need assistant.message.completed (the answer) and command.failed (errors) — the rest drive live UI.

Choosing a Permission Mode​

ModeBehavior
"yolo"Auto-approve all tool calls (best for scripts/CI)
"acceptEdits"Auto-approve reads, prompt for writes
"default"Prompt for all tool calls via can_use_tool callback

For automation, use "yolo". For controlled execution, use "default" with a permission callback. See also: Built-in Tools for the full list of tool groups and permission modes.

Tool Permissions​

Control which tools the agent can use:

Enabling / Disabling Tools​

Use enabled_default_tools (positive set) or disabled_default_tools (negative set) to control which built-in tools the agent can see and call. Disabled tools are absent from the agent's prompt entirely.

# Positive set: agent can ONLY use these tools
options = AdalAgentOptions(
    workspace=".",
    enabled_default_tools=["Read", "Search", "Bash"],
    permission_mode="yolo",
)

# Negative set: disable specific tools
options = AdalAgentOptions(
    workspace=".",
    disabled_default_tools=["Web", "Video", "Image"],  # no web access or media generation
    permission_mode="yolo",
)

Accepts tool groups ("Bash", "Edit", "Read", "Search", "Web", "Image", "Video", "Consult") or exact tool names ("web_search"). Scope is built-in core tools only; custom tools are unaffected.

For the full tool group reference and CLI equivalents (--enabled-default-tools / --disabled-default-tools), see the Built-in Tools guide.

Selecting a Model​

Specify a model at startup:

options = AdalAgentOptions(
    workspace=".",
    model="claude-sonnet-4-6",
    permission_mode="yolo",
)

See the models list for available model slugs.

Custom System Prompt​

Override the default agent system prompt with your own instructions from a file:

options = AdalAgentOptions(
    workspace=".",
    prompt_file="./my_prompt.txt",
    permission_mode="yolo",
)

The file contents replace AdaL's built-in role prompt, letting you tailor the agent's persona, constraints, or focus area for your use case. This is equivalent to the --prompt-file flag in the CLI. For the full guide on AGENTS.md and --prompt-file, see Custom System Prompt.

Custom Runtime Path​

If AdaL is installed in a non-standard location:

options = AdalAgentOptions(
    workspace=".",
    runtime_path="/opt/adal/bin/adal",
)

Or set the environment variable:

export ADAL_RUNTIME_PATH=/opt/adal/bin/adal

What's Next​