Skip to main content

Andon SDK and CLI (andon-ai)

Andon is a Python SDK for building durable, document-centric workflows with typed steps, LLM agents, human review, and integrations. Authors define the workflow; the Andon platform handles execution, checkpointing, files, and operations.

Installing andon-ai provides the andon command and the andon_dsl Python package. Python 3.13 or newer and uv are required.

Create a workspace

Start in an empty directory and sign in to your organization:

mkdir claims-workflow
cd claims-workflow
uvx andon-ai auth login
uvx andon-ai init
uv sync

andon workspace init writes the platform's starter workspace: andon.toml, a deployable andon/ package, and a sample workflow and test. It adds local project configuration and preserves files that already exist, so an empty directory is the supported starting point.

The generated AGENTS.md routes coding agents to the authoring contract and tool catalog that match the installed SDK.

Build an email workflow

This workflow reads unread Gmail messages, summarizes them with an agent, and emails the digest. Save it as andon/workflows/inbox.py:

from dataclasses import dataclass

from andon_dsl.agents import Agent, StepContext
from andon_dsl.integrations import ConnectionRef, EmailFilter, EmailMessage, Gmail
from andon_dsl.workflows import map, step, workflow


@dataclass
class InboxInput:
    recipient: str
    limit: int = 10


@dataclass
class EmailSummary:
    sender: str
    subject: str
    summary: str


GMAIL = ConnectionRef(Gmail, "gmail")


summarizer = Agent(
    model_family="small",
    input_type=EmailMessage,
    output_type=EmailSummary,
    system_instructions="Summarize inbound email clearly and concisely.",
)


@step(connections=[GMAIL])
async def read_inbox(ctx: StepContext, input: InboxInput) -> list[EmailMessage]:
    gmail = await ctx.connect(GMAIL)
    return await gmail.list_messages(
        filter=EmailFilter(is_unread=True),
        limit=input.limit,
    )


@step
async def summarize(message: EmailMessage) -> EmailSummary:
    return await summarizer(
        "Summarize this email from {{sender}}.\n"
        "Subject: {{subject}}\n\n"
        "{{body_text}}",
        inputs=message,
    )


@step(connections=[GMAIL])
async def send_digest(
    ctx: StepContext,
    recipient: str,
    summaries: list[EmailSummary],
) -> str:
    gmail = await ctx.connect(GMAIL)
    body = "\n\n".join(
        f"{item.subject} — {item.sender}\n{item.summary}" for item in summaries
    )
    return await gmail.send(
        to=[recipient],
        subject="Andon inbox digest",
        body=body or "No unread messages.",
    )


@workflow()
def process_inbox(input: InboxInput) -> str:
    messages = read_inbox(input)
    summaries = map(summarize, messages)
    return send_digest(input.recipient, summaries)

Declare the workflow in andon.toml:

[[workflows]]
name = "process_inbox"
path = "andon/workflows/inbox.py"

ConnectionRef pairs the expected integration protocol with the configured organization connection name. Reuse the same ref in the decorator grant and ctx.connect(...) so the name and return type have one source of truth.

Core concepts

  • Workflows are declarative graphs of steps and control-flow primitives. Their bodies are compiled from source during deployment and do not run as ordinary Python during workflow execution.
  • Steps are typed Python functions and the durability boundary. Successful results are checkpointed; external side effects should be safe to repeat if an interrupted attempt runs again.
  • Agents are typed LLM-powered components declared at module scope and awaited inside steps. Runtime prompts are Handlebars templates over the agent's typed inputs.
  • Tools and toolsets give agents explicitly selected capabilities. Andon provides platform tools and curated toolsets, and authors can define their own model-callable functions with @tool.
  • Connections provide typed access to organization-configured email through the Gmail protocol without exposing credentials to workflow code.
  • FileRef values represent uploaded files and generated artifacts. Keep documents and large intermediate outputs behind FileRef rather than passing their bytes or full text through step results.

Workflow bodies use primitives such as map, parallel, branch, loop, wait_for_event, wait_for_review, sleep, and run_workflow. Put ordinary Python branching, iteration, parsing, and integration glue inside steps.

Tools and toolsets

Platform tools and curated toolsets are imported from andon_dsl.tools and opted into an agent through tools=[...]. Authors can combine them with their own @tool functions:

from andon_dsl.agents import Agent
from andon_dsl.tools import tool
from andon_dsl.tools.toolsets import document_analysis


@tool
def normalize_vendor_name(name: str) -> str:
    """Return a normalized vendor name for matching."""
    return " ".join(name.lower().split())


analyst = Agent(
    tools=[*document_analysis.tools, normalize_vendor_name],
)

Find and inspect tools from the installed SDK without signing in:

uv run andon platform-tools list --offline --search document
uv run andon platform-tools show parse_document --offline

Authenticate, synchronize, deploy, and run

