Guided Flow

When to useCopy Anchor Link

• The user wants to complete a short task that needs a few ordered inputs: booking, returning, scheduling, signing up.
• Later steps depend on earlier ones, or the inputs mix choices, times and contact details.

When not to useCopy Anchor Link

• You only need one or two answers. Ask in text, or use a Question Stepper.
• You're collecting a single record with many fields and no order. Use a form.
• The task needs more than 5 steps. Split it, or do part of it yourself.

How the agent should use itCopy Anchor Link

• Keep it to 2–5 steps, each with a short title, in the order a person would decide.
• Options and slots are data-bound when they refer to real items, payment methods or availability. Read them from a tool, never invent them.
• Mark only the fields you truly need as required. Required fields are marked with an asterisk; the rest are optional.
• End with a review step before anything binding, such as a booking, payment or return.
• Don't act until you receive submit, and use only the returned values.

Step typesCopy Anchor Link

InteractionCopy Anchor Link

• Validation is inline. Required fields, email addresses, phone numbers, numbers and dates are checked when the user leaves a field, with the error linked to the input through aria-describedby.
• Focus follows the step. After moving, focus lands on the step title, which screen readers announce as "Step 2 of 4: Details". On screen, progress is a segmented bar.
• Streaming. Steps arrive one by one and the user can start on step 1 straight away. The announced count reads "of 2…" until the payload is complete, and submitting waits for it.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/guided-flow.json

UsageCopy Anchor Link

import { tool } from "ai"
import { guidedFlowTool } from "@/components/genui/guided-flow.schema"

const tools = {
  // No execute(): the call is completed by the user's answers in the UI.
  [guidedFlowTool.name]: tool({
    description: guidedFlowTool.description,
    inputSchema: guidedFlowTool.inputSchema,
  }),
}

import { GuidedFlow } from "@/components/genui/guided-flow"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-start_flow") return null

  return (
    <GuidedFlow
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "start_flow",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

The agent receives one of:

{
  action: "submit",
  values: {
    party: "3-4",
    time: "1930",
    contact: { name: "Dana Levi", phone: "+1 555 0142" },
  },
}
{ action: "cancel" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "start_flow", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

When a conversation is reloaded, pass the stored result back as result. The component renders a compact, read-only summary of the answers (or "Cancelled") and never calls onResult again, so the flow can't be submitted twice. With the AI SDK, that's the tool call's output:

<GuidedFlow
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

Step (every type has id, title and an optional description, one short line such as a date or a constraint)

Host props: status (streaming, ready, submitted, cancelled), onResult, result and className.

SourceCopy Anchor Link