Integrate Team Agents with your own systems

A Team Agent is the bridge between prompts your team approved in AirPrompter and the application that actually runs them. AirPrompter keeps the history, the reviews, and the decision about what an environment may run. Your system pulls a signed release, verifies it, keeps a local copy, calls your own model with your own keys, and reports content-free counters back. Nothing in AirPrompter opens a connection to you, reads your end users’ text, or makes a release live on a host you have locked.

What an integration is

An integration is a runtime you own that does four things:

1. Pulls the release promoted to one environment (dev, staging, or prod) using an Agent key, or receives that release through a store you control.
2. Verifies it against a root public key you pinned when you set the runtime up, then keeps it encrypted on disk so a restart, or a network outage, keeps serving the last good release.
3. Renders a prompt by its key in code (the tag) with your variables and calls the model your release pinned, with your provider credentials.
4. Reports content-free measurements, and, optionally, feedback signals tied to a run reference.

AirPrompter never sits on your request path. render() is a local, in-memory operation; with the network gone, the last verified release keeps serving until its lease policy says otherwise.

The library map

Every public package lives in the open-source airprompter/airprompter-agent-sdk repository (BSD-3-Clause). Install what you use; the packages share one version and one protocol version.

You need to	TypeScript (npm)	Python	Notes
Run prompts in a long-lived process with one call	@airprompter/agent-sdk (AirPrompterAgent)	airprompter-agent (AirPrompterAgent)	The facade; re-exports everything below. Start here.
Verify manifests, open a bundle, render a template, with no I/O	@airprompter/agent-core	airprompter-agent-core	Pure protocol code; the CI test kit lives under its testing entry point.
Pull and verify releases in a job, or hold them in the encrypted store	@airprompter/agent-sync (pullBundle, SlotStore)	airprompter-agent-sync (pull_bundle)	The fleet puller uses this.
Render and attribute over a release you already hold; wrap a provider client	@airprompter/agent-runtime (ReleaseResolver, wrapClient, aiSdkMiddleware)	airprompter-agent-runtime (ReleaseResolver, wrap_client)	No store, no network of its own.
Write the content-free spool yourself, or ship it	@airprompter/agent-telemetry (SpoolWriter, SpoolUploader)	airprompter-agent-telemetry	Any process, in any language, can write the spool format.
Send the counters to your OpenTelemetry collector instead of AirPrompter	@airprompter/otel-bridge (otlpUploadSink)	airprompter_agent_telemetry.otel (OtlpUploadSink)	Optional; no Agent key needed on that path.
Operate hosts from a shell or a service manager	airprompter CLI and airprompterd	the same binaries	Signed single-file executables; Python users never install Node.

Current published versions: the npm packages are at 0.2.9 and speak protocol 0.3.3. The Python distributions exist at the same version in the repository and are coming to PyPI; until then, install from a built wheel. See Python.

The four shapes

1. Resident SDK

The default. AirPrompterAgent.start(...) reads the local store before any network call, syncs in the background (checking a few hundred bytes at a CDN edge first, so idle instances cost almost nothing), and serves every render from memory. Available in TypeScript and Python. A serverless variant (on_invoke sync mode) syncs around each invocation and flushes its counters before the handler returns.

2. Fleet pattern with your own database

When you would rather not put an Agent key on every host, one puller job holds it. It pulls, verifies, seals the release to a distribution key you generated, and writes a row per generation into your database (SQLite, Postgres, DynamoDB; the shape is the point, not the engine). Every runtime holds only the distribution private key, boots from the newest row, and hands a newer row to applyBundle(). Details in The fleet pattern.

3. Hosted environment through compatible endpoints

An environment can run hosted: AirPrompter runs the promoted version on the organization’s model access and meters it. You call it with the OpenAI or Anthropic SDK you already use by changing the base URL and the key, and naming the prompt as the model (model: "slot:support.triage"). The release owns the system prompt and the inference settings; the call cannot add instructions, add tools, or pick a model. Details in Hosted environments.

