assistant-ui--assistant-ui/examples/with-interactables

with-interactables

Demonstrates interactable components — persistent UI components whose state can be read and updated by both the user and the AI assistant.

Features Demonstrated

Task Board

• unstable_useInteractable("taskBoard", config) — registers a single interactable
• Auto-generated update_taskBoard tool with partial scalar updates and array operations
• Collection edits go through tasks.add, tasks.update, tasks.remove, and tasks.clear on the generated update tool

Sticky Notes

• unstable_useInteractable("notes", config) — registers the sticky-note collection and selectedId as one state object
• Auto-generated update_notes manages both note collection edits and selected-note focus
• Selection: click a note to set selectedId; the AI can change focus by updating the same normal state field
• Partial updates: AI can change just one note field with notes.update: [{ id, color: "pink" }]

Getting Started

# Install dependencies (from monorepo root)
pnpm install

# Set your OpenAI API key
cp .env.example .env.local
# Edit .env.local and add your OPENAI_API_KEY

# Run the development server
pnpm --filter with-interactables dev

Open http://localhost:3000 to see the example.

Key Concepts

• unstable_Interactables({ persistence }) — scope resource registered via useAui, with a load/save adapter
• unstable_useInteractable(name, config) — returns [state, { id, setState, isPending, error, flush }]
• Partial updates — auto-generated tools use partial schemas; AI only sends changed fields
• Array operations — array fields support generated add, update, remove, clear, and set operations on the same update_{name} tool
• Selection as state — focused UI state lives in the interactable's normal schema (selectedId), not in a separate manage tool
• sendAutomaticallyWhen — auto-sends follow-up messages when tool calls complete