Multi-prompt agents

Split a long prompt into named states, each with its own instructions, tools and exits, so the agent only sees what the current step needs.

A multi-prompt agent (agent_type: "multi_prompt") is a prompt agent whose instructions are split into states. The model still drives the conversation, but at any moment it sees only the current state's prompt and tools, which keeps a long script from drowning out the step the caller is on.

Use it when one prompt has grown too long to follow, for example a call that must greet, verify identity, then book or cancel. If the order must be strictly enforced, use a flow agent instead.

In the dashboard you do not start from this type. An agent becomes multi-prompt when you add states from its page. Existing multi-prompt agents keep working, and through the API you can create one directly.

How it works

system_prompt is the general prompt, present in every state: who the agent is and how it speaks.
Each state adds its own state_prompt, shown to the model as the current step after the general prompt.
The agent starts in starting_state.
To move on, the model calls a transition. Dialgem builds one tool per edge, named transition_to_<state>, and the edge's description is what tells the model when to use it. Write it as a plain condition: "The caller has confirmed their date of birth."
The agent is told only that it moved. The new state's prompt applies from its next reply.

Shape

json

{
  "agent_type": "multi_prompt",
  "system_prompt": "You answer calls for Bright Smile Dental. Keep replies short.",
  "starting_state": "greet",
  "states": [
    {
      "name": "greet",
      "state_prompt": "Find out whether the caller wants to book, change or cancel.",
      "edges": [
        { "destination_state_name": "book", "description": "The caller wants a new appointment." }
      ]
    },
    {
      "name": "book",
      "state_prompt": "Ask for the preferred day, then offer two times.",
      "tools": [],
      "edges": [
        {
          "destination_state_name": "greet",
          "description": "The caller changed their mind or wants something else.",
          "parameters": {
            "type": "object",
            "properties": { "reason": { "type": "string" } }
          }
        }
      ]
    }
  ]
}

Field	Meaning
`states[].name`	Unique within the agent.
`states[].state_prompt`	The instructions for this step.
`states[].tools`	Functions available only in this state. A state tool with the same name as a general function replaces it while the agent is in that state.
`states[].edges[]`	The exits. `destination_state_name` must be another state of the agent, and `description` says when to take it.
`edges[].parameters`	Optional JSON Schema of details to collect while moving. They are saved as variables, so the next state's prompt can use them as `{{reason}}`.
`starting_state`	Required when there are states.

Rules checked when you save

A save is refused with 422 when:

agent_type is multi_prompt but there are no states;
states are supplied but agent_type is something else;
two states share a name;
starting_state is not one of the states;
an edge points at a state that does not exist.

Limits

Text chat and test runs do not support multi-prompt agents yet, so test one with a call.
Variables collected on an edge persist for the rest of the call, so name them distinctly.