4. Offline and air-gapped

For hosts with no route to AirPrompter, the environment’s Settings offers Download update file: the promoted release sealed to your registered distribution key. airprompter verify and airprompter apply run the same verification chain a runtime runs; airprompter export-telemetry packs the counters into one file to carry back. Details in The CLI and the daemon.

How to pick

Situation	Shape	Why
One service, or a few, each able to reach AirPrompter over outbound HTTPS	Resident SDK	Least moving parts; the SDK owns sync, store, upload, and health.
Many hosts, or a policy that keeps Agent keys off application hosts	Fleet pattern	One key in one job; runtimes read rows and hold only a distribution key.
Several processes on one host that would otherwise each pull and each hold a store	Resident SDK attached to airprompterd	One sync loop and one store per host; processes attach over a local socket and need no key.
You do not want to run models yourself, and the prompt takes one user turn	Hosted environment	The provider SDK you already use, unchanged at the call site.
Hosts that never reach the internet	Offline	A file in, a file out; the verification chain is identical.
Prompts already instrumented by your own code, in any language	Write the spool directly	The spool format is a published contract that airprompterd uploads.

You can mix shapes per environment: dev on a resident SDK against a workstation, prod on the fleet pattern with change control. The prompt’s key in code never changes between them.

Before you integrate

You need:

• a workspace with Team Agents and at least one agent whose board has a prompt promoted to the environment you will run;
• the agent’s organization id and agent id (shown on the agent’s Settings tab);
• an Agent key for that environment from the agent’s Settings → Keys, stored in a secret manager and exposed to the runtime as an environment variable (AIRPROMPTER_AGENT_KEY); it is never passed on a command line and never printed;
• the root public key for the AirPrompter deployment you talk to (the public service is prod), shown on the same Settings tab and pinned in your project as a JSON Web Key file; and
• a provider credential for the model your release pins, handled by your own secret management.

An Agent key is read-only for governance: it can fetch its own agent’s release for its own environment and write telemetry under its own prefix. It cannot seal, promote, unlock, or countersign anything.

Make the smallest proof

1. Promote one prompt to dev from the agent’s board.
2. Mint a dev Agent key and export it as AIRPROMPTER_AGENT_KEY in a terminal you will close afterwards.
3. Run the TypeScript or Python quick start against dev with a fresh state directory.
4. Render the prompt once and print only its versionId, arm, and model, never its text.
5. Open the agent’s Fleet tab and confirm your instance appears with the generation you just served.

Expected result: the runtime reports the promoted generation, the Fleet tab shows one instance on it, and the prompt renders with the release’s pinned model. From here, the same code serves your real work day-to-day: change the prompt in AirPrompter, promote, and watch the generation move without a deploy.

Troubleshooting

start() fails with no_verified_release

The message names the cause. A 404 means no release is promoted to that environment yet; promote one from the board. A 401 is the key; a 403 carries the server’s code (commonly a key bound to another agent or environment). A transport failure carries the base URL it tried.

The runtime serves, but the Fleet tab shows nothing

Heartbeats go out every five minutes by default (heartbeatSeconds). Check ap.status().heartbeat.lastRefusal for a refused heartbeat; a refusal is logged as heartbeat_refused with the server’s message.

Renders refuse with disabled

Someone froze the environment, the agent, or a slot from the console. The runtime honours a freeze from any manifest whose signature verifies, even one left staged. Lift the freeze; the next sync clears it.

Completion checklist

• You know which of the four shapes each environment will use.
• The Agent key reaches the runtime only through the environment.
• The root public key is pinned in your project, not fetched at runtime from an unverified place.
• Your runtime appears on the Fleet tab on the promoted generation.
• Nothing you print or log is prompt text or model output.

Next steps

Build the resident shape in TypeScript or Python, or plan a fleet with your own release store. To understand what leaves your host, read Telemetry first.