using-procedure-api

Using the Procedure API

Procedures are reusable instruction blocks that an agent runs when a trigger matches. Use the ElevenLabs CLI by default to create, edit, compile, and publish them. Python and JavaScript SDKs are also available for application code. Reference: [Procedures](https://elevenlabs.io/docs/eleven-agents/customization/procedures.md) · [API Reference](https://elevenlabs.io/docs/api-reference/agents/procedures/).

For what belongs in `trigger` and `content`, see [Writing Procedures](writing-procedures.md).

The CLI exposes the complete procedure lifecycle, including draft operations and structured procedure compilation.

Prerequisites

• `ELEVENLABS_API_KEY` is set, with the `CONVAI_READ` and `CONVAI_WRITE` scopes.
• Reading requires the viewer role on the target agent. Creating, updating, removing, compiling, and publishing require the editor role. Publishing to a protected branch requires admin.
• The target `agent_id` is known.
• The target `branch_id` is known. If not, read `main_branch_id` with `elevenlabs agents get --agent-id "$AGENT_ID" --query main_branch_id`, or list branches with `elevenlabs agents branches list --agent-id "$AGENT_ID"`.

AGENT_ID="your-agent-id"
BRANCH_ID="your-branch-id"

The CLI reads `ELEVENLABS_API_KEY` from the environment automatically; never pass the key as a flag, and never print or persist it.

CLI

Use these command groups for procedure management:

| Operation | Command | |-----------|---------| | List, create, read, remove | `elevenlabs agents procedures ...` | | Read, update, discard draft | `elevenlabs agents procedures drafts ...` | | Compile structured procedures | `elevenlabs agents procedures compile` | | Publish pending changes | `elevenlabs agents update` |

Use `--dry-run` to validate and inspect a generated request without sending it. Use `--schema` on any command to inspect its machine-readable input and output contract.

SDKs

Procedure APIs are available in both SDKs starting in `2.60.0`. Earlier versions do not include a `procedures` client, so install at or above that version:

pip install "elevenlabs>=2.60.0"
npm install @elevenlabs/elevenlabs-js@^2.60.0

For JavaScript, use `@elevenlabs/elevenlabs-js`. The unscoped `elevenlabs` npm package is the deprecated v1.x and has no procedures client at any version.

Both clients read `ELEVENLABS_API_KEY` from the environment; never pass a literal key.

Use these SDK methods for the procedure endpoints. Python nests them under `client.conversational_ai.agents`; JavaScript uses `client.conversationalAi.agents`:

| Operation | Endpoint | Method | |-----------|----------|--------| | List | `GET .../procedures` | `procedures.list` | | Create | `POST .../procedures` | `procedures.create` | | Read branch HEAD | `GET .../procedures/{procedure_id}` | `procedures.get` | | Read draft | `GET .../procedures/{procedure_id}/draft` | `procedures.drafts.get` | | Update draft | `PATCH .../procedures/{procedure_id}/draft` | `procedures.drafts.update` | | Discard draft | `DELETE .../procedures/{procedure_id}/draft` | `procedures.drafts.delete` | | Remove | `DELETE .../procedures/{procedure_id}` | `procedures.remove` | | Compile | `POST .../procedures/compile` | `procedures.compile` | | Publish | `PATCH /v1/convai/agents/{agent_id}?branch_id=...` | `agents.update` |

SDK notes:

• JavaScript takes the IDs positionally, then a body object. Python takes keyword arguments — except `procedures.create`, which takes its body as `request=CreateProcedureRequestModel(...)`. Flat keywords on `create` raise `TypeError`.
• Read one historical version with `procedures.get(..., version_id=...)` or `procedures.get(agentId, branchId, procedureId, { versionId })`.
• Pass `agent_version_id` to `procedures.list` or `procedures.get` to resolve the procedures attached to a specific agent version.
• For structured changes, pass the `workflow` returned by `procedures.compile` to `agents.update`.

The flow below creates a free-form procedure, edits its draft, and publishes it.

Python

from elevenlabs import ElevenLabs
from elevenlabs.types import CreateProcedureRequestModel

client = ElevenLabs()
procedures = client.conversational_ai.agents.procedures

created = procedures.create(
    agent_id=AGENT_ID,
    branch_id=BRANCH_ID,
    request=CreateProcedureRequestModel(
        name="Refund requests",
        type="free_form",
        trigger="When the user asks for a refund",
        content="Confirm the order number, check eligibility, and explain the next step.",
    ),
)

draft = procedures.drafts.get(
    agent_id=AGENT_ID, branch_id=BRANCH_ID, procedure_id=created.procedure_id
)
procedures.drafts.update(
    agent_id=AGENT_ID,
    branch_id=BRANCH_ID,
    procedure_id=created.procedure_id,
    name=draft.name,
    type="free_form",
    trigger=draft.trigger,
    content="Confirm the order number. Check refund eligibility. Explain the refund timeline.",
)

client.conversational_ai.agents.update(
    agent_id=AGENT_ID,
    branch_id=BRANCH_ID,
    version_description="Publish refund procedure",
)

If the pending changes include structured procedures, compile before publishing:

from elevenlabs.errors import BadRequestError

try:
    compiled = procedures.compile(agent_id=AGENT_ID, branch_id=BRANCH_ID)
except BadRequestError as error:
    print(f"Compile failed, nothing published: {error.body}")
    raise

client.conversational_ai.agents.update(
    agent_id=AGENT_ID,
    branch_id=BRANCH_ID,
    workflow=compiled.workflow,
    version_description="Publish refund procedure",
)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient();
const procedures = client.conversationalAi.agents.procedures;

const created = await procedures.create(agentId, branchId, {
  name: "Refund requests",
  type: "free_form",
  trigger: "When the user asks for a refund",
  content: "Confirm the order nu