Option Builder

When to useCopy Anchor Link

• The user is assembling a combination where every choice has a cost or impact: APIs and their load time, plan add-ons and their price, PC parts within a budget, integrations and their monthly cost.
• Seeing the combined total, and whether it fits a budget, should shape the choice.

When not to useCopy Anchor Link

• The options have no numbers to combine. Use the Entity Picker or the Question Stepper.
• The agent doesn't have real metrics for every option. Fetch them first; never estimate prices, sizes or timings.
• It's one product with variants (size, color). Use Product Options.

How the agent should use itCopy Anchor Link

• Every metric value and budget comes from a tool result or the user, never from the model.
• Order metrics by importance. The first two are the big header numbers; on each row they sit on the right, the first in body text and the second quieter.
• Use requires for real dependencies and excludes for real conflicts, and set a group's max: 1 for one-of choices like a CPU.
• Only add score when budgets exist, and say what the budget is in the reply.
• Over budget is allowed. On submit, read totals and point out any overrun before moving on.
• On dismiss, drop the flow and ask what the user would like instead.

How it worksCopy Anchor Link

Selections persist across tabs, and each change is announced in a polite live region, e.g. "Added Mapbox GL. Load time 582 ms, over budget by 82 ms. Size 611 KB, over budget by 99 KB. Score 57, grade F." The pure helpers (aggregation, budgets, score, dependency resolution, formatting) live in option-builder-utils.ts so the host can reuse them, e.g. to recheck totals on the server.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/option-builder.json

UsageCopy Anchor Link

import { tool } from "ai"
import { optionBuilderTool } from "@/components/genui/option-builder.schema"

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

import { OptionBuilder } from "@/components/genui/option-builder"

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

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

The agent receives one of:

{
  action: "submit",
  selected: ["northwind-vision", "contoso-speech", "fabrikam-search"],
  totals: { load: 368, size: 336896 },
  score: { value: 89, grade: "B" },
}
{ action: "dismiss" }

selected includes dependencies that were added automatically. totals leaves out metrics with no value (e.g. max of nothing).

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

Pass the stored result back as result. The builder shows the submitted totals, score and selected options (or the closed state) read-only, and never calls onResult again.

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

SchemaCopy Anchor Link

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

SourceCopy Anchor Link