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

Give the agent a name and a short description of what it does. The platform derives a URL-safe slug from the name — you'll use the slug everywhere.

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

Next

• Run your agent and watch it execute.
• Understand how the harness runs your agent step by step.