Skip to main content

aod-sdk

Python SDK for the Agent on Demand HTTP API. Covers every endpoint in docs/openapi.yaml with typed pydantic models, sync and async clients, and a typed SSE event stream.

Install

pip install aod-sdk

Quickstart

Sync

from aod import Client

with Client(base_url="https://aod.example", token="aod_...") as client:
    env = client.environments.create(
        name="prod",
        packages={"apt": ["jq"], "npm": ["typescript"]},
        env_vars={"OPENAI_API_KEY": "sk-..."},
        networking={"type": "limited", "allowed_hosts": ["api.github.com"]},
    )
    agent = client.agents.create(
        name="my-agent",
        model="claude-sonnet-4-5",
        runtime="claude-code",
        system="You are a careful software engineer.",
        environment_id=env.id,
    )
    ack = client.sessions.create(
        agent_id=agent.id,
        prompt="implement the feature in TODO.md",
        resources=[
            {"type": "github_repository", "url": "https://github.com/me/repo"},
        ],
    )
    with client.sessions.stream(ack.id) as events:
        for event in events:
            print(event.type, event.extra)

Async

import asyncio
from aod import AsyncClient

async def main():
    async with AsyncClient(token="aod_...") as client:
        agents = await client.agents.list()
        for agent in agents:
            print(agent.name)

asyncio.run(main())

Configuration

base_url and token can be passed to the constructor or read from the AOD_API_URL and AOD_API_TOKEN environment variables. base_url defaults to http://localhost:8777.

Errors

Non-2xx responses raise a typed subclass of AodHTTPError:

Status Exception When
401/3 AuthError Missing/invalid token
404 NotFoundError Resource missing
409 ConflictError Archived row, terminal session, or stale version
422 ValidationError Server-side pydantic validation failure
429 RateLimitError Per-user concurrent session limit reached (.limit, .active)
5xx ServerError

All share .status_code, .detail, .method, .url.

Optimistic concurrency

agents and environments require the current version on update. A stale version raises ConflictError:

agent = client.agents.get(agent_id)
client.agents.update(agent.id, version=agent.version, name="renamed")

Streaming

client.sessions.stream(session_id, since=None) is a context manager that yields a StreamEvent iterator. Pass since to resume after a specific event id. Event types: start, turn_start, output, stage, exit, error, terminated, stale. Everything except the discriminator (type) and id lands in event.extra.

Pretty-printing agent output

aod.pretty holds optional, runtime-scoped formatters that turn an agent's raw stdout into human-readable display lines. Runtime output formats are not part of the AoD API, so these helpers live under a separate namespace — the core SDK stays runtime-agnostic.

Currently shipped:

Formatter Runtime Input format
aod.pretty.claude.ClaudeFormatter claude-* Claude CLI stream-json lines
from aod import Client
from aod.pretty.claude import ClaudeFormatter

fmt = ClaudeFormatter()
with client.sessions.stream(session_id) as events:
    for event in events:
        for line in fmt.consume(event):  # filters to output/stdout
            print(line)
    for line in fmt.flush():              # drain any unterminated buffer
        print(line)

.consume(event) is the event-oriented entry point. .feed(chunk) and .flush() are available for lower-level integrations that already extracted the stdout bytes themselves.

Development

cd clients/python
uv pip install -e ".[dev]"
pytest
ruff check
mypy

Releases (maintainers)

Published to PyPI via GitHub Actions using Trusted Publishing — no API tokens to manage. Two workflows live in .github/workflows/:

  • sdk-release.yml — fires on GitHub Release creation with tag aod-sdk-v<version>, publishes to pypi.org/p/aod-sdk.
  • sdk-release-test.yml — manual workflow_dispatch, publishes to test.pypi.org/p/aod-sdk for dry-run validation.

One-time setup

  1. Reserve the name on PyPI (and TestPyPI). On both pypi.org and test.pypi.org, add a pending trusted publisher:

    Field Value
    Project name aod-sdk
    Owner ravi-hq
    Repository agent-on-demand
    Workflow sdk-release.yml (PyPI) / sdk-release-test.yml (TestPyPI)
    Environment pypi / testpypi
  2. (Recommended) Create protected GitHub environments. In Settings → Environments, create pypi with required reviewers, and testpypi with no protections.

Cutting a release

  1. Bump the version in both clients/python/pyproject.toml and clients/python/src/aod/__init__.py (the workflow verifies the pyproject value matches the tag). PR + merge to main.

  2. (Recommended) Run sdk-release-test.yml against main and pip install -i https://test.pypi.org/simple/ aod-sdk==<version> in a throwaway venv to confirm the wheel installs and imports cleanly.

  3. Tag and create a GitHub Release:

    gh release create aod-sdk-v0.2.0 \
      --title "aod-sdk v0.2.0" \
      --notes "..." \
      --target main
    

    sdk-release.yml fires on published, verifies the tag matches pyproject.toml, runs the tests, builds sdist + wheel, and uploads to PyPI.

Metadata

Release files for aod-sdk 0.1.0

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

Source distribution (sdist)

Source distribution for aod-sdk 0.1.0
File Size Uploaded Provenance Actions
aod_sdk-0.1.0.tar.gz 67.5 kB With provenance Details for aod_sdk-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aod-sdk 0.1.0
File Interpreter ABI Platform Actions
aod_sdk-0.1.0-py3-none-any.whl Python 3 none any Details for aod_sdk-0.1.0-py3-none-any.whl

Total release size: 87.3 kB

Release files / aod_sdk-0.1.0.tar.gz

Download URL aod_sdk-0.1.0.tar.gz
Size 67.5 kB
Tags Source
SHA-256 checksum
How to use checksums
685ca70335f81ba100b4420d29a8970012fdd600bb753ca9cedb3b2977f9eb64
BLAKE2b-256 checksum
How to use checksums
b8a4a23232030e549ff06b4a6d7dc8c7d1e82367cb528b5c9aaeb033b805c967
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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 Apr 22, 2026.

Transparency log

Release files / aod_sdk-0.1.0-py3-none-any.whl

Download URL aod_sdk-0.1.0-py3-none-any.whl
Size 19.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bdbd77f1e9678c845e66a235118ea835b58e3b756d4a2bc94ac04f9583d576f1
BLAKE2b-256 checksum
How to use checksums
11bf1dc63e61764126d35d90425170a3931bccf1a62b40f0f04a2334d5c5976a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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 Apr 22, 2026.

Transparency log

Security for aod-sdk 0.1.0

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 aod_sdk-0.1.0.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 Apr 22, 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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