Build step-by-step wizards for guided AI flows

Candu Actions has two modes. Chat mode is freeform — the user types whatever they want and the AI matches their intent to any available action. Wizard mode is structured — you define a sequence of steps, each with its own question, available actions, and completion criteria. Use wizards when the workflow has clear stages and you want the AI to move through them in order.

New to wizards? Read What is a wizard? for the conceptual overview before diving into config.

How wizards work

At each step, the wizard shows a specific question, gives the AI a focused prompt (stageBooster), exposes only a declared subset of actions (availableActions), and advances when the AI confirms the step’s completionCriteria is met. At runtime, the stageBooster is appended to the agent’s system prompt for that step only. Actions outside availableActions are not exposed to the model at all — they’re invisible, not just discouraged.

Wizard config

{
  "title": "Segment Wizard",
  "version": "poc-1",
  "steps": [
    {
      "id": "abc-213",
      "title": "Describe the segment you want to create",
      "question": "Which users do you want to target?",
      "stageBooster": "Help the user define segment criteria. Use autocomplete_query to look up valid trait names. Don't use markdown. Keep replies short.",
      "availableActions": [
        "segments_create", "segments_list", "segments_get",
        "segments_update", "autocomplete_query", "segment_membership_get"
      ],
      "completionCriteria": "A segment has been created"
    },
    {
      "id": "def-546",
      "title": "Test your first segment",
      "question": "We've created your segment. Do you have a user ID or email to test with?",
      "stageBooster": "Help the user validate the segment. Use autocomplete endpoints to look up users.",
      "availableActions": [
        "segments_list", "segments_get", "segments_update",
        "autocomplete_query", "segment_membership_get"
      ],
      "completionCriteria": "The segment has been validated, or the user has opted to skip"
    }
  ]
}

Notice segments_create is in step 1 but not step 2. Once created, the AI can’t accidentally create another one.

completionCriteria is a natural-language description the AI checks each turn — when satisfied, the wizard advances. Write it as a clear outcome statement, not an instruction.

Action scoping per step

This is the most important concept in wizard design. Each step declares exactly which actions are available. Actions not in the list are invisible to the AI for that step. It cannot call them, reference them, or accidentally trigger them.

As a rule: include every action the AI might legitimately need at a step. Remove actions that should no longer be available once the primary goal of a step is complete.

Writing a good stageBooster

A strong stageBooster has four parts: context (what the user is doing), guidance (what the AI should do), constraints (scope and format rules), and formatting (how the response should look).

Context:     The user wants to create a segment.

Guidance:    Help them define the criteria. Reference available
             fields via autocomplete_query.

Constraints: Don't use markdown. Keep replies short (max 2 paragraphs).

Formatting:  Split answers with newlines to make them easier to read.

The labels are pedagogical — they don’t appear in the live config. In your actual stageBooster string, run the four parts together as one passage. The structure is the discipline; the prose is what the model sees.

Launching a wizard

Wizards are typically triggered from a button or link in your app — for example, a “Create your first segment” CTA on an empty state.

// Wizard mode (structured)
window.canduAgentik.launchChat({ slug: "segment-wizard" });

// Chat mode (freeform)
window.canduAgentik.launchChat();

See it run

The Create a Segment walkthrough shows this exact wizard config running end to end — every tool call, payload, and confirmation step.

​How wizards work

​Wizard config

​Action scoping per step

​Writing a good stageBooster

​Launching a wizard

​See it run

How wizards work

Wizard config

Action scoping per step

Writing a good stageBooster

Launching a wizard

See it run