Agents

An agent is the unit you deploy on Levain. It has a name, a slug, a description, a lifecycle, and one or more versions. This guide covers the workflow end to end.

Create an agent

Building an agent needs the Team plan or above — Free workspaces get the Levain agent only; see Plans & Billing. On Team and up, the dashboard's Agents page lists everything you've shipped and has a New agent button for spinning up the next one. Give the agent a name and a short description — Levain derives a URL-safe slug you'll use everywhere the agent is referenced.

The same flow is available from the API for scripting:

curl -X POST https://api.levainlabs.com/api/v1/agents \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support triage",
    "description": "Routes inbound tickets to the right queue."
  }'

The response includes the agent's id, its slug (e.g. support-triage), and its first version (version 1, status: draft). Slugs are unique per workspace and safe to hard-code in application configs.

Reference an agent

You can reference an agent by either its id (a UUID) or its slug. The slug is usually the better choice — it's stable, human-readable, and the same across environments if you keep your agent names in sync.

# Both of these work
curl https://api.levainlabs.com/api/v1/agents/support-triage
curl https://api.levainlabs.com/api/v1/agents/3f7a...c2e1

Version an agent

Every material change to an agent creates a new version. Versions are numbered, they have their own status (draft → active → archived), and each one is pinned to a specific revision of the agent's recipe repo.

Create a new version with POST /api/v1/agents/{agent_id}/versions and promote it by updating its status. Production runs go against the agent's currently active version, which means you can roll a change forward or backward without changing any client code.

See the API reference for the full version schema.

Agent lifecycle

Agents themselves also have a status:

Move between states with PATCH /api/v1/agents/{agent_id}.

Agent settings

Each agent has a Settings card in the dashboard where you configure run limits and notification behaviour. You can:

• Set a wall-clock timeout, a cost budget, and a step limit — the harness enforces these on every run.
• Enable Run notifications to receive an in-app alert (and optionally an email) when a run completes or fails. The toggle is off by default; see the Runs guide for how to configure which channels each notification type uses.
• Pick an icon and accent color so the agent is recognizable at a glance in the agents list and its detail header. Leave both unset and the agent falls back to a colored initial.

These settings can also be written through the API as part of an agent update:

curl -X PATCH https://api.levainlabs.com/api/v1/agents/support-triage \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"notify_on_run": true}}'

Managed agents

Some agents are operated by Levain rather than authored by you — you don't write or version their recipes, and Levain maintains their behavior. They still run, schedule, and report like any agent you built.

The Levain agent

Every workspace comes with the Levain agent already adopted — a managed assistant that Levain operates on your behalf. You don't author or version it; it's always available and always reflects the current platform.

You reach it from the dashboard or by tagging the Levain Slack app in any channel it's invited to. In Slack's Agents & AI Apps pane you can start a direct conversation with it at any time.

The Levain agent does the work itself first: it answers questions, grounds business-number questions in your synced app data, searches the web for anything the workspace doesn't hold, and recalls past sessions instead of asking you to repeat yourself. It only hands a task off to another agent you've built when that agent clearly owns the job — it's an assistant, not just a router.

On the Free plan, the Levain agent is the whole story — see Plans & Billing. Building, template adoption, and managed-agent adoption all start on Team.

The managed-agent catalog

Beyond the Levain agent, Levain ships ready-made analysts you adopt instead of build. Adopting one — like building your own agent — requires a platform app connected — see Integrations — before it can be adopted:

GET /api/v1/managed-agents lists everything available to your workspace and whether you've already adopted it. Adopt one with POST /api/v1/managed-agents/{slug}/adopt or the adopt_managed_agent MCP tool — returns 409 if the agent isn't adoptable yet (missing integration, no published recipe, or already adopted). Once adopted, the agent appears in your agent list with kind managed and behaves like any agent you built: schedule it, talk to it, watch its runs. There's no in-dashboard catalog browser yet, so adoption is API- or MCP-only for now.

What's true for every managed agent

• Runs on Levain's account and doesn't count against your run limits.
• Not editable — you can't change its recipe or instructions.
• Can be given access to your workspace integrations the same way any agent you built can.

Next

• Author the recipe that defines what the agent does.
• Run your agent and watch it execute.
• Understand how the harness runs your agent step by step.