Assistant UI

Overview

Workflow

1. Classify the task before coding. Determine whether the request is setup, runtime wiring, primitives, tools, cloud persistence, or migration. If the request includes explicit exclusion language (

   without/no/not assistant-ui

   ), stop and do not use this skill.
2. Select runtime and architecture first. Choose AI SDK, LangGraph, or external-store path before editing components.
3. Apply setup commands with minimum blast radius. Prefer the smallest CLI operation (

   add

   for existing projects,

   create

   for new projects).
4. Wire provider and thread lifecycle. Ensure

   AssistantRuntimeProvider

   and runtime hook are configured before Thread/Composer work.
5. Implement tool UI using current APIs. Prefer

   useAui + Tools({ toolkit })

   for registration; use

   makeAssistantToolUI

   for UI-only bindings.
6. Validate and migrate safely. Run dry-run upgrade checks first, then codemods, then verification.

Runtime Decision Rules

• Choose AI SDK runtime when backend communication is a chat endpoint and no graph thread state is required.
• Choose LangGraph runtime when thread lifecycle (

  initialize/create/load

  ) and interrupts are required.
• Choose external store runtime when app state is controlled outside assistant-ui.
• Add Assistant Cloud only when persistence, auth-linked thread continuity, or multi-device resume is required.

references/runtime-selection.md

Execution Protocol

1. Read

   references/setup-and-cli.md

   for command sequence and flags.
2. Read exactly one runtime reference.

• Read

  references/langgraph-runtime.md

  for LangGraph.
• Read

  references/runtime-selection.md

  for AI SDK or external-store decisions.

1. Read

   references/tool-ui-patterns.md

   only if tools are in scope.
2. Read

   references/cloud-persistence.md

   only if cloud is in scope.
3. Read

   references/troubleshooting.md

   only when failures appear.

Output Contract

• Runtime provider wiring that matches the chosen runtime.
• Thread and composer integration that compiles with the chosen runtime.
• Tool registration and rendering behavior consistent with current APIs.
• Environment variable expectations for cloud flows.
• Upgrade path or migration notes if dependency upgrades are requested.

Guardrails

• Prefer

  Tools({ toolkit })

  over legacy registration helpers.
• Use

  makeAssistantToolUI

  only for UI bindings to already-defined backend tools.
• Keep LangGraph thread handling explicit:

  initialize

  ,

  create

  , and

  load

  .
• Execute upgrade sequence in this order:

  update --dry

  ->

  upgrade

  ->

  codemod

  -> test.
• Avoid broad documentation dumps; load only relevant references.
• Do not activate this workflow for comparison-only requests that do not require assistant-ui implementation changes.

Reference Map

• Setup and CLI:

  references/setup-and-cli.md

• Runtime selection:

  references/runtime-selection.md

• LangGraph runtime wiring:

  references/langgraph-runtime.md

• Tool UI patterns:

  references/tool-ui-patterns.md

• Cloud persistence:

  references/cloud-persistence.md

• Debug and recovery:

  references/troubleshooting.md