Ranked Recommendations

When to useCopy Anchor Link

• The user asks which option is best for them: where to stay, which tool to buy, who to interview first, what to cook.
• The agent compared a few real options against the user's situation and can say why each one fits or doesn't.

When not to useCopy Anchor Link

• There's one clear answer. Say it in a sentence.
• The user wants to compare many attributes side by side without a verdict. Use a Data Table.
• The agent only wants to show items to browse or buy. Use the Entity Card, which describes items; this component explains why to choose them.
• The agent hasn't looked anything up. Never rank options from memory.

How the agent should use itCopy Anchor Link

• Write basis as one sentence naming what the ranking optimizes for, in the user's terms: "Ranked for a 2-person team under $20/month that needs a mobile app". It's read to screen readers; the card doesn't repeat it visually, and neither does it show a must/nice legend (each item's checks carry the constraint names).
• Rank 1 is the top pick. Its name is the card's largest text and it shows all its reasons and trade-offs; the other items show their first reason and first trade-off, so put the strongest one first. Give each item 1–3 reasons specific to this user, not generic praise. subtitle and tags are read to screen readers only.
• Be honest. Add up to two trade-offs per item, and mark a missed must-have as false rather than leaving it out. The item then shows "Misses a must-have".
• Fill meets for every constraint, using "partial" when it's met only in part. Constraints without a value aren't shown for that item.
• Cite with [n] in reasons and trade-offs, where n is the 1-based position in sources, the same way as in Citations. Only cite pages the agent retrieved.
• Only make it selectable when the pick changes what happens next, such as starting a trial or searching for stays.
• Lifecycle: set fetchedAt and staleAfterMs on the call when the ranking depends on live data such as prices or availability, so the Renderer flags it as stale. Use supersede when the agent re-ranks after a more result. expiresAt isn't needed unless the items are held offers.

InteractionCopy Anchor Link

Not now is the ✕ icon button. After a decision the list locks, the footer shows a record such as "Chose Tasklane", and focus moves to it. The footer announces it politely.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/ranked-recommendations.json

UsageCopy Anchor Link

import { tool } from "ai"
import { rankedRecommendationsTool } from "@/components/genui/ranked-recommendations.schema"

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

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

The agent receives one of:

{ action: "select", itemIds: ["tasklane"] }
{ action: "more", reason: "Something with built-in time tracking" }
{ action: "more" }
{ action: "dismiss" }

On select, act on the returned ids only. On more, search again using the reason, and show a new ranking. On dismiss, stop.

The helpers in ranked-recommendations-utils.ts (sortByRank, summarizeConstraints, formatScore, formatPrice, toggleSelection, splitMarkers) are pure, so the server can reuse them, for example to check which items miss a must-have before ranking.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "recommend", props: { toolCallId, ...args } }, { message }), then interrupt() until the user's result arrives. Render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored result back as result. The list renders read-only with the user's choice (or the "other options" request and its reason) and never calls onResult again.

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

SchemaCopy Anchor Link

RecommendationItem

Host props: status (streaming, ready, selected, more, dismissed), onResult, result and className.

SourceCopy Anchor Link