Entity Picker

When to useCopy Anchor Link

• The user must choose which real records to work with: an ad account, campaigns, files, teammates.
• The agent fetched more than one candidate and can't tell which the user means.

When not to useCopy Anchor Link

• Only one record matches. Use it and say which one.
• The choices are options or preferences, not records. Use the Question Stepper.
• The agent hasn't fetched the records yet. Fetch them first; never list records from memory.

How the agent should use itCopy Anchor Link

• Every entity comes from a tool result, with its real id.
• Use description to tell similar records apart: an account id, an email, a path.
• Use group when records belong to different parents, e.g. campaigns by ad account.
• Set multiple and max only when the next step can take several records.
• Act only on the ids returned with select.

InteractionCopy Anchor Link

The list is an ARIA listbox (aria-multiselectable when multiple) that tracks the active option with aria-activedescendant; groups are labelled by their headings. Search appears automatically above 6 records, and lists longer than 8 rows scroll inside the card. Once max is reached, the remaining options are disabled until one is cleared.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/entity-picker.json

UsageCopy Anchor Link

import { tool } from "ai"
import { entityPickerTool } from "@/components/genui/entity-picker.schema"

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

import { EntityPicker } from "@/components/genui/entity-picker"

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

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

The agent receives one of:

{ action: "select", ids: ["120210", "330102"] }
{ action: "cancel" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "pick_entities", 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 picker lists the chosen records (or the cancelled state) and never calls onResult again.

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

SchemaCopy Anchor Link

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

SourceCopy Anchor Link