Python SDK

The PyPI distribution is papermap-air; the Python import is air. Python 3.10 or newer is required and the SDK is async-native.

python -m pip install papermap-air

`AirClient`

AirClient(base_url: str, api_key: str)

Use it as an async context manager or call await client.aclose() explicitly.

`client.runs.create()`

Creates a run. agent_id is required. model_id, input, context, and webhook_url are optional. Returns a Run.

`client.runs.get(run_id)`

Returns the latest state of a run.

`client.runs.wait(run_id, timeout=60, poll_interval=0.2)`

Polls until succeeded, failed, or cancelled. Raises RunTimeoutError when the local timeout is reached.

`client.runs.stream(run_id, *, after_seq=0, max_retries=3, retry_delay=0.5)`

Returns an async iterator of RunEvent objects. It emits existing events after after_seq, continues with live events, and stops after a terminal run_succeeded, run_failed, or run_cancelled event. The SDK reconnects after a temporary stream failure and resumes after the last sequence number it received. max_retries controls the number of reconnect attempts and retry_delay controls the delay between them.

text = ""
async for event in client.runs.stream(run.id):
    if event.output_delta is not None:
        text += event.output_delta
    elif event.type == "model_output_reset":
        text = ""

`client.runs.cancel(run_id)`

Requests cancellation and returns the server response dictionary.

`Run`

Field	Type	Meaning
`id`	`str`	Run identifier.
`status`	`str`	Current lifecycle status.
`output`	`dict \| None`	Validated schema object, or `{ "text": "..." }` for a schema-less agent.
`error`	`str \| None`	Failure detail when available.
`cost_usd`	`str`	Recorded cost as a decimal string.
`raw`	`dict`	Complete server response.

`RunEvent`

Field	Type	Meaning
`seq`	`int`	Increasing sequence number within the run.
`type`	`str`	Event type, such as `model_output_delta` or `run_succeeded`.
`data`	`dict`	Event-specific payload.
`created_at`	`str \| None`	Server timestamp when available.
`output_delta`	`str \| None`	Convenience property containing text for `model_output_delta` events.

When type is model_output_reset, discard any partial model text already rendered. This event means AIR started another model attempt after a retry or fallback. Terminal run events end the iterator.

`@tool`

from air import tool


@tool(name="lookup_order", timeout=30)
def lookup_order(order_id: str, context: dict) -> dict:
    """Look up one order."""

    return {"order_id": order_id}

The decorator derives a JSON schema from type annotations. Synchronous tools run in a thread; async tools are awaited. A context parameter receives the run context. Every tool must return a dictionary. Use a separate ToolRegistry when you want explicit isolation instead of the process-wide default registry.

`Worker`

Worker(
    base_url: str,
    worker_key: str,
    *,
    registry: ToolRegistry | None = None,
    environment: str = "default",
)

Important methods are start(), poll_once(), heartbeat(), run(), mount_mcp(), and aclose().

Errors

All SDK errors inherit from AirError:

AirProtocolError for rejected or unexpected HTTP responses
RunTimeoutError when a local wait deadline expires
ToolDefinitionError for invalid or duplicate tool definitions
ToolResultError when a tool does not return a dictionary
McpError for MCP transport or protocol failures

Start here

Build agents and apps

Connect private tools

Operate safely

SDK reference

`AirClient`

`client.runs.create()`

`client.runs.get(run_id)`

`client.runs.wait(run_id, timeout=60, poll_interval=0.2)`

`client.runs.stream(run_id, *, after_seq=0, max_retries=3, retry_delay=0.5)`

`client.runs.cancel(run_id)`

`Run`

`RunEvent`

`@tool`

`Worker`

Errors

​AirClient

​client.runs.create()

​client.runs.get(run_id)

​client.runs.wait(run_id, timeout=60, poll_interval=0.2)

​client.runs.stream(run_id, *, after_seq=0, max_retries=3, retry_delay=0.5)

​client.runs.cancel(run_id)

​Run

​RunEvent

​@tool

​Worker

​Errors

`AirClient`

`client.runs.create()`

`client.runs.get(run_id)`

`client.runs.wait(run_id, timeout=60, poll_interval=0.2)`

`client.runs.stream(run_id, *, after_seq=0, max_retries=3, retry_delay=0.5)`

`client.runs.cancel(run_id)`

`Run`

`RunEvent`

`@tool`

`Worker`

Errors