Register typed Python functions as governed tools over an outbound-only worker connection.
Workers keep database and API access inside your infrastructure. They make
outbound HTTPS requests to AIR; you do not expose an inbound worker port.
1
Install the SDK
python -m pip install papermap-air
2
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.
3
Issue a worker key
Open Settings, select Issue worker key, and store the value in an
environment variable or secret manager.
Worker credentials are separate from application credentials.
The process registers its manifest and begins long-polling for tool calls.
5
Review the discovered tool
Open Tools. A newly discovered capability starts awaiting approval;
registration never grants permission by itself.
AIR has discovered one worker tool but no agent can call it yet.
6
Inspect and enable it
Select Review. Confirm the source, description, timeout, generated input
schema, and whether it needs write access. Then select Enable tool.
Review the generated schema and explicitly grant write capability only when required.
7
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?”
