Procedures | ElevenLabs Documentation

Overview

A procedure contains instructions for one specific task. Each procedure has a trigger that describes when it applies and content that describes what to do. When a conversation matches the trigger, the agent loads the procedure.

Use procedures when your agent needs to handle many distinct tasks. One example use case is a customer support agent, where each procedure covers one type of request: refunds, identity verification, account recovery, or connection troubleshooting.

Procedure types

There are two kinds of procedures:

Free-form procedures are written as natural-language instructions the agent interprets and adapts to the situation.
Structured procedures are an ordered list of typed steps the agent runs the same way every time.

You can use both kinds on the same agent. The agent picks the relevant procedure from its trigger, regardless of type.

Procedures can call each other. A free-form procedure calls another procedure with an inline reference, and a structured procedure calls another structured procedure with a Sub-procedure step. A common pattern is to keep open-ended handling in a free-form procedure and hand off the parts that must run the same way every time to a structured one.

An agent can have procedures, a workflow, or both. When both are present, every procedure is available from every point in the workflow; a procedure cannot be limited to specific workflow nodes. Most agents are built around one approach or the other, but the two compose.

When to use procedures

Every agent has a system prompt. Procedures and workflows are two ways to add structure on top, and an agent can use both. Choose a starting point based on how much the conversation can vary.

Requirement	Use	Why
Simple proof of concept agent	System prompt only	Fastest to set up and iterate on, but a single prompt gets unwieldy as the agent grows in scope.
Task where the agent can adapt wording and order	Free-form procedure	Keeps the whole conversation in one LLM’s context, so the agent adapts wording and order and can follow unexpected turns. Uses more of the context window.
Task whose steps must run the same way every time	Structured procedure	Each step runs in the order you set, the same way every time, and you author it as a short list of steps.
Full control over complex branching and edge cases	Workflow	Runs as a graph of subagents you design and connect yourself, with full control over branching and the model each step uses.

Free-form procedures are the default choice. They are the fastest to write, they read like a document so non-technical teams can own them, and the agent can recover when a conversation goes off script. Reach for a structured procedure when the cost of a skipped or reordered step is high, such as authentication, escalation, or a financial transaction. Reach for a workflow when you need routing logic or per-step model control that neither procedure type offers.

Manage procedures

The dashboard is the recommended way to author procedures. Use the CLI or the API to manage procedures programmatically or integrate them into deployment tooling.

Build via the dashboard

Manage via the CLI

Manage via the API

Open your agent in the dashboard, then select Procedures. Use + to create a free-form or structured procedure. Procedures can be grouped into folders from the same menu. See Free-form procedures and Structured procedures for authoring guidance.

Choose procedures per conversation

By default, every conversation can use all of the agent’s procedures, and the agent loads a procedure only after the conversation matches its trigger. Your application often knows more before the conversation starts: who the user is, which region they are in, or what they called about. Pass procedure IDs in the conversation initiation client data to use that knowledge. You decide which procedures the agent can use, and which ones it follows from the first turn.

Field	What it does	Why use it
`procedure_ids`	Limits the conversation to these procedures. An empty array disables all of the agent’s procedures.	Give each user only the procedures that apply to them, for example hide account procedures from a user who has not signed in. Also use it when procedures have similar triggers that you cannot avoid, such as one refund procedure per region. Pass only the user’s region, so the agent cannot follow another region’s procedure.
`start_procedure_ids`	Starts these free-form procedures with the conversation, so the agent follows them from the first turn. Accepts up to five IDs.	Reply faster when you already know the user’s task, for example from an IVR menu choice, the page that hosts the widget, or CRM data.

A procedure in start_procedure_ids is already loaded when the user first speaks, so the agent skips the LLM call that would load it. Any active procedure stays in the prompt on every turn, whether the agent or your application started it. A started procedure that the conversation never needs still adds its content to every turn, so start only the procedures the conversation is likely to use.

Allow procedure selection

The Procedures override is off by default. Enable it on each agent that should accept procedure IDs from the client.

Dashboard

CLI

SDK

Open your agent in the dashboard, select the Security tab, and enable the Procedures override.

Pass the IDs when the conversation starts

If the agent does not have the Procedures override enabled, or an ID is invalid, the conversation fails to start.

Get procedure IDs from List procedures. Add procedure_ids, start_procedure_ids, or both to the conversation initiation client data:

Conversation initiation payload

{
  "type": "conversation_initiation_client_data",
  "procedure_ids": [
    "agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b",
    "agtprc_2301k8f3xq9zfa7tkrqs6m4bdn5e",
    "agtprc_7801k8f3yt4mfzh2xbq9d0vcpw1r"
  ],
  "start_procedure_ids": ["agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b"]
}

The agent starts the conversation with the first procedure already running. It can still start the other two when the conversation matches their triggers.

The Python and JavaScript conversation SDKs do not send procedure_ids or start_procedure_ids. To use these fields, send the initiation message over the WebSocket yourself.

Both fields follow these rules:

Each ID in procedure_ids must belong to the agent. If a selected procedure calls sub-procedures, include the sub-procedures too.
Each ID in start_procedure_ids must be a free-form procedure. When you also pass procedure_ids, each ID must also be in that list.
procedure_ids applies only to the agent the conversation starts with. It does not apply after an agent transfer.
Started procedures count toward the five active procedures in Limitations. The conversation history records each one as a start_procedure tool call.

Limitations

A procedure’s content is capped at 50,000 characters.
The agent keeps the five most recently started procedures in context. When more have been started in one conversation, the content, inline tools, and knowledge base documents of the oldest free-form procedures drop out of the prompt. Keep procedures focused and use sub-procedures so that few are active at once.
You cannot change a procedure’s type after creating it. To convert between free-form and structured, create a new procedure and update any references to it.
Procedures belong to one agent. They cannot be shared across agents or stored as workspace-level resources.
Duplicating an agent copies its procedures instead of sharing them. The copies receive new procedure IDs, so references in the duplicated agent must use those new IDs.
Procedures cannot be limited to specific workflow nodes. When an agent has both, every procedure is available from every node.
Structured procedures cannot reference knowledge base documents.