Fleet Agents

You define an agent once at the org level and deploy it across your customer base. Each workspace runs its own isolated copy against its own data and credentials; you improve the definition centrally and the fleet follows.

Publish to the org registry

Two paths into the registry, same result:

Promote a workspace agent. Build and test the agent in your primary workspace like any other — the Agents guide covers that loop — then snapshot its active version into the registry:

curl -X POST https://api.levainlabs.com/api/v1/org/agents/support-triage/promote \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'$STAGING_WS_ID'",
    "agent_id": "'$AGENT_ID'"
  }'

The agent keeps living in its workspace; promoting again publishes the next version. This is the loop most teams settle into: iterate in staging, promote to the fleet when it holds up. The same action is available in the dashboard under Organization settings → Agents.

Upload a source archive. If your agent definition lives in your own repository and CI, POST /api/v1/org/agents/{slug}/versions takes a gzipped tar of the recipe package directly.

Slugs are global across Levain, so pick one specific to you. Publishing requires a plan with agent building; see Plans & Billing.

Adopt into a customer workspace

Adoption instantiates the org agent in one workspace:

curl -X POST https://api.levainlabs.com/api/v1/managed-agents/support-triage/adopt \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $CUSTOMER_WORKSPACE_ID"

Fold this into your provisioning flow: create the workspace, push credentials, adopt the agent — three calls and the customer is live. Adopted agents follow the registry's active version, so publishing a new version rolls out to every adopting workspace; there's no per-workspace upgrade step.

Run it

From here the agent behaves like any other agent in the workspace: trigger runs, poll status, stream logs — the Runs guide applies unchanged, with X-Workspace-Id selecting the customer.

curl -X POST https://api.levainlabs.com/api/v1/agents/support-triage/runs \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $CUSTOMER_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Triage the tickets that arrived overnight."}'

Each run executes in the customer workspace's own sandbox, reads that workspace's credentials, and bills to that workspace's usage — see Usage & Billing.

Keep an eye on the fleet

GET /api/v1/org/agents lists your registry with each agent's active version and adoption count. The dashboard's Organization settings section shows the same registry next to the workspace fleet.