Authenticate in the browser. You confirm the organization before Andon creates a 90-day installation credential. The credential lives in the operating system's secure store; only nonsecret profile metadata is written to disk:

andon auth login
andon auth status
andon platform-tools list --search document
andon platform-tools show parse_document --json

andon auth login --with-api-key imports a key created in Settings from a no-echo prompt or stdin. auth list, auth use, and auth logout manage organization-bound profiles. Browser credentials are revoked on logout by default. auth status shows stored device and expiry metadata only when the selected profile supplies the authenticated credential.

ANDON_API_KEY remains the noninteractive headless and CI override. The CLI uses https://app.andonai.com/ by default; --profile selects an organization and --api-url targets another environment without sending a stored credential to a different origin. --no-input and ANDON_NON_INTERACTIVE=1 prohibit prompts and browser launches; JSON output also implies no-input.

Pull an existing workspace, or start a new draft with andon workspace init.

uv run andon workspace pull
uv run andon workspace status
uv run andon workspace push --message "Save review changes"
uv run andon workspace validate --revision <revision>
uv run andon deployments create --revision <revision>
uv run andon runs start process_inbox \
  --deployment <deployment-id> \
  --input '{"recipient":"ops@example.com","limit":10}'
uv run andon runs watch <run-id>
uv run andon runs show <run-id>

If both sides edited a file, use andon workspace pull --keep-local to keep your version and take the other incoming changes. After testing the deployment, read andon deployments list --active and review its diff against the tested version. Activate the tested ID with andon deployments activate <deployment-id> --expected-active-deployment <active-id>. For first activation, omit the flag.

If an inspectable domain mutation response is lost, the CLI reports ambiguous_outcome and exact inspection commands. It never automatically resubmits the mutation. Inspect the current workspace, deployment, run, or event state and create a fresh plan before another write. Input-file upload response loss reports an ordinary retryable network_error because the run does not exist yet.

andon run starts a deployed workflow. Local paths supplied at typed FileRef input positions are uploaded before run creation; andon files upload returns a reusable ref instead. andon runs show <run-id> summarizes step status and errors; add its invocation ID to inspect recorded input/output, error and artifact refs, or page through map/loop children. Inspection shows which complete values are available to download. andon runs download <run-id> <invocation-id> [destination] saves the complete recorded output as JSON; add --value input for the input. andon files download saves any andon:// output locally. Both verify the server's digest and refuse to replace an existing file without --overwrite.

Use - as the destination for verified raw bytes on stdout, with plain-text diagnostics on stderr; for example, andon runs download <run-id> <invocation-id> - | jq '.jobs | length'. This raw output applies even with --json.

Authoring reference

Use the references bundled with the installed SDK before editing a workspace:

uv run andon docs list --search workflow
uv run andon docs show authoring

andon docs show authoring opens the task index for the installed SDK. Use the topic IDs from andon docs list to read individual sections. Use andon --help to find a command and append --help to that command for its arguments. The generated andon/AGENTS.md also points coding agents to the installed contract and tool catalog.

Public imports

Package Purpose
andon_dsl.workflows Workflow and step decorators plus control-flow primitives.
andon_dsl.agents Agent declarations, prompt content, the step context, model settings, and usage limits.
andon_dsl.tools User-authored tools and platform tool stubs.
andon_dsl.tools.toolsets Curated tool bundles an agent opts into in one line.
andon_dsl.resources FileRef, document result types, reference data helpers, and schema extensions.
andon_dsl.integrations Typed ConnectionRef bindings, provider protocols, and shared integration types.
andon_dsl.errors Public authoring and execution error types.

Metadata

Release files for andon-ai 0.8.6

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

Source distribution (sdist)

Source distribution for andon-ai 0.8.6
File Size Uploaded Provenance Actions
andon_ai-0.8.6.tar.gz 119.0 kB With provenance Details for andon_ai-0.8.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for andon-ai 0.8.6
File Interpreter ABI Platform Actions
andon_ai-0.8.6-py3-none-any.whl Python 3 none any Details for andon_ai-0.8.6-py3-none-any.whl

Total release size: 254.4 kB

Release files / andon_ai-0.8.6.tar.gz

Download URL andon_ai-0.8.6.tar.gz
Size 119.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a1d1f6602e38783021948eebe39150062e4a89a3fcb6c1bd749fe2303cea86c5
BLAKE2b-256 checksum
How to use checksums
411e1000b10d1588efefb534a66f54b8d1cce4f52d4b36ea7a6d81ca7d7800ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / andon_ai-0.8.6-py3-none-any.whl

Download URL andon_ai-0.8.6-py3-none-any.whl
Size 135.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e814893a21bb3672a8f5c034b00d9353975af2e6829ccc5298db7086c824e87c
BLAKE2b-256 checksum
How to use checksums
86de66206867f19c144cf335da28992b13e55279334f3748b25f5fdd2d6b55ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for andon-ai 0.8.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for andon_ai-0.8.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page