> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-prompt agents

> Configure legacy Retell AI multi-prompt agents with LLM states, state prompts, tools, transition parameters, and a starting state for calls.

Multi-prompt agents are a legacy agent type that organizes instructions and tools into LLM states. See [When to use single prompt vs. conversation flow agents](/build/choose-agent-type) for the other agent types.

Multi-prompt state transitions use LLM tool calls. They are different from [conversation flow transitions](/build/conversation-flow/transition-condition), which use a node transition model. In a multi-prompt agent, the state prompt should describe when to call a state transition.

## Edit an existing agent

Open **Edit prompt tree** on the agent detail page to edit its states.

You can also configure states through the [Retell LLM API](/api-references/create-retell-llm).

## Configure LLM states

### State name

Give each state a unique name, such as `information_collection`. Names can contain letters, digits, underscores, and dashes, with a maximum length of 64 characters and no spaces.

### State prompt

The model receives the general prompt followed by the current state's prompt. Put instructions that apply throughout the call in the general prompt and the current task's instructions in the state prompt. Apply the [general prompting principles](/build/prompt-engineering-guide) to both.

### Tools

The model has access to both general tools and the current state's tools. Keep tools used throughout the call, such as `end_call`, in general tools. Put tools needed only for a particular task, such as `book_appointment`, in that state's tools.

Describe when to call a tool in the prompt. For example:

```
Confirm the caller's selected date, time, and timezone. Once confirmed, call book_appointment.
```

See [Function calling](/build/single-multi-prompt/function-calling) for tool configuration.

### State transitions

Define edges for the states the agent can transition to. Because each edge is implemented as a tool call, describe when to take it in the state prompt. For example:

```
Collect the caller's name and order number. Once both are provided, transition to order_lookup.
```

An edge's `parameters` can carry information into later states as [dynamic variables](/build/dynamic-variables). For example, this parameter schema carries the caller's name:

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "user_name": {
      "type": "string",
      "description": "The caller's full name."
    }
  },
  "required": ["user_name"]
}
```

Later state prompts and tool descriptions can reference `{{user_name}}`.

### Starting state

Choose the state the agent should use at the beginning of the call.

## Keep the state structure simple

Keep related conversation and tools in the same state. Limit outgoing edges so the model has fewer transition choices, and describe the transition criteria clearly in the state prompt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.