Conversation Stages
Conversation stages shape the conversation itself. Instead of one instruction set that has to cover every situation, you divide the work into focused stages such as Intake, Troubleshooting, Recommendation, and Handoff. The assistant moves between them as the conversation changes.
Stages are managed in Dashboard → Actions → Stages, or as
conversationStages in the
Assistant Config API, so you can keep stages in
version control and push them from CI.
What a stage holds
Section titled “What a stage holds”Each stage has:
- a name (up to 100 characters);
- a purpose, one or two sentences on what the stage is for (up to 500 characters);
- instructions for the assistant while it is in the stage (up to 2,000 characters);
- the actions it may use, chosen from the actions whose Start says “When the AI decides”;
- When it moves on: for each stage it can hand over to, a sentence saying when that should happen (up to 500 characters).
The first stage in the list is where every conversation starts. Adding a stage links the one before it to the new one, because stages are usually sequential. You can change that in the stage’s move-on conditions.
The purpose and the move-on sentences become tool descriptions the model reads on every turn, so keep them short and concrete: “the visitor has a problem with an order” works better than a paragraph.
How stages combine with the main instructions
Section titled “How stages combine with the main instructions”A stage’s instructions are added after the assistant’s main instructions while the assistant is in that stage. They never replace them, and the rules for grounding, language and formatting still apply. A stage is a refinement, which is why it has a lower limit than the main instructions.
Because the stage text comes later, a model given two instructions that contradict each other tends to follow the stage. A stage that says “answer any question” under main instructions that limit the topics would quietly undo the setup. Ragtime checks for this, as described below.
The stage review
Section titled “The stage review”Stages are part of the draft: like the instructions and actions, they reach visitors when you publish, and the preview uses them as soon as you save. When you save them, Ragtime reviews the stage text against the assistant’s main instructions and looks for three things:
- a conflict with the main instructions;
- an attempt to subvert the assistant’s rules;
- harmful content.
If the review flags a stage, the stages stay off until you fix the text. While they are off, the assistant uses one prompt with all its actions. The dashboard shows each finding with the line it concerns. A change to the main instructions can cause a conflict too, so the review also runs again when you publish, and you can ask for it at any time with Check again.
If the review fails to run, the stages also stay off until a check comes back clear. When no AI provider is configured to run it at all, the stages stay as you set them.
Use the switch above the list to turn stages off yourself. The stages are kept, and the assistant goes back to a single prompt with all its actions.
Trying stages
Section titled “Trying stages”In the assistant preview, each answer shows the stage it ended in and why the assistant moved there. Use it to check that the move-on sentences fire when you expect.
If your page controls the flow, it can move the assistant between stages itself.
See Embedding for the set-stage message and the
stage_changed event.
Permissions
Section titled “Permissions”Anyone who can open the Actions page can look at the stages. Changing them takes the permission to edit actions and also Configure Assistant, because stage instructions are added to the assistant’s own.
When to use stages
Section titled “When to use stages”Stages help when one long prompt has started doing too many jobs. Use them when:
- different phases need different instructions;
- sensitive actions should only be available in the right context;
- a consultation has a natural progression;
- you need an explicit route to escalation or handoff.
For example, an intake stage may only gather context. A recommendation stage can use product lookup actions. A handoff stage can summarize the exchange and use a submission action.
What stages do not do
Section titled “What stages do not do”Stages are not a form builder. The conversation stays model-led and free-form. When the visitor must complete explicit fields or choices, use a Message step with the Form response in an action.
Stages are also not a durable automation engine. They describe the assistant’s current mode, not background jobs, schedules, long waits or run history. Use an Operational Workflow for those.
If no stages are configured, the assistant keeps its normal single-prompt behavior and can use its regular action set.