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 runs start <workflow_key> starts a deployed workflow. Local paths at typed FileRef input positions are uploaded before run creation. andon files upload returns a reusable reference.

Use andon runs show <run_id> for status and failures, then andon invocations show <invocation_id> --run <run_id> for recorded previews. andon nodes list and andon invocations list page through the run's nodes and their executions. Read inputs or results with inputs show or outputs show, or save the complete JSON with their download commands. andon files download saves files by Andon reference. Downloads verify the digest and require --overwrite to replace an existing destination.

Use - as the destination to pipe verified bytes to stdout: andon outputs download --run <run_id> --invocation <invocation_id> - | jq '.jobs | length'. The same pipe works 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.8

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.8
File Size Uploaded Provenance Actions
andon_ai-0.8.8.tar.gz 123.6 kB With provenance Details for andon_ai-0.8.8.tar.gz

Built distribution (wheel)

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

Total release size: 264.4 kB

Release files / andon_ai-0.8.8.tar.gz

Download URL andon_ai-0.8.8.tar.gz
Size 123.6 kB
Tags Source
SHA-256 checksum
How to use checksums
7ad30d96cc457c1c53d4f3455533088978d446a8ce4b0214c87bc0b199f99a89
BLAKE2b-256 checksum
How to use checksums
b5394bac58c2d492281c8f7cd8210be1f63b0f3025b252e5d60829a8afe10dd7
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 18, 2026.

Transparency log

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

Download URL andon_ai-0.8.8-py3-none-any.whl
Size 140.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b7c705849df7a15b2586a0c8f6532b91632197bcfd92264d35b5168e6cbe9a9d
BLAKE2b-256 checksum
How to use checksums
4f6c7b349447f71dee51d5e98f9a9c008bd61e6fb374bddf99e6ccb0340ed69a
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 18, 2026.

Transparency log

Security for andon-ai 0.8.8

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.8.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 18, 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