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 registryCopy Anchor Link

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 from the workspace agent's Config tab (Promote to organization).

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.

Either path validates the recipe — a package that fails validation is refused with 422 — and derives the agent's contract from it: the input schema from the graph.tla state (what GET /api/v1/agents/{id}/state-schema reports once adopted) and the integration requirements from its @mcp_servers names. Integrations the recipe names are required; provider-named platform servers such as slack are optional.

Adopt into a customer workspaceCopy Anchor Link

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"

Adoption links the workspace integrations the recipe names, matched by display name or provider, and is refused with 409 naming what's missing while a required one isn't connected — so push credentials before you adopt. GET /api/v1/managed-agents shows each agent's required_integrations and, for the selected workspace, missing_integrations.

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. When you want a workspace to move on your schedule instead, pin it — see Stage a rollout.

Run itCopy Anchor Link

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."}'

A bare prompt is routed into the recipe's primary input field; pass initial_state instead to set fields explicitly, validated against the derived schema. 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.

For an agent your organization published, an organization-scoped key gets the full execution timeline: GET /api/v1/runs/{run_id}/log, GET /api/v1/runs/{run_id}/log/events, and GET /api/v1/runs/{run_id}/record all return unredacted. A workspace-scoped key stays redacted even for runs in its own workspace — those surfaces are org-console-only.

For an agent your users chat with, flag it interactive in that workspace so its machine stays warm between turns instead of being released after the idle window:

curl -X PATCH https://api.levainlabs.com/api/v1/agents/support-triage \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $CUSTOMER_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"config": {"interactive": true, "keep_warm_minutes": 60}}'

config replaces the agent's whole config, so include any other keys you rely on. Follow-ups then skip machine start-up (a free worker is still needed), and each run's latency breakdown shows where the remaining time goes. Held time is billed to that workspace by the hour, bounded by keep_warm_minutes, three conversations per agent, and the workspace's credit and spend cap. See Run Lifecycle and Plans & Billing.

Stage a rollout, roll it backCopy Anchor Link

A pin holds one workspace to one version. A pinned workspace keeps running its pinned version no matter what you publish or activate; everyone else follows the registry's active version. Pins apply to new runs and sessions — work already in flight finishes on the version it started with.

curl -X PUT https://api.levainlabs.com/api/v1/org/agents/support-triage/pins/$CUSTOMER_WORKSPACE_ID \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": 4}'

To ship a new version to one customer before the fleet:

1. Freeze the fleet. Pin each adopting workspace to the current version (PUT /api/v1/org/agents/{slug}/pins/{workspace_id}).
2. Publish the new version. It becomes the active version, but every pinned workspace stays put.
3. Release the first customer. Clear that workspace's pin (DELETE /api/v1/org/agents/{slug}/pins/{workspace_id}) and it follows the new active version on its next run.
4. Roll forward by clearing the remaining pins at whatever pace the first customer's results justify — or hold any workspace back for as long as you like.

The inverse works too: to hold one cautious customer back while the fleet moves, pin just that workspace before publishing.

Rollback is one call. Re-activate the previous version with POST /api/v1/org/agents/{slug}/versions/{version}/activate and every unpinned workspace is back on it at its next run:

curl -X POST https://api.levainlabs.com/api/v1/org/agents/support-triage/versions/4/activate \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY"

Clearing a pin is the per-workspace equivalent — the workspace rejoins the fleet on whatever version is active. GET /api/v1/org/agents/{slug}/pins lists which workspaces are currently held, so a staged rollout is always inspectable mid-flight.

Keep an eye on the fleetCopy Anchor Link

GET /api/v1/org/agents lists your registry with each agent's active version and adoption count. The dashboard's Agents page shows the same registry below the workspace's own agents; opening an entry shows its recipe, with a version picker that can activate an earlier version.

Build a new version in the dashboardCopy Anchor Link

Promoting and uploading aren't the only ways to a new version. From an org agent's Recipe tab, New version starts a draft copied from the active version, and the same build conversation as for a workspace agent edits it: describe the change, let the builder work and verify, then Publish. The published draft becomes the active version, so unpinned workspaces follow it on their next run — pin first to stage the rollout, as above.

The draft belongs to the org, not to any workspace: it has no triggers, schedules or integrations of its own, and the builder won't offer to set them up — adopting workspaces provide those. Its build turns run in, and are billed to, your organization's first workspace. The same flow is available over the API: POST /api/v1/org/agents/{slug}/versions/draft creates the draft and POST /api/v1/org/agents/{slug}/versions/{version}/build opens its build conversation.

Edit from ClaudeCopy Anchor Link

The Build from Claude loop works on an org agent too: in your own Claude session, refer to it as org:<slug> and the skill forks a draft, clones its source, pushes your changes, runs the platform's verification and publishes on a green verdict — through the same MCP tools as a workspace agent. Under the hood that is GET /api/v1/org/agents/{slug}/versions/{version}/source and a credential from POST .../git-credential to clone and push, POST .../verify with GET .../review-threads for the reviewer's feedback, and POST .../publish once the verdict is green. Promoting a workspace agent is the same ask in Claude ("promote support-triage to the organization").