Create a private worker

Workers keep database and API access inside your infrastructure. They make outbound HTTPS requests to AIR; you do not expose an inbound worker port.

Install the SDK

python -m pip install papermap-air

Declare a typed tool

Create tools.py:

from air import tool


@tool(timeout=30)
def lookup_order(order_id: str, context: dict) -> dict:
    """Look up an order for the current tenant."""

    tenant_id = context["tenant_id"]
    # Query your system and verify the order belongs to tenant_id.
    return {
        "order_id": order_id,
        "tenant_id": tenant_id,
        "status": "shipped",
    }

Type annotations become the JSON input schema. The first docstring line is the description shown during review. Every tool must return a dictionary.

Issue a worker key

Open Settings, select Issue worker key, and store the value in an environment variable or secret manager.

AIR settings showing separate app and worker key controls — Worker credentials are separate from application credentials.

Start the worker

export AIR_BASE_URL="https://dev.airapi.papermap.ai"
export AIR_WORKER_KEY="<your-worker-key>"
export AIR_WORKER_ENV="staging"

air worker start --module tools

The process registers its manifest and begins long-polling for tool calls.

Review the discovered tool

Open Tools. A newly discovered capability starts awaiting approval; registration never grants permission by itself.

AIR Tools screen showing lookup_order awaiting approval — AIR has discovered one worker tool but no agent can call it yet.

Inspect and enable it

Select Review. Confirm the source, description, timeout, generated input schema, and whether it needs write access. Then select Enable tool.

AIR tool review dialog showing lookup_order schema and read-only approval — Review the generated schema and explicitly grant write capability only when required.

Allow it on an agent version

Create a new agent version, open Advanced — fallback models, tools, and limits, add lookup_order, test the version, and activate it. Enabling a project tool does not automatically add it to existing agent versions.

Registration answers “what can this worker do?” Tool approval answers “does this project trust it?” The agent version answers “may this agent call it?”

Start here

Build agents and apps

Connect private tools

Operate safely

SDK reference

Create a private worker

Install the SDK

Declare a typed tool

Issue a worker key

Start the worker

Review the discovered tool

Inspect and enable it

Allow it on an agent version