Multi-prompt agents | Tried Docs

Split a call into states, each with its own prompt, functions and transitions, while one general prompt applies throughout.

A multi-prompt agent divides the call into states. Each state has its own prompt, its own functions and transitions to other states. The general prompt and general functions still apply in every state, so you keep shared rules in one place and stage-specific instructions short.

Use multi-prompt when a call has clear stages, such as triage, then booking, then confirmation, and a single prompt has started to skip or blend steps. When the order of steps must be enforced exactly, or you need to branch on data with equations, use a conversation flow instead.

The Multi-prompt states editor with a starting state, a state prompt and a transition

How it works#

The call starts in the Starting state (starting_state, or the first state when unset).
The model sees the general prompt plus a ## Current State: <name> section with that state's prompt.
The model can call the general functions, the current state's functions, and one transition_to_<state> function per transition out of the current state. The transition's description becomes the function description.
When the model calls a transition function, the agent moves to that state. The next reply uses the new state's prompt and functions.
Values passed with the transition are stored as dynamic variables, so later states can use them as {{name}}.

The system variables {{current_agent_state}} and {{previous_agent_state}} hold the state names. The transcript records each move as a node_transition item in transcript_with_tool_calls.

Create a multi-prompt agent#

You can start from the Multi-prompt type in Create agent, or add states to any single prompt agent: a Retell LLM with states is a multi-prompt agent.

Add states#

In the Multi-prompt states card below the welcome message, click Add state. Each new state is named state_1, state_2 and so on.

Name each state#

Expand a state and set State name. Names use letters, numbers, - and _, up to 64 characters, and must be unique. Renaming a state updates transitions and the starting state that point at it.

Write the state prompt#

Use State prompt for what the agent does in this stage only. Keep shared rules (identity, tone, safety) in the general prompt above.

Add transitions#

Under Transitions, click Add transition, pick the destination state and describe when to move, for example "The caller has chosen a day and time". The model moves when the description matches the conversation.

Pass values along (optional)#

Open Values to pass along on a transition and add parameters. The model fills them when it takes the transition, and they become dynamic variables in the next state.

Add state functions#

Under State functions, click Add to give the state tools that only make sense there, such as book_appointment in a booking state.

Choose the starting state#

Set Starting state at the top of the card.

Fields#

On the Retell LLM (Update Retell LLM):

Field	Type	Description
`states`	array	The states.
`states[].name`	string	`^[a-zA-Z0-9_-]{1,64}$`. Unique.
`states[].state_prompt`	string	Prompt for this state. Default `""`.
`states[].tools`	array	Functions available only in this state. Default `[]`.
`states[].edges`	array	Transitions out of this state. Default `[]`.
`states[].edges[].destination_state_name`	string	Target state name.
`states[].edges[].description`	string	When to take the transition. Becomes the description of `transition_to_<state>`.
`states[].edges[].parameters`	object	Optional JSON schema of values to pass. The values become dynamic variables.
`starting_state`	string or null	First state. `null` starts in the first state of the list.
`general_prompt`, `general_tools`	string, array	Apply in every state.

Example#

{
  "general_prompt": "You are Ava, the receptionist for {{business_name}}. Be brief and warm.",
  "general_tools": [
    { "type": "end_call", "name": "end_call", "description": "End the call when the caller is done." }
  ],
  "starting_state": "triage",
  "states": [
    {
      "name": "triage",
      "state_prompt": "Find out whether the caller wants to book, change or cancel an appointment.",
      "edges": [
        {
          "destination_state_name": "booking",
          "description": "The caller wants to book a new appointment.",
          "parameters": {
            "type": "object",
            "properties": { "service": { "type": "string", "description": "The service requested" } },
            "required": ["service"]
          }
        }
      ]
    },
    {
      "name": "booking",
      "state_prompt": "Book a {{service}} appointment. Ask for the preferred day and time, check availability and confirm.",
      "tools": [
        {
          "type": "custom",
          "name": "check_availability",
          "description": "Check open slots for a date.",
          "url": "https://example.com/availability",
          "parameters": {
            "type": "object",
            "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" } },
            "required": ["date"]
          }
        }
      ]
    }
  ]
}

When the model calls transition_to_booking with {"service": "check-up"}, the agent enters booking and {{service}} renders as check-up.

Design tips#

One job per state. If a state prompt has "first", "then" and "finally", split it.
Write transitions as observable facts. "The caller has given a phone number" works better than "Move on when ready".
Add a way back. Give later states a transition back to triage for callers who change their mind.
Put end call and human transfer in general tools so they work from every state.
Watch the prompt length. The 32,768 token limit counts the general prompt, general tools and the largest state together.

Test it#

In Test LLM, walk through each path and check that transition calls appear at the right moments. Use the Simulation mode to run test cases that cover each state. See Test.