> ## Documentation Index
> Fetch the complete documentation index at: https://docs.papermap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How AIR works

> Understand projects, agents, runs, workers, tools, and the durable execution loop.

AIR separates hosted orchestration from private tool execution. The hosted
runtime owns the durable agent loop; your worker owns access to your systems.

## Core objects

| Object        | Purpose                                                                   |
| ------------- | ------------------------------------------------------------------------- |
| Project       | Security and configuration boundary for agents, tools, keys, and members. |
| Prompt        | Reusable, versioned instructions.                                         |
| Agent         | Stable API identity used to create runs.                                  |
| Agent version | Immutable prompt, model, allowed tools, fallbacks, and limits.            |
| Run           | One durable execution of an active agent version.                         |
| Tool          | Reviewed capability an agent may request.                                 |
| Worker        | Outbound process that registers and executes private tools.               |

## Run lifecycle

<Steps>
  <Step title="Your application creates a run">
    `AirClient` sends the agent API ID, input, trusted context, and optional
    webhook settings using an app key.
  </Step>

  <Step title="AIR snapshots the active configuration">
    The run is bound to one agent version so later configuration changes cannot
    alter an execution already in progress.
  </Step>

  <Step title="AIR calls the model">
    Output chunks are recorded as durable events and published live. Each
    request, response, token count, latency, and cost is recorded in the trace.
  </Step>

  <Step title="AIR queues approved tool calls">
    If the model requests an allowed tool, the run waits while an outbound
    worker claims the task.
  </Step>

  <Step title="AIR resumes durably">
    The tool result enters the transcript and the run continues until it
    succeeds, fails, or is cancelled.
  </Step>
</Steps>

## Live output and replay

The console and Python SDK consume the same ordered run-event stream. AIR saves
each event in Postgres before publishing it through Redis:

* Redis delivers new events immediately to connected subscribers.
* Postgres remains the source of truth and replays events a subscriber missed.
* Each sequence number lets a reconnecting client continue without losing or
  duplicating output.

Redis is the live delivery path, not the permanent record. A console or SDK
client can therefore join after a run starts, reconnect after a network break,
or inspect a completed run and still receive the recorded event sequence.

<Frame caption="The trace makes model behavior, cost, and the immutable configuration auditable.">
  <img src="https://mintcdn.com/papermap/6FYSF5TTvsKzeVI6/air/images/run-trace.png?fit=max&auto=format&n=6FYSF5TTvsKzeVI6&q=85&s=e2721f2663b9d054aecacec88f394418" alt="AIR run trace with model response, usage, cost, and configuration snapshot" width="2880" height="1800" data-path="air/images/run-trace.png" />
</Frame>

## Why tools start pending

A worker discovers capability; it does not grant policy. Newly registered tools
start **awaiting approval** until a project owner reviews their description,
schema, timeout, source, and write capability. An agent version can only call
tools explicitly included in that version.