From 70a95101bc51b3a10ad39dd4870674658db07810 Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Fri, 24 Apr 2026 21:06:50 -0400
Subject: [PATCH 1/4] Add docs for UI Agents

---
 api-reference/client/js/a11y-snapshot.mdx     | 235 +++++++++++++
 api-reference/client/js/overview.mdx          |  14 +
 api-reference/client/js/ui-agent-client.mdx   | 139 ++++++++
 api-reference/client/react/components.mdx     |  39 +++
 api-reference/client/react/hooks.mdx          | 299 ++++++++++++++++
 .../pipecat-subagents/decorators.mdx          |  50 ++-
 api-reference/pipecat-subagents/messages.mdx  |  89 +++++
 api-reference/pipecat-subagents/overview.mdx  |  29 ++
 api-reference/pipecat-subagents/ui-agent.mdx  | 318 ++++++++++++++++++
 .../pipecat-subagents/ui-commands.mdx         |  90 +++++
 .../pipecat-subagents/ui-prompts.mdx          |  47 +++
 api-reference/pipecat-subagents/ui-tools.mdx  | 100 ++++++
 docs.json                                     |  21 +-
 13 files changed, 1465 insertions(+), 5 deletions(-)
 create mode 100644 api-reference/client/js/a11y-snapshot.mdx
 create mode 100644 api-reference/client/js/ui-agent-client.mdx
 create mode 100644 api-reference/pipecat-subagents/ui-agent.mdx
 create mode 100644 api-reference/pipecat-subagents/ui-commands.mdx
 create mode 100644 api-reference/pipecat-subagents/ui-prompts.mdx
 create mode 100644 api-reference/pipecat-subagents/ui-tools.mdx

diff --git a/api-reference/client/js/a11y-snapshot.mdx b/api-reference/client/js/a11y-snapshot.mdx
new file mode 100644
index 00000000..4d521b49
--- /dev/null
+++ b/api-reference/client/js/a11y-snapshot.mdx
@@ -0,0 +1,235 @@
+---
+title: "Accessibility Snapshots"
+description: "Stream the document's accessibility tree to the server as <ui_state>"
+---
+
+## Overview
+
+The accessibility-snapshot module produces a structured tree of the document
+that the server-side
+[`UIAgent`](/api-reference/pipecat-subagents/ui-agent) renders into LLM
+context as `<ui_state>`. Shape and filtering are inspired by Playwright's
+accessibility snapshot and the Playwright MCP server's LLM-facing format:
+the goal is a compact, semantically meaningful tree, not a raw DOM dump.
+
+```javascript
+import {
+  A11ySnapshotStreamer,
+  snapshotDocument,
+  findElementByRef,
+} from "@pipecat-ai/client-js";
+```
+
+The streaming side is handled by `A11ySnapshotStreamer` (or
+[`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot) in
+React). The walker (`snapshotDocument`) is exposed for apps that need a
+one-off snapshot, and `findElementByRef` resolves a server-supplied ref
+back to a live DOM element for command handlers.
+
+<Note>
+  Apps can mark a subtree as PII / sensitive by adding `data-a11y-exclude` to
+  the element. The walker skips it and its descendants entirely, without also
+  hiding it from screen readers (unlike `aria-hidden`). Password inputs are
+  stripped automatically.
+</Note>
+
+## A11ySnapshotStreamer
+
+```typescript
+class A11ySnapshotStreamer {
+  constructor(client: UIAgentClient, options?: A11ySnapshotStreamerOptions);
+  start(): void;
+  stop(): void;
+}
+```
+
+Framework-agnostic helper that drives accessibility-snapshot streaming.
+Wraps the walker, a `MutationObserver`, and the other triggers
+(`scrollend`, `resize`, focus, `visibilitychange`) into a single object
+with a `start` / `stop` lifecycle.
+
+```javascript
+import { A11ySnapshotStreamer, UIAgentClient } from "@pipecat-ai/client-js";
+
+const ui = new UIAgentClient(pcClient);
+ui.attach();
+
+const streamer = new A11ySnapshotStreamer(ui);
+streamer.start();
+
+// Later
+streamer.stop();
+```
+
+<Note>
+  React apps should prefer
+  [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), which
+  is a thin lifecycle wrapper around this class.
+</Note>
+
+### Triggers
+
+A snapshot is scheduled (debounced via `debounceMs`) on:
+
+- **DOM mutations** observed by `MutationObserver` on `document.body`
+  (`childList`, `subtree`, and a curated list of attribute changes including
+  `role`, `aria-*`, `data-a11y-exclude`, `disabled`, `hidden`, `tabindex`,
+  `href`).
+- **Focus changes** (`focusin`, `focusout`).
+- **Scroll-end** (`scrollend`, captured at window level so any scrollable
+  ancestor triggers it).
+- **Window resize** (debounced because the viewport rect shifts which nodes
+  are `[offscreen]`).
+- **Tab visibility** transition to `visible`.
+
+An initial snapshot is scheduled immediately on `start()`.
+
+### Options
+
+<ParamField path="debounceMs" type="number" default="300">
+  Minimum interval between snapshot emissions, in milliseconds. Multiple
+  triggers within the window coalesce into one snapshot.
+</ParamField>
+
+<ParamField path="trackViewport" type="boolean" default="true">
+  When `true`, annotate every emitted node with `"offscreen"` in its `state`
+  list if its bounding rect sits entirely outside the viewport. Set to `false`
+  to skip the per-node layout measurement (e.g. on very large pages where layout
+  cost outweighs the viewport signal).
+</ParamField>
+
+<ParamField path="logSnapshots" type="boolean" default="false">
+  When `true`, log each emitted snapshot to the browser console (node count,
+  rough token estimate, raw tree). Mirrors the server's `log_snapshots` flag on
+  `UIAgent`.
+</ParamField>
+
+### Methods
+
+#### start
+
+```typescript
+start(): void
+```
+
+Begin streaming. Idempotent: subsequent calls before `stop()` are no-ops.
+
+#### stop
+
+```typescript
+stop(): void
+```
+
+Stop streaming. Detaches all observers/listeners and cancels pending timers.
+Safe to call before `start()` or multiple times.
+
+## snapshotDocument
+
+```typescript
+function snapshotDocument(
+  root?: Element,
+  options?: SnapshotOptions,
+): A11ySnapshot;
+```
+
+Produce a one-off accessibility snapshot of a DOM subtree. Useful for tests
+or for apps that want to drive snapshot timing manually (e.g. snapshot only
+on a specific app event).
+
+<ParamField path="root" type="Element">
+  Element to walk. Defaults to `document.body`.
+</ParamField>
+
+<ParamField path="options" type="SnapshotOptions">
+  Snapshot options.
+  <Expandable title="SnapshotOptions">
+    <ParamField path="trackViewport" type="boolean" default="true">
+      When `true`, each emitted node gets `"offscreen"` in its state list if its
+      bounding rect sits entirely outside the viewport.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Returns:** An `A11ySnapshot` with a `generic` root containing the walked
+children, plus a client-side capture timestamp.
+
+## findElementByRef
+
+```typescript
+function findElementByRef(ref: string): Element | null;
+```
+
+Resolve a ref string like `"e42"` back to a live DOM element. Returns `null`
+if the ref was never assigned or the element has since been
+garbage-collected.
+
+The walker assigns stable refs to every emitted DOM element via a `WeakMap`
+(forward) plus a `Map<string, WeakRef<Element>>` (reverse). Refs persist as
+long as the element stays mounted and survive across snapshots. Command
+handlers use this to act on nodes the server referenced from `<ui_state>`.
+
+The
+[`useStandard*Handler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
+hooks call this internally.
+
+## Types
+
+### A11yNode
+
+One node in the accessibility snapshot tree.
+
+```typescript
+interface A11yNode {
+  ref: string;
+  role: string;
+  name?: string;
+  value?: string;
+  state?: string[];
+  level?: number;
+  colcount?: number;
+  rowcount?: number;
+  children?: A11yNode[];
+}
+```
+
+| Field      | Type         | Description                                                                                                        |
+| ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `ref`      | `string`     | Stable reference id of the form `e{N}`. Persists across snapshots while the DOM node is mounted.                   |
+| `role`     | `string`     | ARIA role (explicit or tag-derived).                                                                               |
+| `name`     | `string`     | Accessible name, truncated to 100 chars.                                                                           |
+| `value`    | `string`     | Current value for inputs (omitted for passwords), progress, etc.                                                   |
+| `state`    | `string[]`   | Short state tags. Known values: `"focused"`, `"selected"`, `"expanded"`, `"checked"`, `"disabled"`, `"offscreen"`. |
+| `level`    | `number`     | Heading level, 1-6.                                                                                                |
+| `colcount` | `number`     | Column count for grid-like containers, populated from `aria-colcount`.                                             |
+| `rowcount` | `number`     | Row count for grid-like containers, populated from `aria-rowcount`.                                                |
+| `children` | `A11yNode[]` | Child nodes.                                                                                                       |
+
+### A11ySnapshot
+
+```typescript
+interface A11ySnapshot {
+  root: A11yNode;
+  captured_at: number;
+}
+```
+
+Shape of the payload inside a `__ui_snapshot` UI event. A full tree is sent
+on each update; the server keeps the latest and renders it into
+`<ui_state>...</ui_state>` when an agent injects it.
+
+| Field         | Type       | Description                                                      |
+| ------------- | ---------- | ---------------------------------------------------------------- |
+| `root`        | `A11yNode` | Root of the accessibility tree (usually `document.body`'s node). |
+| `captured_at` | `number`   | Client-side timestamp (ms since epoch) when captured.            |
+
+### UI_SNAPSHOT_EVENT_NAME
+
+```typescript
+const UI_SNAPSHOT_EVENT_NAME = "__ui_snapshot";
+```
+
+Reserved UI event name carrying an accessibility snapshot. The server-side
+`UIAgent` recognizes this name and stores the payload as the latest
+snapshot without dispatching to `@on_ui_event` handlers or injecting a
+`<ui_event>` developer message. Underscore-prefixed to signal SDK-internal
+and avoid colliding with app-defined event names.
diff --git a/api-reference/client/js/overview.mdx b/api-reference/client/js/overview.mdx
index c4a817d0..772e46db 100644
--- a/api-reference/client/js/overview.mdx
+++ b/api-reference/client/js/overview.mdx
@@ -85,6 +85,20 @@ pcClient.connect({
   >
     Daily, SmallWebRTC, WebSocket, and other transports
   </Card>
+  <Card
+    title="UIAgentClient"
+    icon="window"
+    href="/api-reference/client/js/ui-agent-client"
+  >
+    Send UI events and dispatch UI commands with the v1 UI Agent protocol
+  </Card>
+  <Card
+    title="A11y Snapshots"
+    icon="eye"
+    href="/api-reference/client/js/a11y-snapshot"
+  >
+    Stream the document's accessibility tree to the server as `<ui_state>`
+  </Card>
 </CardGroup>
 
 The Pipecat JavaScript SDK implements the [RTVI standard](/client/rtvi-standard) for real-time AI inference, ensuring compatibility with any RTVI-compatible server and transport layer.
diff --git a/api-reference/client/js/ui-agent-client.mdx b/api-reference/client/js/ui-agent-client.mdx
new file mode 100644
index 00000000..ff2a0016
--- /dev/null
+++ b/api-reference/client/js/ui-agent-client.mdx
@@ -0,0 +1,139 @@
+---
+title: "UIAgentClient"
+description: "Client-side surface for the UI Agent pattern"
+---
+
+## Overview
+
+`UIAgentClient` wraps an existing `PipecatClient` with the v1 UI Agent
+protocol:
+
+- **`sendEvent(name, payload)`** for client → server events.
+- **`registerCommandHandler(name, handler)`** for server → client commands.
+  Handlers dispatch on the command name extracted from `RTVIEvent.ServerMessage`
+  payloads of type `"ui.command"`.
+
+Construction does not subscribe to anything. Call `attach()` to start
+listening for `RTVIEvent.ServerMessage` and store the returned detach
+function to stop. The React provider
+([`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider))
+does this automatically inside a `useEffect` so subscription lifecycle
+follows mount/unmount.
+
+```javascript
+import { PipecatClient, UIAgentClient } from "@pipecat-ai/client-js";
+
+const pcClient = new PipecatClient({ /* ... */ });
+const uiClient = new UIAgentClient(pcClient);
+const detach = uiClient.attach();
+
+uiClient.registerCommandHandler("toast", (payload) => {
+  showToast(payload.title, payload.subtitle);
+});
+
+uiClient.sendEvent("nav_click", { view: "settings" });
+
+// Later, on cleanup
+detach();
+```
+
+## Constructor
+
+```typescript
+new UIAgentClient(client: PipecatClient)
+```
+
+<ParamField path="client" type="PipecatClient" required>
+  An existing Pipecat client. The UI agent client wraps this without taking
+  ownership; the host is still responsible for connecting and disconnecting
+  the underlying client.
+</ParamField>
+
+## Properties
+
+### pipecatClient
+
+```typescript
+get pipecatClient: PipecatClient
+```
+
+The underlying Pipecat client, exposed as an escape hatch when an app needs
+to call `PipecatClient` methods directly.
+
+## Methods
+
+### sendEvent
+
+```typescript
+sendEvent<T = unknown>(name: string, payload?: T): void
+```
+
+Send a named UI event to the server. The event is delivered as an RTVI
+client message with type `"ui.event"`; the bridge installed by
+`attach_ui_bridge` republishes it as `BusUIEventMessage` on the bus.
+
+<ParamField path="name" type="string" required>
+  App-defined event name. Must match the `name` argument on a server-side
+  `@on_ui_event(name)` handler if the agent should react.
+</ParamField>
+
+<ParamField path="payload" type="T">
+  App-defined payload. Schemaless. Optional.
+</ParamField>
+
+### registerCommandHandler
+
+```typescript
+registerCommandHandler<T = unknown>(
+  name: string,
+  handler: UICommandHandler<T>,
+): void
+```
+
+Register a handler for a named UI command. Overwrites any existing handler
+for the same name.
+
+<ParamField path="name" type="string" required>
+  App-defined command name. Must match the `name` argument the server passes
+  to `UIAgent.send_command(name, payload)`.
+</ParamField>
+
+<ParamField path="handler" type="UICommandHandler<T>" required>
+  Callback invoked with the command payload. Sync or async; rejected promises
+  surface to the host's unhandled-rejection channel rather than being
+  swallowed.
+</ParamField>
+
+### unregisterCommandHandler
+
+```typescript
+unregisterCommandHandler(name: string): void
+```
+
+Remove the handler previously registered for `name`, if any. No-op when no
+handler is registered.
+
+### unregisterAllCommandHandlers
+
+```typescript
+unregisterAllCommandHandlers(): void
+```
+
+Remove all registered command handlers.
+
+### attach
+
+```typescript
+attach(): () => void
+```
+
+Subscribe to `RTVIEvent.ServerMessage` on the underlying `PipecatClient`.
+Returns a detach function that unsubscribes.
+
+Safe to call more than once: each call installs an independent listener.
+Invoke the returned function to remove that listener. The React provider
+calls this inside `useEffect` and uses the returned function as the cleanup,
+so subscription lifecycle follows React's mount/unmount cycle (including
+`StrictMode`'s double-invoke in development).
+
+**Returns:** A `() => void` detach function.
diff --git a/api-reference/client/react/components.mdx b/api-reference/client/react/components.mdx
index f1b18ae7..df10be47 100644
--- a/api-reference/client/react/components.mdx
+++ b/api-reference/client/react/components.mdx
@@ -21,6 +21,45 @@ The root component for providing Pipecat client context to your application. It
   A singleton instance of `PipecatClient`
 </ParamField>
 
+## UIAgentProvider
+
+Wraps its children with a `UIAgentClient` bound to a Pipecat client. Mount
+inside (or alongside) `PipecatClientProvider`. Descendants can then call
+[`useUIAgentClient`](/api-reference/client/react/hooks#useuiagentclient),
+[`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler),
+[`useUIEventSender`](/api-reference/client/react/hooks#useuieventsender),
+[`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), and
+the [`useStandard*Handler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
+hooks.
+
+The provider subscribes to `RTVIEvent.ServerMessage` on the underlying
+Pipecat client to dispatch UI commands. On unmount (or when the underlying
+Pipecat client changes), the subscription is torn down via the detach
+function returned from `client.attach()`, including under `StrictMode`'s
+double-invoke in development.
+
+```jsx
+<PipecatClientProvider client={pcClient}>
+  <UIAgentProvider>
+    <App />
+  </UIAgentProvider>
+</PipecatClientProvider>
+```
+
+**Props**
+
+<ParamField path="client" type="PipecatClient">
+  The Pipecat client to bind the UI agent to. When omitted, the provider
+  reads the client from the ambient `PipecatClientProvider` via
+  `usePipecatClient`. When set, the prop takes precedence and the context
+  is ignored.
+
+  Pass this explicitly when the host provides the client via a render prop
+  (for example, `PipecatAppBase` from `@pipecat-ai/voice-ui-kit`) so the
+  UI agent binds to the exact same client instance without relying on
+  React-context identity.
+</ParamField>
+
 ## PipecatClientAudio
 
 Creates a new `<audio>` element that mounts the bot's audio track.
diff --git a/api-reference/client/react/hooks.mdx b/api-reference/client/react/hooks.mdx
index 4202c8a5..bde9f725 100644
--- a/api-reference/client/react/hooks.mdx
+++ b/api-reference/client/react/hooks.mdx
@@ -254,3 +254,302 @@ Programmatically inject a message into the conversation.
 <ParamField path="botOutputSupported" type="boolean | null">
 Whether the connected bot supports BotOutput events (RTVI 1.1.0+). `null` means detection hasn't completed yet.
 </ParamField>
+
+## UI Agent hooks
+
+These hooks require an ambient
+[`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider).
+
+### useUIAgentClient
+
+Returns the [`UIAgentClient`](/api-reference/client/js/ui-agent-client) from
+the ambient `UIAgentProvider`, or `undefined` if the provider is not mounted
+or the Pipecat client has not been initialized yet.
+
+```tsx
+import { useUIAgentClient } from "@pipecat-ai/client-react";
+
+function Diagnostics() {
+  const ui = useUIAgentClient();
+  // Escape hatch: call low-level methods directly.
+  return <button onClick={() => ui?.sendEvent("ping")}>Ping</button>;
+}
+```
+
+**Returns**
+
+<ParamField path="client" type="UIAgentClient | undefined">
+  The active `UIAgentClient`, or `undefined` while the underlying client is
+  not yet initialized.
+</ParamField>
+
+### useUIEventSender
+
+Returns a callable that sends a named UI event to the server. The returned
+function is a no-op until a `UIAgentClient` is available.
+
+```tsx
+import { useUIEventSender } from "@pipecat-ai/client-react";
+
+function NavLink({ view, label }: { view: string; label: string }) {
+  const sendEvent = useUIEventSender();
+  return <a onClick={() => sendEvent("nav_click", { view })}>{label}</a>;
+}
+```
+
+**Returns**
+
+<ParamField path="sendEvent" type="<T>(name: string, payload?: T) => void">
+  Function that emits a UI event with the given name and optional payload.
+</ParamField>
+
+### useUICommandHandler
+
+Register a handler for a named UI command. The handler is registered on
+mount and unregistered on unmount; if the handler reference changes between
+renders, the registration is refreshed. Pass a stable reference (via
+`useCallback`) to avoid per-render churn.
+
+```tsx
+import { useCallback } from "react";
+import { useUICommandHandler } from "@pipecat-ai/client-react";
+
+function Toaster() {
+  const onToast = useCallback((payload: { title: string }) => {
+    showToast(payload.title);
+  }, []);
+  useUICommandHandler("toast", onToast);
+  return null;
+}
+```
+
+**Arguments**
+
+<ParamField path="name" type="string" required>
+  App-defined command name, matching what the server emits via
+  `UIAgent.send_command`.
+</ParamField>
+
+<ParamField path="handler" type="UICommandHandler<T>" required>
+  Callback invoked with the command payload.
+</ParamField>
+
+### useA11ySnapshot
+
+Capture a structured accessibility snapshot of the document and stream it
+to the server as a reserved UI event (`__ui_snapshot`). The server-side
+[`UIAgent`](/api-reference/pipecat-subagents/ui-agent) stores the latest
+snapshot and renders it into LLM context as `<ui_state>` so the agent can
+reason about what's on screen.
+
+Call once near the root of your app, inside a `UIAgentProvider`. This hook
+is a thin lifecycle wrapper around the framework-agnostic
+[`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot#a11ysnapshotstreamer);
+non-React apps can instantiate the streamer directly.
+
+```tsx
+import { useA11ySnapshot } from "@pipecat-ai/client-react";
+
+function App() {
+  useA11ySnapshot();
+  return <Routes>...</Routes>;
+}
+```
+
+**Behaviour**
+
+- Emits an initial snapshot shortly after mount.
+- Re-emits on DOM mutations, ARIA attribute changes, focus changes,
+  scroll-end, window resize, and tab visibility change, coalesced by
+  `debounceMs`.
+- No-op until a `UIAgentClient` is available from the ambient
+  `UIAgentProvider`.
+
+**Options**
+
+<ParamField path="enabled" type="boolean" default="true">
+  Whether the hook is active. Set to `false` to stop emitting snapshots
+  without unmounting the component.
+</ParamField>
+
+<ParamField path="debounceMs" type="number" default="300">
+  Minimum interval between snapshot emissions, in milliseconds.
+</ParamField>
+
+<ParamField path="trackViewport" type="boolean" default="true">
+  When `true`, annotate every emitted node with `"offscreen"` in its `state`
+  list if its bounding rect sits entirely outside the viewport.
+</ParamField>
+
+<ParamField path="logSnapshots" type="boolean" default="false">
+  When `true`, log each emitted snapshot to the browser console (node count,
+  rough token estimate, raw tree).
+</ParamField>
+
+### useStandardScrollToHandler
+
+Install the default `scroll_to` handler: `scrollIntoView` on the resolved
+target. Resolves by snapshot `ref` first, then falls back to
+`document.getElementById(target_id)`.
+
+```tsx
+import { useStandardScrollToHandler } from "@pipecat-ai/client-react";
+
+function App() {
+  useStandardScrollToHandler({
+    block: "center",
+    container: () => document.querySelector(".main"),
+  });
+  return <...>;
+}
+```
+
+**Options**
+
+<ParamField path="block" type='"start" | "center" | "end" | "nearest"' default='"start"'>
+  `scrollIntoView` block position.
+</ParamField>
+
+<ParamField path="inline" type='"start" | "center" | "end" | "nearest"' default='"nearest"'>
+  `scrollIntoView` inline position.
+</ParamField>
+
+<ParamField path="defaultBehavior" type='"auto" | "instant" | "smooth"' default='"smooth"'>
+  Fallback scroll behavior when `payload.behavior` is unset.
+</ParamField>
+
+<ParamField path="container" type="Element | null | (() => Element | null | undefined)">
+  When set, scroll *inside* this element instead of relying on
+  `scrollIntoView` walking to the nearest scrollable ancestor. Function form
+  is evaluated on each scroll so it can account for containers mounted
+  after the hook.
+</ParamField>
+
+<ParamField path="offset" type="{ top?: number; left?: number }">
+  Pixel offsets applied after scrolling, typically to clear a sticky header.
+  Only applied when `container` is set.
+</ParamField>
+
+### useStandardFocusHandler
+
+Install the default `focus` handler: `.focus()` on the resolved target.
+
+```tsx
+import { useStandardFocusHandler } from "@pipecat-ai/client-react";
+useStandardFocusHandler({ preventScroll: true });
+```
+
+**Options**
+
+<ParamField path="preventScroll" type="boolean" default="false">
+  Pass `{ preventScroll: true }` to `element.focus()` so the focus change
+  doesn't also pan the viewport. Useful when focus happens alongside an
+  explicit `scroll_to`.
+</ParamField>
+
+### useStandardHighlightHandler
+
+Install the default `highlight` handler: toggle a CSS class on the resolved
+target for `duration_ms`. Apps style the class themselves, e.g.
+
+```css
+.ui-highlight {
+  outline: 2px solid gold;
+  transition: outline 0.25s;
+}
+```
+
+```tsx
+import { useStandardHighlightHandler } from "@pipecat-ai/client-react";
+
+useStandardHighlightHandler({
+  className: "ui-highlight",
+  defaultDurationMs: 2000,
+  scrollIntoViewFirst: true,
+});
+```
+
+**Options**
+
+<ParamField path="className" type="string" default='"ui-highlight"'>
+  CSS class toggled on the target for `duration_ms`.
+</ParamField>
+
+<ParamField path="defaultDurationMs" type="number" default="1500">
+  Fallback duration when `payload.duration_ms` is missing.
+</ParamField>
+
+<ParamField path="scrollIntoViewFirst" type="boolean" default="false">
+  When `true`, the target is scrolled into view before the class is applied,
+  so the flash is visible to the user even if the target is currently
+  offscreen.
+</ParamField>
+
+### useStandardCommandHandlers
+
+Install all DOM-based default handlers (`scroll_to`, `focus`, `highlight`)
+at once. Pass per-handler option objects to customize.
+
+```tsx
+import { useStandardCommandHandlers } from "@pipecat-ai/client-react";
+
+useStandardCommandHandlers({
+  scrollTo: { block: "center" },
+  highlight: { defaultDurationMs: 2000 },
+});
+```
+
+**Options**
+
+<ParamField path="scrollTo" type="StandardScrollToOptions">
+  Forwarded to `useStandardScrollToHandler`.
+</ParamField>
+
+<ParamField path="focus" type="StandardFocusOptions">
+  Forwarded to `useStandardFocusHandler`.
+</ParamField>
+
+<ParamField path="highlight" type="StandardHighlightOptions">
+  Forwarded to `useStandardHighlightHandler`.
+</ParamField>
+
+### useToastHandler
+
+Typed sugar for `useUICommandHandler<ToastPayload>("toast", handler)`. Wire
+a toast renderer of your choice; the SDK doesn't ship one.
+
+```tsx
+import { useToastHandler } from "@pipecat-ai/client-react";
+import { useCallback } from "react";
+
+useToastHandler(useCallback((payload) => {
+  myToastLib.show(payload.title, payload.subtitle);
+}, []));
+```
+
+**Arguments**
+
+<ParamField path="handler" type="UICommandHandler<ToastPayload>" required />
+
+### useNavigateHandler
+
+Typed sugar for `useUICommandHandler<NavigatePayload>("navigate", handler)`.
+Wire into your router of choice; the SDK doesn't ship one.
+
+```tsx
+import { useNavigateHandler } from "@pipecat-ai/client-react";
+import { useCallback } from "react";
+import { useNavigate } from "react-router-dom";
+
+function NavWiring() {
+  const navigate = useNavigate();
+  useNavigateHandler(useCallback((payload) => {
+    navigate(`/${payload.view}`, { state: payload.params });
+  }, [navigate]));
+  return null;
+}
+```
+
+**Arguments**
+
+<ParamField path="handler" type="UICommandHandler<NavigatePayload>" required />
diff --git a/api-reference/pipecat-subagents/decorators.mdx b/api-reference/pipecat-subagents/decorators.mdx
index 8bf05bc9..1909c50d 100644
--- a/api-reference/pipecat-subagents/decorators.mdx
+++ b/api-reference/pipecat-subagents/decorators.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Decorators"
-description: "@tool, @task, and @agent_ready decorators"
+description: "@tool, @task, @agent_ready, and @on_ui_event decorators"
 ---
 
 ## @tool
@@ -136,3 +136,51 @@ Agent-ready handler methods receive an [`AgentReadyData`](/api-reference/pipecat
 async def on_worker_ready(self, data: AgentReadyData) -> None:
     print(f"Agent {data.agent_name} is ready on runner {data.runner}")
 ```
+
+## @on_ui_event
+
+Mark an agent method as a handler for a named UI event.
+
+On [`UIAgent`](/api-reference/pipecat-subagents/ui-agent) subclasses,
+decorated methods are automatically dispatched when a
+[`BusUIEventMessage`](/api-reference/pipecat-subagents/messages#busuieventmessage)
+with a matching `name` arrives. Each handler runs in its own asyncio task so
+the bus dispatcher is never held open while the handler awaits downstream
+work.
+
+```python
+from pipecat_subagents.agents import on_ui_event
+```
+
+```python
+class MyUIAgent(UIAgent):
+    @on_ui_event("nav_click")
+    async def on_nav(self, message):
+        view = message.payload.get("view")
+        ...
+```
+
+### Parameters
+
+<ParamField path="name" type="str" required>
+  The UI event name to match. Must match the `name` argument the client
+  passes to `UIAgentClient.sendEvent(name, payload)`.
+</ParamField>
+
+### Method Signature
+
+`@on_ui_event` handler methods receive a
+[`BusUIEventMessage`](/api-reference/pipecat-subagents/messages#busuieventmessage):
+
+```python
+@on_ui_event("track_played")
+async def on_track_played(self, message: BusUIEventMessage):
+    track_id = message.payload.get("track_id")
+    ...
+```
+
+<Note>
+  Two handlers cannot share the same event name on the same class. Defining a
+  duplicate raises `ValueError` at agent instantiation time. Subclasses can
+  override a base-class handler by redeclaring the method with the same name.
+</Note>
diff --git a/api-reference/pipecat-subagents/messages.mdx b/api-reference/pipecat-subagents/messages.mdx
index ee8fe31b..ef6a3872 100644
--- a/api-reference/pipecat-subagents/messages.mdx
+++ b/api-reference/pipecat-subagents/messages.mdx
@@ -193,3 +193,92 @@ All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 | `target`  | `str | None` | `None`  | Requester agent name                                                   |
 | `task_id` | `str`        |         | The task identifier                                                    |
 | `data`    | `dict | None` | `None`  | Stream metadata (start), chunk payload (data), or final metadata (end) |
+
+## UI Messages
+
+| Type                   | Priority | Description                                               |
+| ---------------------- | -------- | --------------------------------------------------------- |
+| `BusUIEventMessage`    | Data     | UI event sent from the client to a server-side `UIAgent`  |
+| `BusUICommandMessage`  | Data     | UI command sent from a `UIAgent` to the client            |
+
+### BusUIEventMessage
+
+Emitted by [`attach_ui_bridge`](#attach-ui-bridge) when the client dispatches
+an event via `UIAgentClient.sendEvent(name, payload)`.
+[`UIAgent`](/api-reference/pipecat-subagents/ui-agent) subclasses dispatch
+these to [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event)
+handlers.
+
+| Field        | Type         | Default | Description                            |
+| ------------ | ------------ | ------- | -------------------------------------- |
+| `source`     | `str`        |         | Sending component (the bridge)         |
+| `target`     | `str | None` | `None`  | Recipient agent name (None broadcasts) |
+| `event_name` | `str`        | `""`    | App-defined event name                 |
+| `payload`    | `Any`        | `None`  | App-defined payload. Schemaless.       |
+
+### BusUICommandMessage
+
+Published by
+[`UIAgent.send_command`](/api-reference/pipecat-subagents/ui-agent#send-command).
+The bridge installed by `attach_ui_bridge` translates this to an
+`RTVIServerMessageFrame` with `data == {"type": "ui.command", "name":
+command_name, "payload": payload}` and pushes it through the root agent's
+pipeline for RTVI to deliver to the client.
+
+| Field          | Type         | Default | Description                                                |
+| -------------- | ------------ | ------- | ---------------------------------------------------------- |
+| `source`       | `str`        |         | Sending agent name                                         |
+| `target`       | `str | None` | `None`  | Recipient agent name (None broadcasts)                     |
+| `command_name` | `str`        | `""`    | App-defined command name                                   |
+| `payload`      | `Any`        | `None`  | Plain dict by the time it lands on the bus (see `send_command`) |
+
+### Constants
+
+```python
+from pipecat_subagents.bus import (
+    UI_EVENT_MESSAGE_TYPE,
+    UI_COMMAND_MESSAGE_TYPE,
+    UI_SNAPSHOT_EVENT_NAME,
+)
+```
+
+| Constant                  | Value             | Description                                                                                          |
+| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `UI_EVENT_MESSAGE_TYPE`   | `"ui.event"`      | RTVI client-message type carrying UI events. The bridge filters on this before republishing on the bus. |
+| `UI_COMMAND_MESSAGE_TYPE` | `"ui.command"`    | Discriminator written into the `RTVIServerMessageFrame` `data` field for UI commands. Client dispatchers filter on this. |
+| `UI_SNAPSHOT_EVENT_NAME`  | `"__ui_snapshot"` | Reserved `event_name` carrying an accessibility snapshot. `UIAgent` stores the payload without dispatch or `<ui_event>` injection. |
+
+## attach_ui_bridge
+
+```python
+def attach_ui_bridge(agent: BaseAgent, *, target: str | None = None) -> None
+```
+
+Wire the root agent's pipeline to the UI Agent SDK wire protocol. Call this
+from the root agent's `on_ready` hook. The root agent's pipeline task must be
+built with `enable_rtvi=True`.
+
+```python
+from pipecat_subagents.agents.ui_bridge import attach_ui_bridge
+
+class RootAgent(BaseAgent):
+    async def on_ready(self) -> None:
+        await super().on_ready()
+        attach_ui_bridge(self)
+```
+
+Side effects:
+
+- Registers an `on_client_message` handler on RTVI. Messages whose `type`
+  matches `UI_EVENT_MESSAGE_TYPE` are republished as `BusUIEventMessage`;
+  all other client messages pass through untouched.
+- Registers an `on_bus_message` handler on `agent`. When a
+  `BusUICommandMessage` arrives, the bridge pushes an `RTVIServerMessageFrame`
+  downstream so RTVI delivers it to the client.
+
+| Parameter | Type         | Default | Description                                                                                                                                |
+| --------- | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent`   | `BaseAgent`  |         | The root agent owning the pipeline task and RTVI processor.                                                                                |
+| `target`  | `str | None` | `None`  | Optional target agent name for the republished `BusUIEventMessage`. When `None`, the message is broadcast to every `UIAgent` on the bus. |
+
+**Raises:** `RuntimeError` if the agent's pipeline task has no RTVI processor.
diff --git a/api-reference/pipecat-subagents/overview.mdx b/api-reference/pipecat-subagents/overview.mdx
index 3a4254a0..dd5101d9 100644
--- a/api-reference/pipecat-subagents/overview.mdx
+++ b/api-reference/pipecat-subagents/overview.mdx
@@ -57,6 +57,34 @@ uv add "pipecat-ai-subagents[websocket]"
   >
     Agent with Pipecat Flows integration for structured conversations
   </Card>
+  <Card
+    title="UIAgent"
+    icon="window"
+    href="/api-reference/pipecat-subagents/ui-agent"
+  >
+    LLM agent that dispatches UI events and reasons about what's on screen
+  </Card>
+  <Card
+    title="UI Tools"
+    icon="hand-pointer"
+    href="/api-reference/pipecat-subagents/ui-tools"
+  >
+    Opt-in tool mixins for `UIAgent` (`scroll_to`, `highlight`)
+  </Card>
+  <Card
+    title="UI Commands"
+    icon="bolt"
+    href="/api-reference/pipecat-subagents/ui-commands"
+  >
+    Built-in command vocabulary for `UIAgent.send_command`
+  </Card>
+  <Card
+    title="UI Prompts"
+    icon="pencil"
+    href="/api-reference/pipecat-subagents/ui-prompts"
+  >
+    Canonical prompt fragments describing the UI agent wire format
+  </Card>
 </CardGroup>
 
 ### Infrastructure
@@ -133,5 +161,6 @@ uv add "pipecat-ai-subagents[websocket]"
 | [`BaseAgent`](/api-reference/pipecat-subagents/base-agent)                                             | -           | Core agent with lifecycle, bus, and task coordination |
 | [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent)                                               | `BaseAgent` | Adds LLM pipeline and `@tool` registration            |
 | [`FlowsAgent`](/api-reference/pipecat-subagents/flows-agent)                                           | `BaseAgent` | Adds Pipecat Flows integration                        |
+| [`UIAgent`](/api-reference/pipecat-subagents/ui-agent)                                                 | `LLMAgent`  | Adds UI event dispatch and accessibility snapshot reasoning |
 | [`WebSocketProxyClientAgent`](/api-reference/pipecat-subagents/proxy-agents#websocketproxyclientagent) | `BaseAgent` | Forwards bus messages to a remote server              |
 | [`WebSocketProxyServerAgent`](/api-reference/pipecat-subagents/proxy-agents#websocketproxyserveragent) | `BaseAgent` | Receives bus messages from a remote client            |
diff --git a/api-reference/pipecat-subagents/ui-agent.mdx b/api-reference/pipecat-subagents/ui-agent.mdx
new file mode 100644
index 00000000..cebc2abc
--- /dev/null
+++ b/api-reference/pipecat-subagents/ui-agent.mdx
@@ -0,0 +1,318 @@
+---
+title: "UIAgent"
+description: "LLM agent that dispatches UI events from the client and reasons about what's on screen"
+---
+
+## Overview
+
+`UIAgent` extends [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent) with a UI-aware loop:
+
+- **UI events** sent from the client via `UIAgentClient.sendEvent(name, payload)` are dispatched to methods marked with [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event), and (by default) appended to the LLM context as `<ui_event name="...">payload</ui_event>` developer messages.
+- **Accessibility snapshots** captured by the client's a11y walker arrive on a reserved event name and are stored as the latest `<ui_state>`. By default, the snapshot is auto-injected into the LLM context at the start of every task request, so the agent always reasons over the current screen.
+- **UI commands** flow back the other way via `send_command(name, payload)`. The bridge installed by [`attach_ui_bridge`](/api-reference/pipecat-subagents/messages#attach-ui-bridge) translates each command into an `RTVIServerMessageFrame`; the client's `UIAgentClient` dispatches by name to a registered handler.
+
+```python
+from pipecat_subagents.agents import UIAgent, on_ui_event
+```
+
+```python
+class MyUIAgent(UIAgent):
+    def build_llm(self) -> LLMService:
+        return OpenAILLMService(
+            api_key="...",
+            system_instruction=f"You are a UI agent.\n\n{UI_STATE_PROMPT_GUIDE}",
+        )
+
+    @on_ui_event("nav_click")
+    async def on_nav(self, message):
+        view = message.payload.get("view")
+        ...
+```
+
+<Note>
+  Apps opt in to LLM tools via mixins
+  ([`ScrollToToolMixin`](/api-reference/pipecat-subagents/ui-tools#scrolltotoolmixin),
+  [`HighlightToolMixin`](/api-reference/pipecat-subagents/ui-tools#highlighttoolmixin)).
+  Inherit alongside `UIAgent` to expose them to the LLM.
+</Note>
+
+## Configuration
+
+Inherits all parameters from [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent#configuration).
+
+<ParamField path="name" type="str" required>
+  Unique name for this agent.
+</ParamField>
+
+<ParamField path="bus" type="AgentBus" required>
+  The [`AgentBus`](/api-reference/pipecat-subagents/bus#agentbus) for
+  inter-agent communication.
+</ParamField>
+
+<ParamField path="active" type="bool" default="False">
+  Whether the agent starts active. Defaults to `False`, matching `LLMAgent`.
+</ParamField>
+
+<ParamField path="bridged" type="tuple[str, ...] | None" default="None">
+  Bridge configuration. See
+  [`BaseAgent`](/api-reference/pipecat-subagents/base-agent#configuration) for
+  details.
+</ParamField>
+
+<ParamField path="inject_events" type="bool" default="True">
+  When `True`, every UI event received is appended to the LLM context as a
+  `<ui_event name="...">payload</ui_event>` developer message before the
+  matching `@on_ui_event` handler (if any) runs. Override
+  [`render_ui_event`](#render-ui-event) to customize the rendered string, or
+  set this to `False` to disable injection entirely.
+</ParamField>
+
+<ParamField path="auto_inject_ui_state" type="bool" default="True">
+  When `True`, the latest `<ui_state>` snapshot is appended to the LLM context
+  at the start of every task request, so the agent always reasons over the
+  current screen. Set to `False` to call [`inject_ui_state`](#inject-ui-state)
+  yourself.
+</ParamField>
+
+<ParamField path="log_snapshots" type="bool" default="False">
+  When `True`, emit a `logger.debug` line on every accessibility snapshot
+  received: node count, rendered size, rough token estimate, and the full
+  rendered `<ui_state>` text. Useful in dev / staging for eyeballing what the
+  LLM will see.
+</ParamField>
+
+## Properties
+
+Inherits all properties from
+[`LLMAgent`](/api-reference/pipecat-subagents/llm-agent#properties).
+
+### current_task
+
+```python
+agent.current_task -> BusTaskRequestMessage | None
+```
+
+The task this agent is currently processing, or `None` when idle. Set when
+[`on_task_request`](#on-task-request) runs and cleared by
+[`respond_to_task`](#respond-to-task). Lets `@tool` methods inspect the
+in-flight task without threading the message through every call.
+
+## Abstract Methods
+
+### build_llm
+
+```python
+@abstractmethod
+def build_llm(self) -> LLMService
+```
+
+Return the LLM service for this agent. Same contract as
+[`LLMAgent.build_llm`](/api-reference/pipecat-subagents/llm-agent#build-llm).
+
+**Returns:** An `LLMService` instance.
+
+## Lifecycle Hooks
+
+### on_bus_message
+
+```python
+async def on_bus_message(self, message: BusMessage) -> None
+```
+
+Override of `BaseAgent.on_bus_message` that dispatches UI events alongside
+base lifecycle handling.
+
+When a [`BusUIEventMessage`](/api-reference/pipecat-subagents/messages#busuieventmessage)
+arrives:
+
+1. The reserved [`UI_SNAPSHOT_EVENT_NAME`](/api-reference/pipecat-subagents/messages#ui-snapshot-event-name)
+   updates the stored snapshot and returns. No `<ui_event>` injection, no
+   handler dispatch.
+2. Other events trigger context injection followed by handler dispatch: a
+   `<ui_event>` developer message is appended to the LLM context (when
+   `inject_events=True`), then the matching
+   [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event)
+   handler (if any) runs in its own asyncio task.
+
+Always call `super()` when overriding so base lifecycle handling continues
+to run.
+
+### on_task_request
+
+```python
+async def on_task_request(self, message: BusTaskRequestMessage) -> None
+```
+
+Override of `BaseAgent.on_task_request` that records the in-flight task on
+[`current_task`](#current-task) for [`respond_to_task`](#respond-to-task) to
+close out, then auto-injects the latest `<ui_state>` so the agent reasons
+over the current screen.
+
+Disable the snapshot injection via `auto_inject_ui_state=False` if your app
+wants to drive injection manually (e.g. inject only on specific task names).
+Task tracking happens regardless.
+
+| Parameter | Type                                                                              | Description                              |
+| --------- | --------------------------------------------------------------------------------- | ---------------------------------------- |
+| `message` | [`BusTaskRequestMessage`](/api-reference/pipecat-subagents/messages#bustaskrequestmessage) | The incoming task request from the bus. |
+
+## Methods
+
+### respond_to_task
+
+```python
+async def respond_to_task(
+    self,
+    response: dict | None = None,
+    *,
+    speak: str | None = None,
+    status: TaskStatus = TaskStatus.COMPLETED,
+) -> None
+```
+
+Complete the in-flight task this agent is processing.
+
+Convenience wrapper around `send_task_response` that looks up the current
+task from [`current_task`](#current-task) so `@tool` methods don't have to
+thread the `task_id` through every call. Clears `current_task` after the
+response is sent, so a second call is a no-op.
+
+`speak` is the convention the SDK demos use for "text the voice agent
+should hand verbatim to TTS." When provided, it's merged into the
+response dict as `{"speak": speak}`. Apps that don't follow the convention
+can pass a fully formed `response` dict and leave `speak` unset.
+
+No-op when there is no task in flight (e.g. the tool was invoked outside a
+task dispatch).
+
+| Parameter  | Type                                                                | Default     | Description                                                                                                                                  |
+| ---------- | ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `response` | `dict | None`                                                       | `None`      | Result data dict. Merged with the `speak` key when `speak` is provided.                                                                      |
+| `speak`    | `str | None`                                                        | `None`      | Optional short text for verbatim TTS. Omit (or pass `None`) to leave the response without a `speak` key — the voice agent stays silent for the turn. |
+| `status`   | [`TaskStatus`](/api-reference/pipecat-subagents/types#taskstatus)   | `COMPLETED` | Completion status.                                                                                                                            |
+
+```python
+@tool
+async def navigate_to_artist(self, params, name: str):
+    await self.send_command("navigate", Navigate(view=f"/artist/{name}"))
+    await self.respond_to_task(speak=f"Showing {name}.")
+    await params.result_callback(None)
+```
+
+### send_command
+
+```python
+async def send_command(self, name: str, payload: Any = None) -> None
+```
+
+Send a named UI command to the client. Publishes a
+[`BusUICommandMessage`](/api-reference/pipecat-subagents/messages#busuicommandmessage),
+which `attach_ui_bridge` translates into an `RTVIServerMessageFrame` for the
+RTVI processor to deliver to the client. Client-side handlers registered via
+`registerCommandHandler` (or one of the `useStandard*Handler` hooks) dispatch
+on the command name.
+
+| Parameter | Type            | Default | Description                                                                                  |
+| --------- | --------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `name`    | `str`           |         | App-defined command name (e.g. `"toast"`, `"navigate"`, or any app-specific name). |
+| `payload` | `Any`           | `None`  | Dataclass instance, dict, or `None`. See below.                                              |
+
+`payload` is normalized before sending:
+
+- **Dataclass instance** (including the built-ins in
+  [`pipecat_subagents.agents.ui_commands`](/api-reference/pipecat-subagents/ui-commands)):
+  converted to a plain dict via `dataclasses.asdict`.
+- **`dict`**: forwarded as-is.
+- **`None`**: forwarded as an empty dict.
+
+```python
+from pipecat_subagents.agents.ui_commands import Toast, Navigate
+
+await self.send_command("toast", Toast(title="Saved"))
+await self.send_command("navigate", Navigate(view="settings"))
+await self.send_command("custom", {"foo": "bar"})
+```
+
+### render_ui_state
+
+```python
+def render_ui_state(self) -> str
+```
+
+Render the latest accessibility snapshot as a `<ui_state>` block.
+
+Produces Playwright-MCP-style indented text with stable element refs. Each
+line is `- role "name" [level=N] [cols=N] [rows=N] [state] [ref=eN]`, with
+children nested one indent deeper. Returns an empty string if no snapshot has
+been received yet.
+
+Override to customize the rendered form (different formatting, additional
+metadata, alternate truncation).
+
+```
+<ui_state>
+- generic [ref=e1]:
+  - main [ref=e2]:
+    - heading "Trending artists" [level=2] [ref=e5]
+    - region "New releases" [cols=4] [ref=e12]:
+      - button "Veils" [ref=e18]
+      - button "Vanessa Carlton" [offscreen] [ref=e19]
+</ui_state>
+```
+
+**Returns:** The rendered `<ui_state>` string, or empty string when no
+snapshot is available.
+
+### inject_ui_state
+
+```python
+async def inject_ui_state(self) -> None
+```
+
+Append the latest `<ui_state>` block to the LLM context as a developer
+message. No-op when no snapshot has been received. The frame is queued with
+`run_llm=False` so the snapshot is treated as context, not a user turn.
+
+Apps with `auto_inject_ui_state=True` (the default) get this for free at the
+start of every task. Call this manually only when you want extra injections
+between tasks (e.g. inside an `@on_ui_event` handler that performs a chain of
+work).
+
+### visible_nodes
+
+```python
+def visible_nodes(self) -> list[dict[str, Any]]
+```
+
+Return the snapshot nodes the user is currently looking at: a flat list of
+every node whose `state` does not contain `"offscreen"`, in depth-first order
+matching `<ui_state>`.
+
+Useful for code paths that want to reason about visible interactables without
+parsing the rendered text. Returns an empty list when no snapshot has been
+received yet.
+
+**Returns:** Flat list of visible `A11yNode`-shaped dicts.
+
+### render_ui_event
+
+```python
+def render_ui_event(self, message: BusUIEventMessage) -> str
+```
+
+Render a UI event as a string for LLM context injection. Override to
+customize the injected content.
+
+The default wraps the event in a single `<ui_event>` XML tag with a `name`
+attribute and a JSON-encoded payload as inner text:
+
+```
+<ui_event name="nav_click">{"view": "settings"}</ui_event>
+```
+
+| Parameter | Type                                                                                  | Description                                  |
+| --------- | ------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `message` | [`BusUIEventMessage`](/api-reference/pipecat-subagents/messages#busuieventmessage) | The UI event to render.                      |
+
+**Returns:** A string to append to the LLM context as a developer message.
+Return an empty string to skip injection for this event.
diff --git a/api-reference/pipecat-subagents/ui-commands.mdx b/api-reference/pipecat-subagents/ui-commands.mdx
new file mode 100644
index 00000000..e18bf161
--- /dev/null
+++ b/api-reference/pipecat-subagents/ui-commands.mdx
@@ -0,0 +1,90 @@
+---
+title: "UI Commands"
+description: "Built-in command vocabulary for UIAgent.send_command"
+---
+
+## Overview
+
+These dataclasses describe commands that have matching default React handlers
+in `@pipecat-ai/client-react`'s `standardHandlers`. Apps can use them as-is,
+override the client handler to customize rendering, or ignore them entirely
+and define their own command names.
+
+```python
+from pipecat_subagents.agents.ui_commands import (
+    Toast,
+    Navigate,
+    ScrollTo,
+    Highlight,
+    Focus,
+)
+```
+
+[`UIAgent.send_command(name, payload)`](/api-reference/pipecat-subagents/ui-agent#send-command)
+accepts any of these dataclasses directly. `dataclasses.asdict` converts them
+to the plain-dict shape that travels over the wire.
+
+```python
+await self.send_command("toast", Toast(title="Saved", subtitle="Just now"))
+await self.send_command("navigate", Navigate(view="settings"))
+await self.send_command("scroll_to", ScrollTo(ref="e42"))
+```
+
+## Toast
+
+A transient notification surface shown on the client. Apps wire a toast
+renderer of their choice via
+[`useToastHandler`](/api-reference/client/react/hooks#usetoasthandler); the
+SDK doesn't ship one.
+
+| Field         | Type         | Default | Description                                            |
+| ------------- | ------------ | ------- | ------------------------------------------------------ |
+| `title`       | `str`        |         | Required headline.                                     |
+| `subtitle`    | `str | None` | `None`  | Optional second line beneath the title.                |
+| `description` | `str | None` | `None`  | Optional body text.                                    |
+| `image_url`   | `str | None` | `None`  | Optional leading image URL.                            |
+| `duration_ms` | `int | None` | `None`  | Optional dismiss timer. Client default applies when `None`. |
+
+## Navigate
+
+Client-side navigation to a named view. Wire into your router of choice via
+[`useNavigateHandler`](/api-reference/client/react/hooks#usenavigatehandler).
+
+| Field    | Type          | Default | Description                                              |
+| -------- | ------------- | ------- | -------------------------------------------------------- |
+| `view`   | `str`         |         | App-defined view name (route, screen id, tab key, etc.). |
+| `params` | `dict | None` | `None`  | Optional view-specific parameters.                       |
+
+## ScrollTo
+
+Scroll a target element into view.
+
+The client resolves the target by `ref` first (a snapshot ref like `"e42"`
+assigned by the a11y walker), then falls back to `target_id`
+(`document.getElementById`). Supply whichever you have; `ref` is the normal
+choice when acting on a node from `<ui_state>`.
+
+| Field       | Type         | Default | Description                                                                |
+| ----------- | ------------ | ------- | -------------------------------------------------------------------------- |
+| `ref`       | `str | None` | `None`  | Snapshot ref from `<ui_state>`.                                       |
+| `target_id` | `str | None` | `None`  | Element id registered on the client.                                       |
+| `behavior`  | `str | None` | `None`  | Optional behavior hint (`"smooth"` or `"instant"`). Clients may ignore. |
+
+## Highlight
+
+Briefly emphasize a target element (flash, glow, pulse).
+
+| Field         | Type         | Default | Description                                          |
+| ------------- | ------------ | ------- | ---------------------------------------------------- |
+| `ref`         | `str | None` | `None`  | Snapshot ref from `<ui_state>`.                 |
+| `target_id`   | `str | None` | `None`  | Element id registered on the client.                 |
+| `duration_ms` | `int | None` | `None`  | Optional duration in ms. Client default applies when `None`. |
+
+## Focus
+
+Move input focus to a target element.
+
+| Field       | Type         | Default | Description                          |
+| ----------- | ------------ | ------- | ------------------------------------ |
+| `ref`       | `str | None` | `None`  | Snapshot ref from `<ui_state>`. |
+| `target_id` | `str | None` | `None`  | Element id registered on the client. |
diff --git a/api-reference/pipecat-subagents/ui-prompts.mdx b/api-reference/pipecat-subagents/ui-prompts.mdx
new file mode 100644
index 00000000..b4810c8e
--- /dev/null
+++ b/api-reference/pipecat-subagents/ui-prompts.mdx
@@ -0,0 +1,47 @@
+---
+title: "UI Prompts"
+description: "Canonical prompt fragments describing the UI agent wire format"
+---
+
+## Overview
+
+Apps concatenate these constants into their system prompt so the LLM
+understands the `<ui_state>` and `<ui_event>` developer messages the SDK
+injects on its behalf.
+
+```python
+from pipecat_subagents.agents.ui_prompts import UI_STATE_PROMPT_GUIDE
+```
+
+The SDK updates the guide alongside the wire format, so apps get new tags
+and semantics automatically on the next release.
+
+## UI_STATE_PROMPT_GUIDE
+
+```python
+UI_STATE_PROMPT_GUIDE: str
+```
+
+A multi-line string that documents:
+
+- The two SDK-managed message kinds (`<ui_event>` and `<ui_state>`).
+- The Playwright-MCP-style indented format and what each line means.
+- Known state tags (`[focused]`, `[selected]`, `[disabled]`, `[offscreen]`).
+- Grid metadata (`[cols=N]`) and how to compute row/column from the flat
+  reading order.
+- How to resolve position references ("top right", "the third one") against
+  the most recent `<ui_state>` tree.
+
+Use it directly inside an f-string when building your system prompt:
+
+```python
+from pipecat_subagents.agents.ui_prompts import UI_STATE_PROMPT_GUIDE
+
+system_prompt = f"""\
+You are a voice-driven music player agent.
+
+...app-specific tool and behavior instructions...
+
+{UI_STATE_PROMPT_GUIDE}
+"""
+```
diff --git a/api-reference/pipecat-subagents/ui-tools.mdx b/api-reference/pipecat-subagents/ui-tools.mdx
new file mode 100644
index 00000000..31fa7bfd
--- /dev/null
+++ b/api-reference/pipecat-subagents/ui-tools.mdx
@@ -0,0 +1,100 @@
+---
+title: "UI Tools"
+description: "Opt-in tool mixins for UIAgent"
+---
+
+## Overview
+
+Tool mixins expose focused LLM tools that work with the v1 UI protocol. Apps
+compose them by inheriting alongside their `UIAgent` subclass:
+
+```python
+from pipecat_subagents.agents import UIAgent
+from pipecat_subagents.agents.ui_tools import (
+    HighlightToolMixin,
+    ScrollToToolMixin,
+)
+
+class MyUIAgent(ScrollToToolMixin, HighlightToolMixin, UIAgent):
+    ...
+```
+
+Keeping these as separate mixins (instead of methods on `UIAgent`) means apps
+opt in to what the LLM sees: a single-screen app with no scrolling shouldn't
+have a `scroll_to` tool cluttering its tool list.
+
+The host class must provide
+[`send_command`](/api-reference/pipecat-subagents/ui-agent#send-command) and
+[`respond_to_task`](/api-reference/pipecat-subagents/ui-agent#respond-to-task)
+(`UIAgent` does both) and must be the target of `@tool` discovery on the LLM
+pipeline.
+
+<Note>
+  The shipped mixin tools are **silent fire-and-forget side effects**. They
+  dispatch a UI command, complete the in-flight task with no `speak` field,
+  and exit. The visual change on the client (the scroll, the highlight) is
+  the user-facing feedback; the voice agent stays quiet for that turn. If
+  you want spoken narration, override the mixin tool and pass a `speak`
+  argument:
+
+  ```python
+  class MyAgent(ScrollToToolMixin, UIAgent):
+      @tool
+      async def scroll_to(self, params, ref: str):
+          await self.send_command("scroll_to", ScrollTo(ref=ref))
+          await self.respond_to_task(speak="Scrolling.")
+          await params.result_callback(None)
+  ```
+</Note>
+
+## ScrollToToolMixin
+
+Exposes a `scroll_to(ref)` tool to the LLM. The LLM is meant to call it
+before acting on elements tagged `[offscreen]` in the current `<ui_state>`.
+
+The tool issues a standard
+[`ScrollTo`](/api-reference/pipecat-subagents/ui-commands#scrollto) command;
+the client's
+[`useStandardScrollToHandler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
+(or any app-defined handler) does the actual scrolling.
+
+### scroll_to
+
+```python
+@tool
+async def scroll_to(self, params: FunctionCallParams, ref: str) -> None
+```
+
+Scroll an element into view by its snapshot ref.
+
+| Parameter | Type                 | Description                                                       |
+| --------- | -------------------- | ----------------------------------------------------------------- |
+| `params`  | `FunctionCallParams` | Framework-provided tool invocation context.                       |
+| `ref`     | `str`                | Ref string from the most recent `<ui_state>` (e.g. `"e42"`). |
+
+## HighlightToolMixin
+
+Exposes a `highlight(ref)` tool to the LLM. Gives the LLM a way to visually
+point at a specific element on screen, e.g. answering "which one is
+Radiohead?" by flashing the tile.
+
+The tool issues a standard
+[`Highlight`](/api-reference/pipecat-subagents/ui-commands#highlight) command;
+the client's
+[`useStandardHighlightHandler`](/api-reference/client/react/hooks#usestandardhighlighthandler)
+(or a custom one) does the actual visual effect.
+
+### highlight
+
+```python
+@tool
+async def highlight(self, params: FunctionCallParams, ref: str) -> None
+```
+
+Briefly flash an element on screen by its snapshot ref. After the flash,
+the element returns to its normal appearance.
+
+| Parameter | Type                 | Description                                                       |
+| --------- | -------------------- | ----------------------------------------------------------------- |
+| `params`  | `FunctionCallParams` | Framework-provided tool invocation context.                       |
+| `ref`     | `str`                | Ref string from the most recent `<ui_state>` (e.g. `"e42"`). |
diff --git a/docs.json b/docs.json
index 8c28938e..aa8021a9 100644
--- a/docs.json
+++ b/docs.json
@@ -172,10 +172,7 @@
         "groups": [
           {
             "group": "Get Started",
-            "pages": [
-              "client/introduction",
-              "client/get-started/quickstart"
-            ]
+            "pages": ["client/introduction", "client/get-started/quickstart"]
           },
           {
             "group": "Core Concepts",
@@ -645,6 +642,15 @@
                   "api-reference/pipecat-subagents/flows-agent"
                 ]
               },
+              {
+                "group": "UI Agent",
+                "pages": [
+                  "api-reference/pipecat-subagents/ui-agent",
+                  "api-reference/pipecat-subagents/ui-tools",
+                  "api-reference/pipecat-subagents/ui-commands",
+                  "api-reference/pipecat-subagents/ui-prompts"
+                ]
+              },
               {
                 "group": "Infrastructure",
                 "pages": [
@@ -681,6 +687,13 @@
                   "api-reference/client/js/client-methods",
                   "api-reference/client/js/callbacks",
                   "api-reference/client/js/errors",
+                  {
+                    "group": "UI Agent",
+                    "pages": [
+                      "api-reference/client/js/ui-agent-client",
+                      "api-reference/client/js/a11y-snapshot"
+                    ]
+                  },
                   {
                     "group": "Transports",
                     "pages": [

From 6c2188cbb9db777b1a0113bf2f893d2d516d2706 Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Sun, 3 May 2026 11:06:22 -0400
Subject: [PATCH 2/4] Refresh UI Agent docs for RTVI 1.3 protocol additions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates the docs to align with the UI Agent Protocol shipped across
pipecat#4407, pipecat-client-web#203, and pipecat-ai-subagents#18.
The wire format moved into pipecat as canonical (5 first-class RTVI
message types, paired Data/Message envelopes, 5 new pipeline frames,
PROTOCOL_VERSION 1.2.0 → 1.3.0); subagents builds the agent
abstractions on top; client-web ships UIAgentClient + React idioms.

Pipecat (server)

- client/rtvi-standard.mdx: bumped version note to 1.3, added a UI
  Agent Protocol section documenting all 5 message types (ui-event,
  ui-snapshot, ui-cancel-task, ui-command, ui-task) with shapes and
  the 8 standard payload models.
- api-reference/server/rtvi/rtvi-processor.mdx: added a UI Agent
  Protocol section documenting the on_ui_message handler and the
  inbound / outbound frame conventions.
- api-reference/server/rtvi/rtvi-observer.mdx: extended the
  frame-translation table for RTVIUICommandFrame and RTVIUITaskFrame.
- api-reference/server/frames/system-frames.mdx: added a RTVI UI
  Frames section documenting all 5 new pipeline frames.

Subagents

- api-reference/pipecat-subagents/ui-agent.mdx: fixed parent class
  (LLMContextAgent), refreshed bridge frame references to
  RTVIUICommandFrame / RTVIUITaskFrame, added keep_history param,
  added 5 action helpers (scroll_to / highlight / select_text /
  click / set_input_value), added user_task_group /
  start_user_task_group / reset_context methods, added
  on_task_cancelled lifecycle hook, documented single-flight task
  lock semantics.
- api-reference/pipecat-subagents/ui-tools.mdx: full rewrite for
  ReplyToolMixin (the prior ScrollToToolMixin / HighlightToolMixin
  documentation no longer matched the source).
- api-reference/pipecat-subagents/ui-commands.mdx: fixed import path
  to point at pipecat (canonical home), added Click, SetInputValue,
  SelectText.
- api-reference/pipecat-subagents/ui-prompts.mdx: fixed import path,
  added <selection> block bullet.
- api-reference/pipecat-subagents/messages.mdx: added 4 task-lifecycle
  bus messages (BusUITaskGroupStartedMessage, BusUITaskUpdateMessage,
  BusUITaskCompletedMessage, BusUITaskGroupCompletedMessage),
  refreshed attach_ui_bridge to reflect the new wiring (subscribes to
  on_ui_message, emits RTVIUICommandFrame / RTVIUITaskFrame), removed
  stale UI_*_MESSAGE_TYPE constants section.
- api-reference/pipecat-subagents/overview.mdx: added LLMContextAgent
  row to the agent hierarchy and fixed UIAgent's parent.
- subagents/learn/ui-agent.mdx: NEW consolidated guide. Sections:
  Why, Architecture, How information flows, Sequence diagram, Action
  vocabulary, Choosing a tool shape, Async tasks and lifecycle, When
  to use, Reference app, API reference. Sourced from the internal
  design doc and the music-player demo.
- subagents/examples/overview.mdx: added a Reference Applications
  section linking pipecat-music-player.
- docs.json: registered subagents/learn/ui-agent in the navigation.

Client (js + react)

- api-reference/client/js/ui-agent-client.mdx: refreshed to RTVI v1.3
  (RTVIEvent.UICommand instead of RTVIEvent.ServerMessage, kebab-case
  wire types), added addTaskListener / removeTaskListener /
  removeAllTaskListeners / cancelTask, added See-also pointers.
- api-reference/client/js/a11y-snapshot.mdx: replaced the dropped
  UI_SNAPSHOT_EVENT_NAME section with A11ySelection shape docs and a
  See-also section noting the streamer dispatches via
  RTVIMessageType.UI_SNAPSHOT.
- api-reference/client/js/client-methods.mdx: added sendRTVIMessage
  section under Messages.
- api-reference/client/react/hooks.mdx: added useStandardSelectTextHandler,
  useStandardSetInputValueHandler, useStandardClickHandler, useUITasks;
  updated useStandardCommandHandlers to reflect that it installs all
  six handlers.
- api-reference/client/react/components.mdx: added UITasksProvider;
  refreshed UIAgentProvider description for RTVIEvent.UICommand /
  RTVIEvent.UITask.

Verified with mint broken-links (no broken links found) and
prettier --write across all touched files.
---
 api-reference/client/js/a11y-snapshot.mdx     |  42 +-
 api-reference/client/js/client-methods.mdx    |  24 +-
 api-reference/client/js/ui-agent-client.mdx   | 114 +++--
 api-reference/client/react/components.mdx     |  33 +-
 api-reference/client/react/hooks.mdx          | 218 ++++++++--
 api-reference/pipecat-subagents/messages.mdx  | 291 +++++++------
 api-reference/pipecat-subagents/overview.mdx  |  17 +-
 api-reference/pipecat-subagents/ui-agent.mdx  | 358 +++++++++++++---
 .../pipecat-subagents/ui-commands.mdx         | 127 ++++--
 .../pipecat-subagents/ui-prompts.mdx          |   8 +-
 api-reference/pipecat-subagents/ui-tools.mdx  | 174 +++++---
 api-reference/server/frames/system-frames.mdx |  75 ++++
 api-reference/server/rtvi/rtvi-observer.mdx   |   5 +
 api-reference/server/rtvi/rtvi-processor.mdx  |  51 ++-
 client/rtvi-standard.mdx                      | 124 +++++-
 docs.json                                     |   1 +
 subagents/examples/overview.mdx               |  74 ++--
 subagents/learn/ui-agent.mdx                  | 390 ++++++++++++++++++
 18 files changed, 1734 insertions(+), 392 deletions(-)
 create mode 100644 subagents/learn/ui-agent.mdx

diff --git a/api-reference/client/js/a11y-snapshot.mdx b/api-reference/client/js/a11y-snapshot.mdx
index 4d521b49..39abdccb 100644
--- a/api-reference/client/js/a11y-snapshot.mdx
+++ b/api-reference/client/js/a11y-snapshot.mdx
@@ -210,26 +210,44 @@ interface A11yNode {
 interface A11ySnapshot {
   root: A11yNode;
   captured_at: number;
+  selection?: A11ySelection;
 }
 ```
 
-Shape of the payload inside a `__ui_snapshot` UI event. A full tree is sent
+Shape of the payload inside a `ui-snapshot` RTVI message. A full tree is sent
 on each update; the server keeps the latest and renders it into
 `<ui_state>...</ui_state>` when an agent injects it.
 
-| Field         | Type       | Description                                                      |
-| ------------- | ---------- | ---------------------------------------------------------------- |
-| `root`        | `A11yNode` | Root of the accessibility tree (usually `document.body`'s node). |
-| `captured_at` | `number`   | Client-side timestamp (ms since epoch) when captured.            |
+| Field         | Type            | Description                                                                                     |
+| ------------- | --------------- | ----------------------------------------------------------------------------------------------- |
+| `root`        | `A11yNode`      | Root of the accessibility tree (usually `document.body`'s node).                                |
+| `captured_at` | `number`        | Client-side timestamp (ms since epoch) when captured.                                           |
+| `selection`   | `A11ySelection` | The user's current text selection, when one exists. Omitted when nothing is selected. Optional. |
 
-### UI_SNAPSHOT_EVENT_NAME
+### A11ySelection
 
 ```typescript
-const UI_SNAPSHOT_EVENT_NAME = "__ui_snapshot";
+interface A11ySelection {
+  ref: string;
+  text: string;
+  start_offset?: number;
+  end_offset?: number;
+}
 ```
 
-Reserved UI event name carrying an accessibility snapshot. The server-side
-`UIAgent` recognizes this name and stores the payload as the latest
-snapshot without dispatching to `@on_ui_event` handlers or injecting a
-`<ui_event>` developer message. Underscore-prefixed to signal SDK-internal
-and avoid colliding with app-defined event names.
+The user's current text selection. Lets the agent ground deictic references like "this paragraph" or "what I selected" against actual on-page content rather than re-asking the user. The server renders this as a `<selection ref="...">...</selection>` block inside `<ui_state>`.
+
+| Field          | Type     | Description                                                                                                                                                                   |
+| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref`          | `string` | Ref of the element carrying the selection. For document selections this is the closest common-ancestor element with a ref; for input/textarea it is the input element itself. |
+| `text`         | `string` | The selected text. Truncated at 2000 characters with a trailing ellipsis to keep `<ui_state>` injections bounded.                                                             |
+| `start_offset` | `number` | Character offset within the input's `value` where the selection starts. Only set for `<input>` and `<textarea>`. Optional.                                                    |
+| `end_offset`   | `number` | Character offset where the selection ends. Only set for `<input>` and `<textarea>`. Optional.                                                                                 |
+
+## See also
+
+- [`UIAgentClient`](/api-reference/client/js/ui-agent-client) — the wrapper the streamer dispatches through.
+- [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot) — React hook idiom.
+- [UI Agent Protocol on the wire](/client/rtvi-standard#ui-snapshot-) — the `ui-snapshot` RTVI message that carries the tree.
+
+The streamer dispatches via `PipecatClient.sendRTVIMessage(RTVIMessageType.UI_SNAPSHOT, { tree })` (RTVI v1.3); apps that build their own snapshot pipeline can target the same wire shape directly without using `UIAgentClient`.
diff --git a/api-reference/client/js/client-methods.mdx b/api-reference/client/js/client-methods.mdx
index 8ba1e39f..42529e03 100644
--- a/api-reference/client/js/client-methods.mdx
+++ b/api-reference/client/js/client-methods.mdx
@@ -84,9 +84,9 @@ During the connection process, the transport state will transition through the f
 
 <Note>
   Calling `connect()` asynchronously will resolve when the bot and client signal
-  that they are ready. If you want to call `connect()` without `await`, you can use the
-  `onBotReady` callback or `BotReady` event to know when you can interact with
-  the bot.
+  that they are ready. If you want to call `connect()` without `await`, you can
+  use the `onBotReady` callback or `BotReady` event to know when you can
+  interact with the bot.
 </Note>
 
 <Warning>
@@ -181,6 +181,24 @@ Sends a custom request to the bot and expects a response. This is useful for que
   type `'error-response'`.
 </ParamField>
 
+### sendRTVIMessage()
+
+`sendRTVIMessage(msgType: RTVIMessageType, data?: unknown): void`
+
+Send a first-class typed RTVI message. Bypasses the `client-message` envelope (which `sendClientMessage` uses) and dispatches the supplied type directly. Used internally by [`UIAgentClient.sendEvent`](/api-reference/client/js/ui-agent-client#sendevent), [`UIAgentClient.cancelTask`](/api-reference/client/js/ui-agent-client#canceltask), and [`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot) to emit `ui-event`, `ui-cancel-task`, and `ui-snapshot` messages respectively.
+
+Available to apps that want to emit a typed RTVI message themselves (e.g. an app-specific subscriber to one of the `ui-*` types, or a future protocol extension).
+
+<ParamField path="msgType" type="RTVIMessageType" required>
+  A member of the `RTVIMessageType` enum (e.g. `RTVIMessageType.UI_EVENT`,
+  `RTVIMessageType.UI_SNAPSHOT`, `RTVIMessageType.UI_CANCEL_TASK`).
+</ParamField>
+
+<ParamField path="data" type="unknown">
+  Optional `data` payload for the message. The shape depends on the `msgType`;
+  see the [RTVI standard](/client/rtvi-standard) for the canonical shapes.
+</ParamField>
+
 ## Devices
 
 ### initDevices()
diff --git a/api-reference/client/js/ui-agent-client.mdx b/api-reference/client/js/ui-agent-client.mdx
index ff2a0016..8b5cb372 100644
--- a/api-reference/client/js/ui-agent-client.mdx
+++ b/api-reference/client/js/ui-agent-client.mdx
@@ -5,25 +5,21 @@ description: "Client-side surface for the UI Agent pattern"
 
 ## Overview
 
-`UIAgentClient` wraps an existing `PipecatClient` with the v1 UI Agent
-protocol:
+`UIAgentClient` wraps an existing `PipecatClient` with the [UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) (RTVI v1.3):
 
-- **`sendEvent(name, payload)`** for client → server events.
-- **`registerCommandHandler(name, handler)`** for server → client commands.
-  Handlers dispatch on the command name extracted from `RTVIEvent.ServerMessage`
-  payloads of type `"ui.command"`.
+- **`sendEvent(name, payload)`** for client → server events. Sends as a first-class `ui-event` RTVI message.
+- **`registerCommandHandler(name, handler)`** for server → client commands. Handlers dispatch on the command name extracted from `RTVIEvent.UICommand` payloads (the `ui-command` envelope).
+- **`addTaskListener(listener)`** for server → client task lifecycle envelopes (`ui-task`). Listeners receive every `group_started` / `task_update` / `task_completed` / `group_completed` envelope in arrival order.
+- **`cancelTask(task_id, reason?)`** to ask the server to cancel an in-flight user task group.
 
-Construction does not subscribe to anything. Call `attach()` to start
-listening for `RTVIEvent.ServerMessage` and store the returned detach
-function to stop. The React provider
-([`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider))
-does this automatically inside a `useEffect` so subscription lifecycle
-follows mount/unmount.
+Construction does not subscribe to anything. Call `attach()` to start listening for `RTVIEvent.UICommand` and `RTVIEvent.UITask`, and store the returned detach function to stop. The React provider ([`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider)) does this automatically inside a `useEffect` so subscription lifecycle follows mount/unmount (including `StrictMode`'s double-invoke).
 
 ```javascript
 import { PipecatClient, UIAgentClient } from "@pipecat-ai/client-js";
 
-const pcClient = new PipecatClient({ /* ... */ });
+const pcClient = new PipecatClient({
+  /* ... */
+});
 const uiClient = new UIAgentClient(pcClient);
 const detach = uiClient.attach();
 
@@ -45,8 +41,8 @@ new UIAgentClient(client: PipecatClient)
 
 <ParamField path="client" type="PipecatClient" required>
   An existing Pipecat client. The UI agent client wraps this without taking
-  ownership; the host is still responsible for connecting and disconnecting
-  the underlying client.
+  ownership; the host is still responsible for connecting and disconnecting the
+  underlying client.
 </ParamField>
 
 ## Properties
@@ -57,8 +53,7 @@ new UIAgentClient(client: PipecatClient)
 get pipecatClient: PipecatClient
 ```
 
-The underlying Pipecat client, exposed as an escape hatch when an app needs
-to call `PipecatClient` methods directly.
+The underlying Pipecat client, exposed as an escape hatch when an app needs to call `PipecatClient` methods directly.
 
 ## Methods
 
@@ -68,9 +63,7 @@ to call `PipecatClient` methods directly.
 sendEvent<T = unknown>(name: string, payload?: T): void
 ```
 
-Send a named UI event to the server. The event is delivered as an RTVI
-client message with type `"ui.event"`; the bridge installed by
-`attach_ui_bridge` republishes it as `BusUIEventMessage` on the bus.
+Send a named UI event to the server as a first-class `ui-event` RTVI message. Internally calls `PipecatClient.sendRTVIMessage(RTVIMessageType.UI_EVENT, ...)`. The server-side bridge installed by `attach_ui_bridge` republishes the event as `BusUIEventMessage` on the agent bus, where matching `@on_ui_event(name)` handlers run.
 
 <ParamField path="name" type="string" required>
   App-defined event name. Must match the `name` argument on a server-side
@@ -90,18 +83,16 @@ registerCommandHandler<T = unknown>(
 ): void
 ```
 
-Register a handler for a named UI command. Overwrites any existing handler
-for the same name.
+Register a handler for a named UI command. Overwrites any existing handler for the same name.
 
 <ParamField path="name" type="string" required>
-  App-defined command name. Must match the `name` argument the server passes
-  to `UIAgent.send_command(name, payload)`.
+  App-defined command name. Must match the `name` argument the server passes to
+  `UIAgent.send_command(name, payload)`.
 </ParamField>
 
 <ParamField path="handler" type="UICommandHandler<T>" required>
   Callback invoked with the command payload. Sync or async; rejected promises
-  surface to the host's unhandled-rejection channel rather than being
-  swallowed.
+  surface to the host's unhandled-rejection channel rather than being swallowed.
 </ParamField>
 
 ### unregisterCommandHandler
@@ -110,8 +101,7 @@ for the same name.
 unregisterCommandHandler(name: string): void
 ```
 
-Remove the handler previously registered for `name`, if any. No-op when no
-handler is registered.
+Remove the handler previously registered for `name`, if any. No-op when no handler is registered.
 
 ### unregisterAllCommandHandlers
 
@@ -121,19 +111,73 @@ unregisterAllCommandHandlers(): void
 
 Remove all registered command handlers.
 
+### addTaskListener
+
+```typescript
+addTaskListener(listener: UITaskListener): void
+```
+
+Subscribe a listener to every `ui-task` envelope. The listener fires for each lifecycle phase: `group_started`, `task_update`, `task_completed`, `group_completed`. Switch on `envelope.kind` to react to specific phases.
+
+The React `useUITasks` hook is the recommended consumer for app code; this lower-level listener is for hosts that want to drive their own state.
+
+<ParamField path="listener" type="UITaskListener" required>
+  Callback invoked once per envelope:
+  `(envelope: UITaskEnvelope) => void`. The discriminated `kind` field
+  (`"group_started"` / `"task_update"` / `"task_completed"` /
+  `"group_completed"`) selects which envelope shape arrived.
+</ParamField>
+
+### removeTaskListener
+
+```typescript
+removeTaskListener(listener: UITaskListener): void
+```
+
+Remove a previously added task listener. No-op when the listener is not registered.
+
+### removeAllTaskListeners
+
+```typescript
+removeAllTaskListeners(): void
+```
+
+Remove every task listener.
+
+### cancelTask
+
+```typescript
+cancelTask(task_id: string, reason?: string): void
+```
+
+Ask the server to cancel an in-flight user task group. Sends a first-class `ui-cancel-task` RTVI message; the server-side `UIAgent` routes this to `cancel_task` on the matching group. The server honors the request only when the group was registered with `cancellable=True`; otherwise the request is silently ignored.
+
+<ParamField path="task_id" type="string" required>
+  The shared task identifier of the group to cancel. Read this from a task
+  group's `taskId` (`useUITasks` surfaces it) or from the `task_id` on any
+  envelope you saw for the group.
+</ParamField>
+
+<ParamField path="reason" type="string">
+  Optional human-readable reason. Logged on the server alongside the cancel
+  request.
+</ParamField>
+
 ### attach
 
 ```typescript
 attach(): () => void
 ```
 
-Subscribe to `RTVIEvent.ServerMessage` on the underlying `PipecatClient`.
-Returns a detach function that unsubscribes.
+Subscribe to `RTVIEvent.UICommand` and `RTVIEvent.UITask` on the underlying `PipecatClient`. Returns a detach function that unsubscribes.
 
-Safe to call more than once: each call installs an independent listener.
-Invoke the returned function to remove that listener. The React provider
-calls this inside `useEffect` and uses the returned function as the cleanup,
-so subscription lifecycle follows React's mount/unmount cycle (including
-`StrictMode`'s double-invoke in development).
+Safe to call more than once: each call installs an independent pair of listeners. Invoke the returned function to remove them. The React provider calls this inside `useEffect` and uses the returned function as the cleanup, so subscription lifecycle follows React's mount/unmount cycle (including `StrictMode`'s double-invoke in development).
 
 **Returns:** A `() => void` detach function.
+
+## See also
+
+- [`PipecatClient.sendRTVIMessage`](/api-reference/client/js/client-methods#sendrtvimessage) — the underlying primitive `sendEvent` and `cancelTask` use to send first-class typed RTVI messages.
+- [`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot) — streams the accessibility tree as `ui-snapshot` messages.
+- [`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider) — React idiom for the same surface.
+- [UI Agent Protocol on the wire](/client/rtvi-standard#ui-agent-protocol) — the underlying RTVI message types.
diff --git a/api-reference/client/react/components.mdx b/api-reference/client/react/components.mdx
index df10be47..68473237 100644
--- a/api-reference/client/react/components.mdx
+++ b/api-reference/client/react/components.mdx
@@ -32,11 +32,7 @@ inside (or alongside) `PipecatClientProvider`. Descendants can then call
 the [`useStandard*Handler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
 hooks.
 
-The provider subscribes to `RTVIEvent.ServerMessage` on the underlying
-Pipecat client to dispatch UI commands. On unmount (or when the underlying
-Pipecat client changes), the subscription is torn down via the detach
-function returned from `client.attach()`, including under `StrictMode`'s
-double-invoke in development.
+The provider subscribes to `RTVIEvent.UICommand` and `RTVIEvent.UITask` on the underlying Pipecat client (the `ui-command` and `ui-task` envelopes). On unmount (or when the underlying Pipecat client changes), the subscription is torn down via the detach function returned from `client.attach()`, including under `StrictMode`'s double-invoke in development.
 
 ```jsx
 <PipecatClientProvider client={pcClient}>
@@ -54,12 +50,31 @@ double-invoke in development.
   `usePipecatClient`. When set, the prop takes precedence and the context
   is ignored.
 
-  Pass this explicitly when the host provides the client via a render prop
-  (for example, `PipecatAppBase` from `@pipecat-ai/voice-ui-kit`) so the
-  UI agent binds to the exact same client instance without relying on
-  React-context identity.
+Pass this explicitly when the host provides the client via a render prop
+(for example, `PipecatAppBase` from `@pipecat-ai/voice-ui-kit`) so the
+UI agent binds to the exact same client instance without relying on
+React-context identity.
+
 </ParamField>
 
+## UITasksProvider
+
+Drives the in-flight task-group state surfaced by [`useUITasks`](/api-reference/client/react/hooks#useuitasks). Subscribes to the `UIAgentClient`'s task-listener channel (every `ui-task` envelope: `group_started`, `task_update`, `task_completed`, `group_completed`) and reduces them into a `groups` array consumers can render.
+
+Mount inside `UIAgentProvider` (the tasks provider depends on the bound `UIAgentClient`). Apps that don't surface in-flight task state to the user can skip this provider; `useUITasks` returns an empty list and a no-op `cancelTask` when no `UITasksProvider` is mounted.
+
+```jsx
+<PipecatClientProvider client={pcClient}>
+  <UIAgentProvider>
+    <UITasksProvider>
+      <App />
+    </UITasksProvider>
+  </UIAgentProvider>
+</PipecatClientProvider>
+```
+
+The provider takes no props.
+
 ## PipecatClientAudio
 
 Creates a new `<audio>` element that mounts the bot's audio track.
diff --git a/api-reference/client/react/hooks.mdx b/api-reference/client/react/hooks.mdx
index bde9f725..e6fc44f3 100644
--- a/api-reference/client/react/hooks.mdx
+++ b/api-reference/client/react/hooks.mdx
@@ -206,14 +206,28 @@ function Messages() {
 
 **Options**
 
-<ParamField path="onMessageCreated" type="(message: ConversationMessage) => void">
-Called once when a new message first enters the conversation. The message may or may not be complete at this point — check `message.final`.
+<ParamField
+  path="onMessageCreated"
+  type="(message: ConversationMessage) => void"
+>
+  Called once when a new message first enters the conversation. The message may
+  or may not be complete at this point — check `message.final`.
 </ParamField>
-<ParamField path="onMessageUpdated" type="(message: ConversationMessage) => void">
-Called whenever an existing message's content changes (e.g. streaming text appended, function call status changed, message finalized). Check `message.final` to detect finalization.
+<ParamField
+  path="onMessageUpdated"
+  type="(message: ConversationMessage) => void"
+>
+  Called whenever an existing message's content changes (e.g. streaming text
+  appended, function call status changed, message finalized). Check
+  `message.final` to detect finalization.
 </ParamField>
-<ParamField path="aggregationMetadata" type="Record<string, AggregationMetadata>">
-Metadata for aggregation types to control rendering and speech progress behavior. Used to determine which aggregations should be excluded from position-based speech splitting.
+<ParamField
+  path="aggregationMetadata"
+  type="Record<string, AggregationMetadata>"
+>
+  Metadata for aggregation types to control rendering and speech progress
+  behavior. Used to determine which aggregations should be excluded from
+  position-based speech splitting.
 </ParamField>
 
 **Returns**
@@ -242,17 +256,25 @@ function TextInput() {
     });
   };
 
-  return <input onKeyDown={(e) => e.key === "Enter" && send(e.currentTarget.value)} />;
+  return (
+    <input
+      onKeyDown={(e) => e.key === "Enter" && send(e.currentTarget.value)}
+    />
+  );
 }
 ```
 
 **Returns**
 
-<ParamField path="injectMessage" type="(message: { role: string; parts: ConversationMessagePart[] }) => void">
-Programmatically inject a message into the conversation.
+<ParamField
+  path="injectMessage"
+  type="(message: { role: string; parts: ConversationMessagePart[] }) => void"
+>
+  Programmatically inject a message into the conversation.
 </ParamField>
 <ParamField path="botOutputSupported" type="boolean | null">
-Whether the connected bot supports BotOutput events (RTVI 1.1.0+). `null` means detection hasn't completed yet.
+  Whether the connected bot supports BotOutput events (RTVI 1.1.0+). `null`
+  means detection hasn't completed yet.
 </ParamField>
 
 ## UI Agent hooks
@@ -279,8 +301,8 @@ function Diagnostics() {
 **Returns**
 
 <ParamField path="client" type="UIAgentClient | undefined">
-  The active `UIAgentClient`, or `undefined` while the underlying client is
-  not yet initialized.
+  The active `UIAgentClient`, or `undefined` while the underlying client is not
+  yet initialized.
 </ParamField>
 
 ### useUIEventSender
@@ -368,8 +390,8 @@ function App() {
 **Options**
 
 <ParamField path="enabled" type="boolean" default="true">
-  Whether the hook is active. Set to `false` to stop emitting snapshots
-  without unmounting the component.
+  Whether the hook is active. Set to `false` to stop emitting snapshots without
+  unmounting the component.
 </ParamField>
 
 <ParamField path="debounceMs" type="number" default="300">
@@ -406,23 +428,37 @@ function App() {
 
 **Options**
 
-<ParamField path="block" type='"start" | "center" | "end" | "nearest"' default='"start"'>
+<ParamField
+  path="block"
+  type='"start" | "center" | "end" | "nearest"'
+  default='"start"'
+>
   `scrollIntoView` block position.
 </ParamField>
 
-<ParamField path="inline" type='"start" | "center" | "end" | "nearest"' default='"nearest"'>
+<ParamField
+  path="inline"
+  type='"start" | "center" | "end" | "nearest"'
+  default='"nearest"'
+>
   `scrollIntoView` inline position.
 </ParamField>
 
-<ParamField path="defaultBehavior" type='"auto" | "instant" | "smooth"' default='"smooth"'>
+<ParamField
+  path="defaultBehavior"
+  type='"auto" | "instant" | "smooth"'
+  default='"smooth"'
+>
   Fallback scroll behavior when `payload.behavior` is unset.
 </ParamField>
 
-<ParamField path="container" type="Element | null | (() => Element | null | undefined)">
-  When set, scroll *inside* this element instead of relying on
-  `scrollIntoView` walking to the nearest scrollable ancestor. Function form
-  is evaluated on each scroll so it can account for containers mounted
-  after the hook.
+<ParamField
+  path="container"
+  type="Element | null | (() => Element | null | undefined)"
+>
+  When set, scroll *inside* this element instead of relying on `scrollIntoView`
+  walking to the nearest scrollable ancestor. Function form is evaluated on each
+  scroll so it can account for containers mounted after the hook.
 </ParamField>
 
 <ParamField path="offset" type="{ top?: number; left?: number }">
@@ -480,15 +516,68 @@ useStandardHighlightHandler({
 </ParamField>
 
 <ParamField path="scrollIntoViewFirst" type="boolean" default="false">
-  When `true`, the target is scrolled into view before the class is applied,
-  so the flash is visible to the user even if the target is currently
-  offscreen.
+  When `true`, the target is scrolled into view before the class is applied, so
+  the flash is visible to the user even if the target is currently offscreen.
+</ParamField>
+
+### useStandardSelectTextHandler
+
+Enable the default `select_text` handler. Resolves the target by ref / target_id and applies the page text selection (`Range.selectNodeContents` for document elements, `el.select()` for `<input>` / `<textarea>`). With `start_offset` / `end_offset` set, walks descendant text nodes to apply a sub-range selection.
+
+```tsx
+import { useStandardSelectTextHandler } from "@pipecat-ai/client-react";
+
+useStandardSelectTextHandler({ scrollIntoViewFirst: true });
+```
+
+**Options**
+
+<ParamField path="scrollIntoViewFirst" type="boolean" default="true">
+  When true, scroll the target into view before applying the selection so the
+  user actually sees what was selected.
+</ParamField>
+
+<ParamField path="block" type="ScrollLogicalPosition" default='"center"'>
+  `scrollIntoView` block position when scrolling first.
+</ParamField>
+
+### useStandardSetInputValueHandler
+
+Enable the default `set_input_value` handler. Resolves the target by ref / target_id; refuses on `disabled`, `readonly`, and `<input type="hidden">` (silent no-op so the agent can't bypass UI affordances the user is meant to control), then assigns `el.value` and dispatches single-shot `input` and `change` events so React-controlled inputs and vanilla `onChange` listeners pick up the new value naturally.
+
+With `replace: false` on the payload, the new text is appended to the current value; the default replaces. The flag is ignored for native `<select>` since a select either has the value or doesn't. Native `<select>` is supported alongside text inputs and textareas (the handler sets `el.value` and dispatches `change`).
+
+```tsx
+import { useStandardSetInputValueHandler } from "@pipecat-ai/client-react";
+
+useStandardSetInputValueHandler({ focusFirst: true });
+```
+
+**Options**
+
+<ParamField path="focusFirst" type="boolean" default="false">
+  When true, fire `focus()` on the target before writing so the user sees the
+  cursor land in the field. The element is blurred after the change events fire
+  to avoid stealing keyboard focus mid-conversation.
 </ParamField>
 
+### useStandardClickHandler
+
+Enable the default `click` handler. Resolves the target by ref / target_id and calls `el.click()`. Silently no-ops on `disabled` and `aria-disabled="true"` targets so the agent can't bypass UI affordances meant to be user-controlled.
+
+```tsx
+import { useStandardClickHandler } from "@pipecat-ai/client-react";
+
+useStandardClickHandler();
+```
+
+Takes no options.
+
 ### useStandardCommandHandlers
 
-Install all DOM-based default handlers (`scroll_to`, `focus`, `highlight`)
-at once. Pass per-handler option objects to customize.
+Install all DOM-based default handlers (`scroll_to`, `focus`, `highlight`,
+`select_text`, `set_input_value`, `click`) at once. Pass per-handler option
+objects to customize.
 
 ```tsx
 import { useStandardCommandHandlers } from "@pipecat-ai/client-react";
@@ -496,6 +585,7 @@ import { useStandardCommandHandlers } from "@pipecat-ai/client-react";
 useStandardCommandHandlers({
   scrollTo: { block: "center" },
   highlight: { defaultDurationMs: 2000 },
+  setInputValue: { focusFirst: true },
 });
 ```
 
@@ -513,6 +603,16 @@ useStandardCommandHandlers({
   Forwarded to `useStandardHighlightHandler`.
 </ParamField>
 
+<ParamField path="selectText" type="StandardSelectTextOptions">
+  Forwarded to `useStandardSelectTextHandler`.
+</ParamField>
+
+<ParamField path="setInputValue" type="StandardSetInputValueOptions">
+  Forwarded to `useStandardSetInputValueHandler`.
+</ParamField>
+
+`useStandardClickHandler` takes no options and is always installed.
+
 ### useToastHandler
 
 Typed sugar for `useUICommandHandler<ToastPayload>("toast", handler)`. Wire
@@ -522,9 +622,11 @@ a toast renderer of your choice; the SDK doesn't ship one.
 import { useToastHandler } from "@pipecat-ai/client-react";
 import { useCallback } from "react";
 
-useToastHandler(useCallback((payload) => {
-  myToastLib.show(payload.title, payload.subtitle);
-}, []));
+useToastHandler(
+  useCallback((payload) => {
+    myToastLib.show(payload.title, payload.subtitle);
+  }, []),
+);
 ```
 
 **Arguments**
@@ -543,9 +645,14 @@ import { useNavigate } from "react-router-dom";
 
 function NavWiring() {
   const navigate = useNavigate();
-  useNavigateHandler(useCallback((payload) => {
-    navigate(`/${payload.view}`, { state: payload.params });
-  }, [navigate]));
+  useNavigateHandler(
+    useCallback(
+      (payload) => {
+        navigate(`/${payload.view}`, { state: payload.params });
+      },
+      [navigate],
+    ),
+  );
   return null;
 }
 ```
@@ -553,3 +660,48 @@ function NavWiring() {
 **Arguments**
 
 <ParamField path="handler" type="UICommandHandler<NavigatePayload>" required />
+
+### useUITasks
+
+Subscribe to the in-flight task-group state surfaced by the server's [`ui-task`](/client/rtvi-standard#ui-task-) lifecycle envelopes. Returns the live list of task groups plus a `cancelTask` method.
+
+Requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside [`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider). The provider listens to `RTVIEvent.UITask` envelopes from the underlying `UIAgentClient` and reduces them into `groups` state.
+
+```tsx
+import { useUITasks } from "@pipecat-ai/client-react";
+
+function DiscoveryPanel() {
+  const { groups, cancelTask } = useUITasks();
+  const inflight = groups.find((g) => g.status === "running");
+  if (!inflight) return null;
+  return (
+    <div>
+      <h3>{inflight.label}</h3>
+      {inflight.cancellable && (
+        <button onClick={() => cancelTask(inflight.taskId, "user requested")}>
+          Cancel
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+**Returns**
+
+<ParamField path="groups" type="TaskGroup[]">
+  Live array of in-flight and recently completed task groups, in arrival order.
+  Each group has `taskId`, `label`, `status` (`"running"` / `"completed"` /
+  `"cancelled"` / `"failed"` / `"error"`), `cancellable`, per-worker entries
+  with status and response, and aggregate `completedCount` / `totalCount`
+  counters.
+</ParamField>
+
+<ParamField path="cancelTask" type="(taskId: string, reason?: string) => void">
+  Ask the server to cancel the named task group. Forwards to
+  [`UIAgentClient.cancelTask`](/api-reference/client/js/ui-agent-client#canceltask).
+  Honored only when the group was registered with `cancellable=True` on the
+  server.
+</ParamField>
+
+When no `UITasksProvider` is mounted, `useUITasks` returns an empty `groups` list and a no-op `cancelTask` rather than throwing.
diff --git a/api-reference/pipecat-subagents/messages.mdx b/api-reference/pipecat-subagents/messages.mdx
index ef6a3872..408362d8 100644
--- a/api-reference/pipecat-subagents/messages.mdx
+++ b/api-reference/pipecat-subagents/messages.mdx
@@ -35,10 +35,10 @@ from pipecat_subagents.bus import (
 
 All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 
-| Field    | Type            | Default | Description                                             |
-| -------- | --------------- | ------- | ------------------------------------------------------- |
-| `source` | `str`           |         | Name of the agent or component that sent this message   |
-| `target` | `str | None` | `None`  | Name of the intended recipient, or `None` for broadcast |
+| Field    | Type  | Default | Description                                           |
+| -------- | ----- | ------- | ----------------------------------------------------- | ------------------------------------------------------- |
+| `source` | `str` |         | Name of the agent or component that sent this message |
+| `target` | `str  | None`   | `None`                                                | Name of the intended recipient, or `None` for broadcast |
 
 ## Frame Transport
 
@@ -49,12 +49,12 @@ All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 ### BusFrameMessage
 
 | Field       | Type             | Default | Description                                                   |
-| ----------- | ---------------- | ------- | ------------------------------------------------------------- |
+| ----------- | ---------------- | ------- | ------------------------------------------------------------- | ---------------------------------------------- |
 | `source`    | `str`            |         | Sending agent name                                            |
-| `target`    | `str | None`     | `None`  | Recipient agent name                                          |
+| `target`    | `str             | None`   | `None`                                                        | Recipient agent name                           |
 | `frame`     | `Frame`          |         | The Pipecat frame to transport                                |
 | `direction` | `FrameDirection` |         | Direction the frame should travel in the recipient's pipeline |
-| `bridge`    | `str | None`     | `None`  | Bridge name for routing in multi-bridge setups                |
+| `bridge`    | `str             | None`   | `None`                                                        | Bridge name for routing in multi-bridge setups |
 
 ## Agent Lifecycle
 
@@ -69,27 +69,27 @@ All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 
 ### BusActivateAgentMessage
 
-| Field    | Type         | Default | Description                                      |
-| -------- | ------------ | ------- | ------------------------------------------------ |
-| `source` | `str`        |         | Sending agent name                               |
-| `target` | `str | None` | `None`  | Agent to activate                                |
-| `args`   | `dict | None` | `None`  | Activation arguments forwarded to `on_activated` |
+| Field    | Type  | Default | Description        |
+| -------- | ----- | ------- | ------------------ | ------------------------------------------------ |
+| `source` | `str` |         | Sending agent name |
+| `target` | `str  | None`   | `None`             | Agent to activate                                |
+| `args`   | `dict | None`   | `None`             | Activation arguments forwarded to `on_activated` |
 
 ### BusEndMessage / BusEndAgentMessage
 
-| Field    | Type        | Default | Description                      |
-| -------- | ----------- | ------- | -------------------------------- |
-| `source` | `str`       |         | Sending agent name               |
-| `target` | `str | None` | `None`  | Recipient agent name             |
-| `reason` | `str | None` | `None`  | Human-readable reason for ending |
+| Field    | Type  | Default | Description        |
+| -------- | ----- | ------- | ------------------ | -------------------------------- |
+| `source` | `str` |         | Sending agent name |
+| `target` | `str  | None`   | `None`             | Recipient agent name             |
+| `reason` | `str  | None`   | `None`             | Human-readable reason for ending |
 
 ### BusCancelMessage / BusCancelAgentMessage
 
-| Field    | Type        | Default | Description                            |
-| -------- | ----------- | ------- | -------------------------------------- |
-| `source` | `str`       |         | Sending agent name                     |
-| `target` | `str | None` | `None`  | Recipient agent name                   |
-| `reason` | `str | None` | `None`  | Human-readable reason for cancellation |
+| Field    | Type  | Default | Description        |
+| -------- | ----- | ------- | ------------------ | -------------------------------------- |
+| `source` | `str` |         | Sending agent name |
+| `target` | `str  | None`   | `None`             | Recipient agent name                   |
+| `reason` | `str  | None`   | `None`             | Human-readable reason for cancellation |
 
 ## Registry & Errors
 
@@ -111,14 +111,14 @@ All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 
 ### BusAgentReadyMessage
 
-| Field        | Type          | Default | Description                                         |
-| ------------ | ------------- | ------- | --------------------------------------------------- |
-| `source`     | `str`         |         | Agent name                                          |
-| `runner`     | `str`         |         | Name of the runner managing this agent              |
-| `parent`     | `str | None`   | `None`  | Name of the parent agent, or `None` for root agents |
-| `active`     | `bool`        | `False` | Whether the agent started active                    |
-| `bridged`    | `bool`        | `False` | Whether the agent is bridged                        |
-| `started_at` | `float | None` | `None`  | Unix timestamp when the agent became ready          |
+| Field        | Type   | Default | Description                            |
+| ------------ | ------ | ------- | -------------------------------------- | --------------------------------------------------- |
+| `source`     | `str`  |         | Agent name                             |
+| `runner`     | `str`  |         | Name of the runner managing this agent |
+| `parent`     | `str   | None`   | `None`                                 | Name of the parent agent, or `None` for root agents |
+| `active`     | `bool` | `False` | Whether the agent started active       |
+| `bridged`    | `bool` | `False` | Whether the agent is bridged           |
+| `started_at` | `float | None`   | `None`                                 | Unix timestamp when the agent became ready          |
 
 ### BusAgentErrorMessage / BusAgentLocalErrorMessage
 
@@ -141,41 +141,41 @@ All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 
 ### BusTaskRequestMessage
 
-| Field       | Type         | Default | Description                             |
-| ----------- | ------------ | ------- | --------------------------------------- |
-| `source`    | `str`        |         | Requester agent name                    |
-| `target`    | `str | None` | `None`  | Worker agent name                       |
-| `task_id`   | `str`        |         | Unique task identifier                  |
-| `task_name` | `str | None` | `None`  | Task name for routing to named handlers |
-| `payload`   | `dict | None` | `None`  | Structured data describing the work     |
+| Field       | Type  | Default | Description            |
+| ----------- | ----- | ------- | ---------------------- | --------------------------------------- |
+| `source`    | `str` |         | Requester agent name   |
+| `target`    | `str  | None`   | `None`                 | Worker agent name                       |
+| `task_id`   | `str` |         | Unique task identifier |
+| `task_name` | `str  | None`   | `None`                 | Task name for routing to named handlers |
+| `payload`   | `dict | None`   | `None`                 | Structured data describing the work     |
 
 ### BusTaskResponseMessage / BusTaskResponseUrgentMessage
 
-| Field      | Type                                                              | Default | Description          |
-| ---------- | ----------------------------------------------------------------- | ------- | -------------------- |
-| `source`   | `str`                                                             |         | Worker agent name    |
-| `target`   | `str | None`                                                      | `None`  | Requester agent name |
-| `task_id`  | `str`                                                             |         | The task identifier  |
-| `status`   | [`TaskStatus`](/api-reference/pipecat-subagents/types#taskstatus) |         | Completion status    |
-| `response` | `dict | None`                                                     | `None`  | Result data          |
+| Field      | Type                                                              | Default | Description         |
+| ---------- | ----------------------------------------------------------------- | ------- | ------------------- | -------------------- |
+| `source`   | `str`                                                             |         | Worker agent name   |
+| `target`   | `str                                                              | None`   | `None`              | Requester agent name |
+| `task_id`  | `str`                                                             |         | The task identifier |
+| `status`   | [`TaskStatus`](/api-reference/pipecat-subagents/types#taskstatus) |         | Completion status   |
+| `response` | `dict                                                             | None`   | `None`              | Result data          |
 
 ### BusTaskUpdateMessage / BusTaskUpdateUrgentMessage
 
-| Field     | Type         | Default | Description          |
-| --------- | ------------ | ------- | -------------------- |
-| `source`  | `str`        |         | Worker agent name    |
-| `target`  | `str | None` | `None`  | Requester agent name |
-| `task_id` | `str`        |         | The task identifier  |
-| `update`  | `dict | None` | `None`  | Progress data        |
+| Field     | Type  | Default | Description         |
+| --------- | ----- | ------- | ------------------- | -------------------- |
+| `source`  | `str` |         | Worker agent name   |
+| `target`  | `str  | None`   | `None`              | Requester agent name |
+| `task_id` | `str` |         | The task identifier |
+| `update`  | `dict | None`   | `None`              | Progress data        |
 
 ### BusTaskCancelMessage
 
-| Field     | Type        | Default | Description                            |
-| --------- | ----------- | ------- | -------------------------------------- |
-| `source`  | `str`       |         | Requester agent name                   |
-| `target`  | `str | None` | `None`  | Worker agent name                      |
-| `task_id` | `str`       |         | The task identifier                    |
-| `reason`  | `str | None` | `None`  | Human-readable reason for cancellation |
+| Field     | Type  | Default | Description          |
+| --------- | ----- | ------- | -------------------- | -------------------------------------- |
+| `source`  | `str` |         | Requester agent name |
+| `target`  | `str  | None`   | `None`               | Worker agent name                      |
+| `task_id` | `str` |         | The task identifier  |
+| `reason`  | `str  | None`   | `None`               | Human-readable reason for cancellation |
 
 ## Task Streaming
 
@@ -187,19 +187,28 @@ All messages inherit these fields from `BusDataMessage` or `BusSystemMessage`:
 
 ### BusTaskStreamStartMessage / BusTaskStreamDataMessage / BusTaskStreamEndMessage
 
-| Field     | Type         | Default | Description                                                            |
-| --------- | ------------ | ------- | ---------------------------------------------------------------------- |
-| `source`  | `str`        |         | Worker agent name                                                      |
-| `target`  | `str | None` | `None`  | Requester agent name                                                   |
-| `task_id` | `str`        |         | The task identifier                                                    |
-| `data`    | `dict | None` | `None`  | Stream metadata (start), chunk payload (data), or final metadata (end) |
+| Field     | Type  | Default | Description         |
+| --------- | ----- | ------- | ------------------- | ---------------------------------------------------------------------- |
+| `source`  | `str` |         | Worker agent name   |
+| `target`  | `str  | None`   | `None`              | Requester agent name                                                   |
+| `task_id` | `str` |         | The task identifier |
+| `data`    | `dict | None`   | `None`              | Stream metadata (start), chunk payload (data), or final metadata (end) |
 
 ## UI Messages
 
-| Type                   | Priority | Description                                               |
-| ---------------------- | -------- | --------------------------------------------------------- |
-| `BusUIEventMessage`    | Data     | UI event sent from the client to a server-side `UIAgent`  |
-| `BusUICommandMessage`  | Data     | UI command sent from a `UIAgent` to the client            |
+| Type                             | Priority | Description                                                                                          |
+| -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `BusUIEventMessage`              | Data     | UI event from the client to a server-side `UIAgent`                                                  |
+| `BusUICommandMessage`            | Data     | UI command from a `UIAgent` to the client                                                            |
+| `BusUITaskGroupStartedMessage`   | Data     | A user-facing task group has been dispatched (forwarded to the client as `ui-task` ` group_started`) |
+| `BusUITaskUpdateMessage`         | Data     | Per-worker progress (`ui-task` `task_update`)                                                        |
+| `BusUITaskCompletedMessage`      | Data     | A worker in a user-facing task group has completed (`ui-task` `task_completed`)                      |
+| `BusUITaskGroupCompletedMessage` | Data     | A user-facing task group has finished (`ui-task` `group_completed`)                                  |
+
+The bus messages are subagents-internal carriers that the bridge installed
+by [`attach_ui_bridge`](#attach-ui-bridge) translates to/from the
+[on-the-wire RTVI types](/client/rtvi-standard#ui-agent-protocol). They
+live in `pipecat_subagents.agents.ui.ui_messages`.
 
 ### BusUIEventMessage
 
@@ -209,44 +218,91 @@ an event via `UIAgentClient.sendEvent(name, payload)`.
 these to [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event)
 handlers.
 
-| Field        | Type         | Default | Description                            |
-| ------------ | ------------ | ------- | -------------------------------------- |
-| `source`     | `str`        |         | Sending component (the bridge)         |
-| `target`     | `str | None` | `None`  | Recipient agent name (None broadcasts) |
-| `event_name` | `str`        | `""`    | App-defined event name                 |
-| `payload`    | `Any`        | `None`  | App-defined payload. Schemaless.       |
+| Field        | Type  | Default | Description                      |
+| ------------ | ----- | ------- | -------------------------------- | -------------------------------------- |
+| `source`     | `str` |         | Sending component (the bridge)   |
+| `target`     | `str  | None`   | `None`                           | Recipient agent name (None broadcasts) |
+| `event_name` | `str` | `""`    | App-defined event name           |
+| `payload`    | `Any` | `None`  | App-defined payload. Schemaless. |
 
 ### BusUICommandMessage
 
 Published by
 [`UIAgent.send_command`](/api-reference/pipecat-subagents/ui-agent#send-command).
-The bridge installed by `attach_ui_bridge` translates this to an
-`RTVIServerMessageFrame` with `data == {"type": "ui.command", "name":
-command_name, "payload": payload}` and pushes it through the root agent's
-pipeline for RTVI to deliver to the client.
-
-| Field          | Type         | Default | Description                                                |
-| -------------- | ------------ | ------- | ---------------------------------------------------------- |
-| `source`       | `str`        |         | Sending agent name                                         |
-| `target`       | `str | None` | `None`  | Recipient agent name (None broadcasts)                     |
-| `command_name` | `str`        | `""`    | App-defined command name                                   |
-| `payload`      | `Any`        | `None`  | Plain dict by the time it lands on the bus (see `send_command`) |
-
-### Constants
-
-```python
-from pipecat_subagents.bus import (
-    UI_EVENT_MESSAGE_TYPE,
-    UI_COMMAND_MESSAGE_TYPE,
-    UI_SNAPSHOT_EVENT_NAME,
-)
-```
-
-| Constant                  | Value             | Description                                                                                          |
-| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
-| `UI_EVENT_MESSAGE_TYPE`   | `"ui.event"`      | RTVI client-message type carrying UI events. The bridge filters on this before republishing on the bus. |
-| `UI_COMMAND_MESSAGE_TYPE` | `"ui.command"`    | Discriminator written into the `RTVIServerMessageFrame` `data` field for UI commands. Client dispatchers filter on this. |
-| `UI_SNAPSHOT_EVENT_NAME`  | `"__ui_snapshot"` | Reserved `event_name` carrying an accessibility snapshot. `UIAgent` stores the payload without dispatch or `<ui_event>` injection. |
+The bridge installed by `attach_ui_bridge` turns this into an
+`RTVIUICommandFrame` on the root agent's pipeline; the
+[`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer) wraps the frame
+into a `ui-command` envelope on the wire and the client's `UIAgentClient`
+dispatches by name to a registered handler.
+
+| Field          | Type  | Default | Description                                                     |
+| -------------- | ----- | ------- | --------------------------------------------------------------- | -------------------------------------- |
+| `source`       | `str` |         | Sending agent name                                              |
+| `target`       | `str  | None`   | `None`                                                          | Recipient agent name (None broadcasts) |
+| `command_name` | `str` | `""`    | App-defined command name                                        |
+| `payload`      | `Any` | `None`  | Plain dict by the time it lands on the bus (see `send_command`) |
+
+### BusUITaskGroupStartedMessage
+
+Published by [`UIAgent.user_task_group(...)`](/api-reference/pipecat-subagents/ui-agent#user-task-group)
+on entry. The bridge forwards it to the client as a `ui-task` envelope with
+`kind = "group_started"`.
+
+| Field         | Type                | Default | Description                                     |
+| ------------- | ------------------- | ------- | ----------------------------------------------- |
+| `task_id`     | `str`               | `""`    | Shared task identifier for the group.           |
+| `agents`      | `list[str] \| None` | `None`  | Names of the agents the work was dispatched to. |
+| `label`       | `str \| None`       | `None`  | Optional human-readable label for the group.    |
+| `cancellable` | `bool`              | `True`  | Whether the client may request cancellation.    |
+| `at`          | `int`               | `0`     | Epoch milliseconds when the group started.      |
+
+### BusUITaskUpdateMessage
+
+Forwarded by `UIAgent` whenever a worker emits a `BusTaskUpdateMessage`
+whose `task_id` matches a registered user task group. The bridge forwards
+to the client as a `ui-task` envelope with `kind = "task_update"`.
+
+| Field        | Type  | Default | Description                                      |
+| ------------ | ----- | ------- | ------------------------------------------------ |
+| `task_id`    | `str` | `""`    | The shared task identifier.                      |
+| `agent_name` | `str` | `""`    | The worker that produced the update.             |
+| `data`       | `Any` | `None`  | The worker's update payload, forwarded verbatim. |
+| `at`         | `int` | `0`     | Epoch milliseconds when the update was emitted.  |
+
+### BusUITaskCompletedMessage
+
+Forwarded by `UIAgent` whenever a worker's `BusTaskResponseMessage` arrives
+for a registered user task group. The bridge forwards to the client as a
+`ui-task` envelope with `kind = "task_completed"`.
+
+| Field        | Type  | Default | Description                                         |
+| ------------ | ----- | ------- | --------------------------------------------------- |
+| `task_id`    | `str` | `""`    | The shared task identifier.                         |
+| `agent_name` | `str` | `""`    | The worker that produced the response.              |
+| `status`     | `str` | `""`    | Completion status as a string (`TaskStatus` value). |
+| `response`   | `Any` | `None`  | The worker's response payload.                      |
+| `at`         | `int` | `0`     | Epoch milliseconds when the response was received.  |
+
+### BusUITaskGroupCompletedMessage
+
+Published when `UIAgent.user_task_group(...)` exits, after every worker has
+responded (or the group has been cancelled). The bridge forwards to the
+client as a `ui-task` envelope with `kind = "group_completed"`.
+
+| Field     | Type  | Default | Description                                  |
+| --------- | ----- | ------- | -------------------------------------------- |
+| `task_id` | `str` | `""`    | The shared task identifier.                  |
+| `at`      | `int` | `0`     | Epoch milliseconds when the group completed. |
+
+### Wire-format type strings
+
+The on-the-wire `type` strings (`"ui-event"`, `"ui-command"`,
+`"ui-snapshot"`, `"ui-cancel-task"`, `"ui-task"`) live exclusively as
+`Literal[...]` defaults on the matching pydantic envelope models in
+[`pipecat.processors.frameworks.rtvi.models`](/client/rtvi-standard#ui-agent-protocol).
+There are no standalone `UI_*_MESSAGE_TYPE` constants. Client-side, the
+strings are members of the `RTVIMessageType` enum (e.g.
+`RTVIMessageType.UI_EVENT`).
 
 ## attach_ui_bridge
 
@@ -254,31 +310,36 @@ from pipecat_subagents.bus import (
 def attach_ui_bridge(agent: BaseAgent, *, target: str | None = None) -> None
 ```
 
-Wire the root agent's pipeline to the UI Agent SDK wire protocol. Call this
-from the root agent's `on_ready` hook. The root agent's pipeline task must be
-built with `enable_rtvi=True`.
+Wire the root agent's pipeline to the UI Agent Protocol. Call this from the
+root agent's `on_ready` hook. The root agent's pipeline task must be built
+with `enable_rtvi=True`.
 
 ```python
-from pipecat_subagents.agents.ui_bridge import attach_ui_bridge
+from pipecat_subagents.agents import attach_ui_bridge
 
 class RootAgent(BaseAgent):
     async def on_ready(self) -> None:
         await super().on_ready()
-        attach_ui_bridge(self)
+        attach_ui_bridge(self, target="ui")
 ```
 
 Side effects:
 
-- Registers an `on_client_message` handler on RTVI. Messages whose `type`
-  matches `UI_EVENT_MESSAGE_TYPE` are republished as `BusUIEventMessage`;
-  all other client messages pass through untouched.
-- Registers an `on_bus_message` handler on `agent`. When a
-  `BusUICommandMessage` arrives, the bridge pushes an `RTVIServerMessageFrame`
-  downstream so RTVI delivers it to the client.
-
-| Parameter | Type         | Default | Description                                                                                                                                |
-| --------- | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `agent`   | `BaseAgent`  |         | The root agent owning the pipeline task and RTVI processor.                                                                                |
-| `target`  | `str | None` | `None`  | Optional target agent name for the republished `BusUIEventMessage`. When `None`, the message is broadcast to every `UIAgent` on the bus. |
+- **Inbound**: subscribes to the `RTVIProcessor`'s
+  [`on_ui_message`](/api-reference/server/rtvi/rtvi-processor#receiving-ui-messages)
+  handler. Every `ui-event` and `ui-snapshot` message is republished onto
+  the bus as a `BusUIEventMessage` (snapshots are routed to `UIAgent` via a
+  reserved internal event name; `ui-cancel-task` is routed similarly to
+  `cancel_task`).
+- **Outbound**: subscribes to the bus. When a `BusUICommandMessage`
+  arrives, the bridge pushes an `RTVIUICommandFrame` downstream; when one
+  of the `BusUITask*` messages arrives, it pushes an `RTVIUITaskFrame`
+  carrying the matching `UITask*Data`. The `RTVIObserver` wraps each
+  frame into the `ui-command` / `ui-task` envelope on the wire.
+
+| Parameter | Type        | Default | Description                                                 |
+| --------- | ----------- | ------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent`   | `BaseAgent` |         | The root agent owning the pipeline task and RTVI processor. |
+| `target`  | `str        | None`   | `None`                                                      | Optional target agent name for republished `BusUIEventMessage`. When `None`, the message is broadcast to every `UIAgent` on the bus. Pass the UI agent's name (e.g. `"ui"`) for direct delivery. |
 
 **Raises:** `RuntimeError` if the agent's pipeline task has no RTVI processor.
diff --git a/api-reference/pipecat-subagents/overview.mdx b/api-reference/pipecat-subagents/overview.mdx
index dd5101d9..977986be 100644
--- a/api-reference/pipecat-subagents/overview.mdx
+++ b/api-reference/pipecat-subagents/overview.mdx
@@ -156,11 +156,12 @@ uv add "pipecat-ai-subagents[websocket]"
 
 ## Agent Type Hierarchy
 
-| Class                                                                                                  | Parent      | Description                                           |
-| ------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------- |
-| [`BaseAgent`](/api-reference/pipecat-subagents/base-agent)                                             | -           | Core agent with lifecycle, bus, and task coordination |
-| [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent)                                               | `BaseAgent` | Adds LLM pipeline and `@tool` registration            |
-| [`FlowsAgent`](/api-reference/pipecat-subagents/flows-agent)                                           | `BaseAgent` | Adds Pipecat Flows integration                        |
-| [`UIAgent`](/api-reference/pipecat-subagents/ui-agent)                                                 | `LLMAgent`  | Adds UI event dispatch and accessibility snapshot reasoning |
-| [`WebSocketProxyClientAgent`](/api-reference/pipecat-subagents/proxy-agents#websocketproxyclientagent) | `BaseAgent` | Forwards bus messages to a remote server              |
-| [`WebSocketProxyServerAgent`](/api-reference/pipecat-subagents/proxy-agents#websocketproxyserveragent) | `BaseAgent` | Receives bus messages from a remote client            |
+| Class                                                                                                  | Parent            | Description                                                                                    |
+| ------------------------------------------------------------------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------- |
+| [`BaseAgent`](/api-reference/pipecat-subagents/base-agent)                                             | -                 | Core agent with lifecycle, bus, and task coordination                                          |
+| [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent)                                               | `BaseAgent`       | Adds LLM pipeline and `@tool` registration                                                     |
+| `LLMContextAgent`                                                                                      | `LLMAgent`        | Adds a built-in `LLMContext` and user/assistant aggregator pair (no separate page; see source) |
+| [`FlowsAgent`](/api-reference/pipecat-subagents/flows-agent)                                           | `BaseAgent`       | Adds Pipecat Flows integration                                                                 |
+| [`UIAgent`](/api-reference/pipecat-subagents/ui-agent)                                                 | `LLMContextAgent` | Adds UI event dispatch and accessibility snapshot reasoning                                    |
+| [`WebSocketProxyClientAgent`](/api-reference/pipecat-subagents/proxy-agents#websocketproxyclientagent) | `BaseAgent`       | Forwards bus messages to a remote server                                                       |
+| [`WebSocketProxyServerAgent`](/api-reference/pipecat-subagents/proxy-agents#websocketproxyserveragent) | `BaseAgent`       | Receives bus messages from a remote client                                                     |
diff --git a/api-reference/pipecat-subagents/ui-agent.mdx b/api-reference/pipecat-subagents/ui-agent.mdx
index cebc2abc..6f5eeb2e 100644
--- a/api-reference/pipecat-subagents/ui-agent.mdx
+++ b/api-reference/pipecat-subagents/ui-agent.mdx
@@ -5,11 +5,11 @@ description: "LLM agent that dispatches UI events from the client and reasons ab
 
 ## Overview
 
-`UIAgent` extends [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent) with a UI-aware loop:
+`UIAgent` extends `LLMContextAgent` (an internal `LLMAgent` subclass that bundles an `LLMContext` plus the user/assistant aggregator pair) with a UI-aware loop:
 
 - **UI events** sent from the client via `UIAgentClient.sendEvent(name, payload)` are dispatched to methods marked with [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event), and (by default) appended to the LLM context as `<ui_event name="...">payload</ui_event>` developer messages.
 - **Accessibility snapshots** captured by the client's a11y walker arrive on a reserved event name and are stored as the latest `<ui_state>`. By default, the snapshot is auto-injected into the LLM context at the start of every task request, so the agent always reasons over the current screen.
-- **UI commands** flow back the other way via `send_command(name, payload)`. The bridge installed by [`attach_ui_bridge`](/api-reference/pipecat-subagents/messages#attach-ui-bridge) translates each command into an `RTVIServerMessageFrame`; the client's `UIAgentClient` dispatches by name to a registered handler.
+- **UI commands** flow back the other way via `send_command(name, payload)`. The bridge installed by [`attach_ui_bridge`](/api-reference/pipecat-subagents/messages#attach-ui-bridge) translates each command into an `RTVIUICommandFrame` (or `RTVIUITaskFrame` for task-lifecycle traffic) on the root agent's pipeline; the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer) wraps it into a `ui-command` / `ui-task` envelope on the wire and the client's `UIAgentClient` dispatches by name to a registered handler.
 
 ```python
 from pipecat_subagents.agents import UIAgent, on_ui_event
@@ -30,10 +30,13 @@ class MyUIAgent(UIAgent):
 ```
 
 <Note>
-  Apps opt in to LLM tools via mixins
-  ([`ScrollToToolMixin`](/api-reference/pipecat-subagents/ui-tools#scrolltotoolmixin),
-  [`HighlightToolMixin`](/api-reference/pipecat-subagents/ui-tools#highlighttoolmixin)).
-  Inherit alongside `UIAgent` to expose them to the LLM.
+  Apps that want a single bundled LLM tool covering the full action vocabulary
+  can inherit
+  [`ReplyToolMixin`](/api-reference/pipecat-subagents/ui-tools#replytoolmixin)
+  alongside `UIAgent`. Apps with their own tool surface call the action helpers
+  (`scroll_to`, `highlight`, `select_text`, `click`, `set_input_value`) directly
+  inside custom `@tool` methods. See [Choosing a tool
+  shape](/subagents/learn/ui-agent#choosing-a-tool-shape).
 </Note>
 
 ## Configuration
@@ -49,22 +52,57 @@ Inherits all parameters from [`LLMAgent`](/api-reference/pipecat-subagents/llm-a
   inter-agent communication.
 </ParamField>
 
-<ParamField path="active" type="bool" default="False">
-  Whether the agent starts active. Defaults to `False`, matching `LLMAgent`.
+<ParamField path="active" type="bool" default="True">
+  Whether the agent starts active. Defaults to `True` for `UIAgent` (vs. `False`
+  on `LLMAgent` / `LLMContextAgent`) because the canonical UIAgent role is an
+  always-on delegate that should self-activate as soon as its pipeline starts.
+  Pass `active=False` only if you have a handoff use case.
 </ParamField>
 
 <ParamField path="bridged" type="tuple[str, ...] | None" default="None">
   Bridge configuration. See
   [`BaseAgent`](/api-reference/pipecat-subagents/base-agent#configuration) for
-  details.
+  details. Setting this together with the default `auto_inject_ui_state=True`
+  raises `ValueError` — see `auto_inject_ui_state` below.
+</ParamField>
+
+<ParamField path="defer_tool_frames" type="bool" default="True">
+  Forwarded to `LLMContextAgent`. See
+  [`LLMAgent`](/api-reference/pipecat-subagents/llm-agent) for details.
+</ParamField>
+
+<ParamField path="context" type="LLMContext | None" default="None">
+  Optional pre-built `LLMContext`. Forwarded to `LLMContextAgent`. Note that any
+  messages seeded here are part of the mutable task history and are cleared
+  before each task when `keep_history=False` (the default), since the reset
+  replaces the entire message list. For durable UI / app instructions, pass them
+  via the LLM service's `system_instruction` instead.
+</ParamField>
+
+<ParamField
+  path="user_params"
+  type="LLMUserAggregatorParams | None"
+  default="None"
+>
+  Optional user-aggregator parameters. Forwarded to `LLMContextAgent`.
+</ParamField>
+
+<ParamField
+  path="assistant_params"
+  type="LLMAssistantAggregatorParams | None"
+  default="None"
+>
+  Optional assistant-aggregator parameters. Forwarded to `LLMContextAgent`. Set
+  `enable_auto_context_summarization=True` here to keep the running context
+  bounded over long sessions when `keep_history=True`.
 </ParamField>
 
 <ParamField path="inject_events" type="bool" default="True">
-  When `True`, every UI event received is appended to the LLM context as a
-  `<ui_event name="...">payload</ui_event>` developer message before the
-  matching `@on_ui_event` handler (if any) runs. Override
-  [`render_ui_event`](#render-ui-event) to customize the rendered string, or
-  set this to `False` to disable injection entirely.
+  When `True`, every UI event received is appended to the LLM context as a `
+  <ui_event name="...">payload</ui_event>` developer message before the matching
+  `@on_ui_event` handler (if any) runs. Override
+  [`render_ui_event`](#render-ui-event) to customize the rendered string, or set
+  this to `False` to disable injection entirely.
 </ParamField>
 
 <ParamField path="auto_inject_ui_state" type="bool" default="True">
@@ -72,13 +110,43 @@ Inherits all parameters from [`LLMAgent`](/api-reference/pipecat-subagents/llm-a
   at the start of every task request, so the agent always reasons over the
   current screen. Set to `False` to call [`inject_ui_state`](#inject-ui-state)
   yourself.
+
+Setting this together with a non-`None` `bridged` value raises `ValueError`:
+auto-injection fires on `on_task_request`, but a bridged `UIAgent` receives
+user voice frames through the bridge instead of task messages, so the
+snapshot would never reach the LLM context. The canonical pattern is a
+non-bridged `UIAgent` receiving delegated tasks from a separate voice
+`LLMAgent`. To use a bridged `UIAgent` (advanced cases), pass
+`auto_inject_ui_state=False` explicitly and call `inject_ui_state()`
+yourself.
+
 </ParamField>
 
-<ParamField path="log_snapshots" type="bool" default="False">
-  When `True`, emit a `logger.debug` line on every accessibility snapshot
-  received: node count, rendered size, rough token estimate, and the full
-  rendered `<ui_state>` text. Useful in dev / staging for eyeballing what the
-  LLM will see.
+<ParamField path="keep_history" type="bool" default="False">
+  When `False` (the default), the LLM context is cleared at the start of every
+  task: each task starts from an empty messages list, the current `<ui_state>`
+  is injected, and the user's query follows. Best for the canonical
+  stateless-delegate role where the voice agent owns dialog state and the UI
+  agent's job is "given the current screen, do something."
+
+When `True`, conversation history accumulates across tasks (queries, prior
+`<ui_state>` blocks, tool calls, responses) so the LLM can reason over
+multi-turn references like "show me the next one" or "tell me about the Pro
+version of that." History accumulation grows token usage and can confuse
+smaller models when multiple `<ui_state>` snapshots are present at once;
+opt in only when the dialog continuity is worth the cost. Pair with
+`enable_auto_context_summarization=True` on the assistant aggregator (via
+`assistant_params`) to keep the running context bounded over long sessions.
+Apps in `keep_history=True` mode can call `await self.reset_context()` to
+clear manually.
+
+In `keep_history=False` mode, messages pre-seeded via `context=` are
+also cleared on the first task. Durable instructions belong in the LLM
+service's `system_instruction` setting (e.g. concatenate with the
+[`UI_STATE_PROMPT_GUIDE`](/api-reference/pipecat-subagents/ui-prompts)
+constant); use `keep_history=True` if seeded messages genuinely need to
+live in the conversation history.
+
 </ParamField>
 
 ## Properties
@@ -143,19 +211,51 @@ to run.
 async def on_task_request(self, message: BusTaskRequestMessage) -> None
 ```
 
-Override of `BaseAgent.on_task_request` that records the in-flight task on
-[`current_task`](#current-task) for [`respond_to_task`](#respond-to-task) to
-close out, then auto-injects the latest `<ui_state>` so the agent reasons
-over the current screen.
+Override of `BaseAgent.on_task_request` that:
+
+1. Acquires the per-agent single-flight task lock (held until
+   [`respond_to_task`](#respond-to-task) or
+   [`on_task_cancelled`](#on-task-cancelled) fires).
+2. Records the in-flight task on [`current_task`](#current-task) for
+   `respond_to_task` to close out.
+3. In `keep_history=False` mode (the default), clears the LLM context so
+   each task starts fresh.
+4. Auto-injects the latest `<ui_state>` so the agent reasons over the
+   current screen.
 
 Disable the snapshot injection via `auto_inject_ui_state=False` if your app
 wants to drive injection manually (e.g. inject only on specific task names).
-Task tracking happens regardless.
+Task tracking and lock acquisition happen regardless.
 
-| Parameter | Type                                                                              | Description                              |
-| --------- | --------------------------------------------------------------------------------- | ---------------------------------------- |
+The single-flight lock keeps overlapping requests queued rather than
+interleaving their context mutations: a second request arrives while the
+first is in-flight, sits in `acquire()`, and proceeds only after the first
+calls `respond_to_task` (or is cancelled).
+
+| Parameter | Type                                                                                       | Description                             |
+| --------- | ------------------------------------------------------------------------------------------ | --------------------------------------- |
 | `message` | [`BusTaskRequestMessage`](/api-reference/pipecat-subagents/messages#bustaskrequestmessage) | The incoming task request from the bus. |
 
+### on_task_cancelled
+
+```python
+async def on_task_cancelled(self, message: BusTaskCancelMessage) -> None
+```
+
+Override of `BaseAgent.on_task_cancelled` that releases the single-flight
+task lock when the in-flight task is cancelled. Without this hook, a
+cancellation would strand the lock (because the framework's cancel path
+sends a `CANCELLED` response directly via `send_task_response`, bypassing
+`respond_to_task` and its lock-release) and every subsequent task request
+would block forever.
+
+Idempotent: if a tool calls `respond_to_task` concurrently and clears the
+slot first, this hook short-circuits.
+
+| Parameter | Type                                                                                     | Description                            |
+| --------- | ---------------------------------------------------------------------------------------- | -------------------------------------- |
+| `message` | [`BusTaskCancelMessage`](/api-reference/pipecat-subagents/messages#bustaskcancelmessage) | The cancellation message from the bus. |
+
 ## Methods
 
 ### respond_to_task
@@ -174,8 +274,10 @@ Complete the in-flight task this agent is processing.
 
 Convenience wrapper around `send_task_response` that looks up the current
 task from [`current_task`](#current-task) so `@tool` methods don't have to
-thread the `task_id` through every call. Clears `current_task` after the
-response is sent, so a second call is a no-op.
+thread the `task_id` through every call. Clears `current_task` and
+**releases the single-flight task lock** (acquired in
+[`on_task_request`](#on-task-request)) so the next queued task can proceed.
+Calling a second time is a no-op.
 
 `speak` is the convention the SDK demos use for "text the voice agent
 should hand verbatim to TTS." When provided, it's merged into the
@@ -185,11 +287,11 @@ can pass a fully formed `response` dict and leave `speak` unset.
 No-op when there is no task in flight (e.g. the tool was invoked outside a
 task dispatch).
 
-| Parameter  | Type                                                                | Default     | Description                                                                                                                                  |
-| ---------- | ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `response` | `dict | None`                                                       | `None`      | Result data dict. Merged with the `speak` key when `speak` is provided.                                                                      |
-| `speak`    | `str | None`                                                        | `None`      | Optional short text for verbatim TTS. Omit (or pass `None`) to leave the response without a `speak` key — the voice agent stays silent for the turn. |
-| `status`   | [`TaskStatus`](/api-reference/pipecat-subagents/types#taskstatus)   | `COMPLETED` | Completion status.                                                                                                                            |
+| Parameter  | Type                                                              | Default     | Description        |
+| ---------- | ----------------------------------------------------------------- | ----------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `response` | `dict                                                             | None`       | `None`             | Result data dict. Merged with the `speak` key when `speak` is provided.                                                                              |
+| `speak`    | `str                                                              | None`       | `None`             | Optional short text for verbatim TTS. Omit (or pass `None`) to leave the response without a `speak` key — the voice agent stays silent for the turn. |
+| `status`   | [`TaskStatus`](/api-reference/pipecat-subagents/types#taskstatus) | `COMPLETED` | Completion status. |
 
 ```python
 @tool
@@ -207,32 +309,192 @@ async def send_command(self, name: str, payload: Any = None) -> None
 
 Send a named UI command to the client. Publishes a
 [`BusUICommandMessage`](/api-reference/pipecat-subagents/messages#busuicommandmessage),
-which `attach_ui_bridge` translates into an `RTVIServerMessageFrame` for the
-RTVI processor to deliver to the client. Client-side handlers registered via
-`registerCommandHandler` (or one of the `useStandard*Handler` hooks) dispatch
-on the command name.
+which the bridge installed by `attach_ui_bridge` turns into an
+`RTVIUICommandFrame` on the root agent's pipeline; the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer)
+wraps that into a `ui-command` envelope on the wire. Client-side handlers
+registered via `registerCommandHandler` (or one of the `useStandard*Handler`
+hooks) dispatch on the command name.
 
-| Parameter | Type            | Default | Description                                                                                  |
-| --------- | --------------- | ------- | -------------------------------------------------------------------------------------------- |
-| `name`    | `str`           |         | App-defined command name (e.g. `"toast"`, `"navigate"`, or any app-specific name). |
-| `payload` | `Any`           | `None`  | Dataclass instance, dict, or `None`. See below.                                              |
+| Parameter | Type  | Default | Description                                                                        |
+| --------- | ----- | ------- | ---------------------------------------------------------------------------------- |
+| `name`    | `str` |         | App-defined command name (e.g. `"toast"`, `"navigate"`, or any app-specific name). |
+| `payload` | `Any` | `None`  | Pydantic model, dataclass, dict, or `None`. See below.                             |
 
 `payload` is normalized before sending:
 
-- **Dataclass instance** (including the built-ins in
-  [`pipecat_subagents.agents.ui_commands`](/api-reference/pipecat-subagents/ui-commands)):
-  converted to a plain dict via `dataclasses.asdict`.
+- **Pydantic `BaseModel` instance** (including the built-in command models
+  in [`pipecat.processors.frameworks.rtvi.models`](/api-reference/pipecat-subagents/ui-commands)):
+  converted to a plain dict via `model_dump()`.
+- **Dataclass instance**: converted to a plain dict via `dataclasses.asdict`.
 - **`dict`**: forwarded as-is.
 - **`None`**: forwarded as an empty dict.
 
 ```python
-from pipecat_subagents.agents.ui_commands import Toast, Navigate
+from pipecat.processors.frameworks.rtvi.models import Toast, Navigate
 
 await self.send_command("toast", Toast(title="Saved"))
 await self.send_command("navigate", Navigate(view="settings"))
 await self.send_command("custom", {"foo": "bar"})
 ```
 
+### Action helpers
+
+Plain instance methods that wrap `send_command` with the standard payload
+models. They are NOT LLM tools — subclasses that want them exposed to the
+LLM either inherit
+[`ReplyToolMixin`](/api-reference/pipecat-subagents/ui-tools#replytoolmixin)
+(which calls these helpers under the hood from a single bundled
+`reply(...)` tool), or write their own `@tool` methods that delegate to
+these helpers.
+
+#### scroll_to
+
+```python
+async def scroll_to(self, ref: str) -> None
+```
+
+Dispatch a `scroll_to` UI command for the given snapshot ref. Convenience
+wrapper around `send_command("scroll_to", ScrollTo(ref=ref))`.
+
+#### highlight
+
+```python
+async def highlight(self, ref: str) -> None
+```
+
+Dispatch a `highlight` UI command for the given snapshot ref. Convenience
+wrapper around `send_command("highlight", Highlight(ref=ref))`.
+
+#### select_text
+
+```python
+async def select_text(
+    self,
+    ref: str,
+    *,
+    start_offset: int | None = None,
+    end_offset: int | None = None,
+) -> None
+```
+
+Dispatch a `select_text` UI command for the given snapshot ref. With
+`start_offset` / `end_offset` set, the client's standard handler selects a
+sub-range of the element's text; with both `None` (the default), the entire
+element's contents are selected. Offsets are character offsets over the
+element's concatenated `textContent`.
+
+#### click
+
+```python
+async def click(self, ref: str) -> None
+```
+
+Dispatch a `click` UI command for the given snapshot ref. Use inside custom
+`@tool` bodies for state-changing form actions like checkboxes, radio
+buttons, and submit buttons. The standard client handler silently no-ops on
+`disabled` targets so the agent can't bypass UI affordances.
+
+#### set_input_value
+
+```python
+async def set_input_value(
+    self,
+    ref: str,
+    value: str,
+    *,
+    replace: bool = True,
+) -> None
+```
+
+Dispatch a `set_input_value` UI command for the given input/textarea ref.
+With `replace=True` (the default) the field's existing value is overwritten;
+with `replace=False` the value is appended.
+
+### user_task_group
+
+```python
+def user_task_group(
+    self,
+    *agent_names: str,
+    name: str | None = None,
+    payload: dict | None = None,
+    timeout: float | None = None,
+    cancel_on_error: bool = True,
+    label: str | None = None,
+    cancellable: bool = True,
+) -> UserTaskGroupContext
+```
+
+Dispatch a task group whose lifecycle is forwarded to the client as `ui-task`
+envelopes. Behaves exactly like
+[`task_group(...)`](/api-reference/pipecat-subagents/base-agent), but the
+client's task reducer (`useUITasks` on React) consumes the envelopes
+automatically — `group_started` on entry, `task_update` for each worker
+update, `task_completed` for each worker response, and `group_completed` on
+exit.
+
+Workers don't need to change. Any `send_task_update` they emit against the
+group's `task_id` is forwarded automatically.
+
+Returns a `UserTaskGroupContext` for use with `async with`. See the
+[Async tasks and lifecycle](/subagents/learn/ui-agent#async-tasks-and-lifecycle)
+guide section for a worked example.
+
+| Parameter         | Type            | Default | Description                                                                            |
+| ----------------- | --------------- | ------- | -------------------------------------------------------------------------------------- |
+| `*agent_names`    | `str`           |         | Names of the worker agents to dispatch to.                                             |
+| `name`            | `str \| None`   | `None`  | Optional task name for routing to named `@task` handlers on the workers.               |
+| `payload`         | `dict \| None`  | `None`  | Optional structured data describing the work.                                          |
+| `timeout`         | `float \| None` | `None`  | Optional timeout in seconds covering both the ready-wait and task execution.           |
+| `cancel_on_error` | `bool`          | `True`  | Whether to cancel the group if a worker errors.                                        |
+| `label`           | `str \| None`   | `None`  | Optional human-readable label surfaced to the client (titles the in-flight task card). |
+| `cancellable`     | `bool`          | `True`  | Whether the client may request cancellation of this group via `ui-cancel-task`.        |
+
+### start_user_task_group
+
+```python
+async def start_user_task_group(
+    self,
+    *agent_names: str,
+    name: str | None = None,
+    payload: dict | None = None,
+    timeout: float | None = None,
+    cancel_on_error: bool = True,
+    label: str | None = None,
+    cancellable: bool = True,
+) -> str
+```
+
+Fire-and-forget version of [`user_task_group`](#user-task-group). Dispatches
+the group in the background and returns the `task_id`. The SDK manages the
+asyncio task that holds the context open while workers run, so callers don't
+need to spawn one themselves.
+
+Use this when an LLM `@tool` body wants to kick off a task group and return
+immediately so the voice agent unblocks. Use the `user_task_group` context
+manager when the caller wants to consume worker events inline (`async for
+event in tg`) or react to results before returning.
+
+Worker exceptions inside the dispatched context are logged but do not
+propagate; cancellation works the same way it does for the context-manager
+form (the user clicks Cancel, the SDK turns it into a `ui-cancel-task`
+envelope and the framework cancels the group).
+
+### reset_context
+
+```python
+async def reset_context(self) -> None
+```
+
+Clear the LLM conversation history. Replaces all messages in the running
+context with an empty list. The system prompt (set via
+`system_instruction`) is unaffected.
+
+Apps in `keep_history=True` mode call this when they want to deliberately
+start over (e.g. the user said "start fresh"). Apps in the default
+`keep_history=False` mode don't need to call this; the per-task reset runs
+automatically.
+
 ### render_ui_state
 
 ```python
@@ -310,9 +572,9 @@ attribute and a JSON-encoded payload as inner text:
 <ui_event name="nav_click">{"view": "settings"}</ui_event>
 ```
 
-| Parameter | Type                                                                                  | Description                                  |
-| --------- | ------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `message` | [`BusUIEventMessage`](/api-reference/pipecat-subagents/messages#busuieventmessage) | The UI event to render.                      |
+| Parameter | Type                                                                               | Description             |
+| --------- | ---------------------------------------------------------------------------------- | ----------------------- |
+| `message` | [`BusUIEventMessage`](/api-reference/pipecat-subagents/messages#busuieventmessage) | The UI event to render. |
 
 **Returns:** A string to append to the LLM context as a developer message.
 Return an empty string to skip injection for this event.
diff --git a/api-reference/pipecat-subagents/ui-commands.mdx b/api-reference/pipecat-subagents/ui-commands.mdx
index e18bf161..20bee13b 100644
--- a/api-reference/pipecat-subagents/ui-commands.mdx
+++ b/api-reference/pipecat-subagents/ui-commands.mdx
@@ -5,29 +5,38 @@ description: "Built-in command vocabulary for UIAgent.send_command"
 
 ## Overview
 
-These dataclasses describe commands that have matching default React handlers
-in `@pipecat-ai/client-react`'s `standardHandlers`. Apps can use them as-is,
-override the client handler to customize rendering, or ignore them entirely
-and define their own command names.
+These pydantic models describe commands that have matching default React
+handlers in `@pipecat-ai/client-react`'s `standardHandlers`. Apps can use
+them as-is, override the client handler to customize rendering, or ignore
+them entirely and define their own command names.
+
+The canonical home of the wire-format models is `pipecat`
+(see the [RTVI standard](/client/rtvi-standard#standard-command-payloads)
+for the on-the-wire shapes). Subagents re-exports them from
+`pipecat_subagents.agents` for convenience.
 
 ```python
-from pipecat_subagents.agents.ui_commands import (
+from pipecat.processors.frameworks.rtvi.models import (
     Toast,
     Navigate,
     ScrollTo,
     Highlight,
     Focus,
+    Click,
+    SetInputValue,
+    SelectText,
 )
 ```
 
 [`UIAgent.send_command(name, payload)`](/api-reference/pipecat-subagents/ui-agent#send-command)
-accepts any of these dataclasses directly. `dataclasses.asdict` converts them
-to the plain-dict shape that travels over the wire.
+accepts any of these pydantic models directly. `BaseModel.model_dump()`
+converts them to the plain-dict shape that travels over the wire.
 
 ```python
 await self.send_command("toast", Toast(title="Saved", subtitle="Just now"))
 await self.send_command("navigate", Navigate(view="settings"))
 await self.send_command("scroll_to", ScrollTo(ref="e42"))
+await self.send_command("click", Click(ref="e7"))
 ```
 
 ## Toast
@@ -37,23 +46,23 @@ renderer of their choice via
 [`useToastHandler`](/api-reference/client/react/hooks#usetoasthandler); the
 SDK doesn't ship one.
 
-| Field         | Type         | Default | Description                                            |
-| ------------- | ------------ | ------- | ------------------------------------------------------ |
-| `title`       | `str`        |         | Required headline.                                     |
-| `subtitle`    | `str | None` | `None`  | Optional second line beneath the title.                |
-| `description` | `str | None` | `None`  | Optional body text.                                    |
-| `image_url`   | `str | None` | `None`  | Optional leading image URL.                            |
-| `duration_ms` | `int | None` | `None`  | Optional dismiss timer. Client default applies when `None`. |
+| Field         | Type  | Default | Description        |
+| ------------- | ----- | ------- | ------------------ | ----------------------------------------------------------- |
+| `title`       | `str` |         | Required headline. |
+| `subtitle`    | `str  | None`   | `None`             | Optional second line beneath the title.                     |
+| `description` | `str  | None`   | `None`             | Optional body text.                                         |
+| `image_url`   | `str  | None`   | `None`             | Optional leading image URL.                                 |
+| `duration_ms` | `int  | None`   | `None`             | Optional dismiss timer. Client default applies when `None`. |
 
 ## Navigate
 
 Client-side navigation to a named view. Wire into your router of choice via
 [`useNavigateHandler`](/api-reference/client/react/hooks#usenavigatehandler).
 
-| Field    | Type          | Default | Description                                              |
-| -------- | ------------- | ------- | -------------------------------------------------------- |
-| `view`   | `str`         |         | App-defined view name (route, screen id, tab key, etc.). |
-| `params` | `dict | None` | `None`  | Optional view-specific parameters.                       |
+| Field    | Type  | Default | Description                                              |
+| -------- | ----- | ------- | -------------------------------------------------------- | ---------------------------------- |
+| `view`   | `str` |         | App-defined view name (route, screen id, tab key, etc.). |
+| `params` | `dict | None`   | `None`                                                   | Optional view-specific parameters. |
 
 ## ScrollTo
 
@@ -64,27 +73,81 @@ assigned by the a11y walker), then falls back to `target_id`
 (`document.getElementById`). Supply whichever you have; `ref` is the normal
 choice when acting on a node from `<ui_state>`.
 
-| Field       | Type         | Default | Description                                                                |
-| ----------- | ------------ | ------- | -------------------------------------------------------------------------- |
-| `ref`       | `str | None` | `None`  | Snapshot ref from `<ui_state>`.                                       |
-| `target_id` | `str | None` | `None`  | Element id registered on the client.                                       |
-| `behavior`  | `str | None` | `None`  | Optional behavior hint (`"smooth"` or `"instant"`). Clients may ignore. |
+| Field       | Type | Default | Description |
+| ----------- | ---- | ------- | ----------- | ----------------------------------------------------------------------- |
+| `ref`       | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.                                         |
+| `target_id` | `str | None`   | `None`      | Element id registered on the client.                                    |
+| `behavior`  | `str | None`   | `None`      | Optional behavior hint (`"smooth"` or `"instant"`). Clients may ignore. |
 
 ## Highlight
 
 Briefly emphasize a target element (flash, glow, pulse).
 
-| Field         | Type         | Default | Description                                          |
-| ------------- | ------------ | ------- | ---------------------------------------------------- |
-| `ref`         | `str | None` | `None`  | Snapshot ref from `<ui_state>`.                 |
-| `target_id`   | `str | None` | `None`  | Element id registered on the client.                 |
-| `duration_ms` | `int | None` | `None`  | Optional duration in ms. Client default applies when `None`. |
+| Field         | Type | Default | Description |
+| ------------- | ---- | ------- | ----------- | ------------------------------------------------------------ |
+| `ref`         | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.                              |
+| `target_id`   | `str | None`   | `None`      | Element id registered on the client.                         |
+| `duration_ms` | `int | None`   | `None`      | Optional duration in ms. Client default applies when `None`. |
 
 ## Focus
 
 Move input focus to a target element.
 
-| Field       | Type         | Default | Description                          |
-| ----------- | ------------ | ------- | ------------------------------------ |
-| `ref`       | `str | None` | `None`  | Snapshot ref from `<ui_state>`. |
-| `target_id` | `str | None` | `None`  | Element id registered on the client. |
+| Field       | Type | Default | Description |
+| ----------- | ---- | ------- | ----------- | ------------------------------------ |
+| `ref`       | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.      |
+| `target_id` | `str | None`   | `None`      | Element id registered on the client. |
+
+## Click
+
+Click an element on the client. Closes the form-fill loop for non-text
+inputs (checkboxes, radios) and exposes the rest of the action vocabulary
+(submit buttons, links, app-specific clickable nodes). The standard handler
+silently no-ops on `disabled` targets so the agent can't bypass UI
+affordances meant to be user-controlled.
+
+For native `<select>`, prefer [`SetInputValue`](#setinputvalue) (clicking
+options doesn't reliably change the selection); for custom comboboxes
+(ARIA listbox + popup), apps wire their own command matching the library's
+interaction model.
+
+| Field       | Type | Default | Description |
+| ----------- | ---- | ------- | ----------- | ------------------------------------------------------------------------------------------------ |
+| `ref`       | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.                                                                  |
+| `target_id` | `str | None`   | `None`      | Element id registered on the client. Used as a fallback when `ref` is not set or has gone stale. |
+
+## SetInputValue
+
+Write a value into a text input or textarea on the client. Use this for
+form-filling: the agent has decided what should go into a field
+(clarifying answer, tax form entry, etc.) and asks the client to populate
+it.
+
+The standard handler silently no-ops on `disabled`, `readonly`, and
+`<input type="hidden">` targets so the agent can't write into fields the
+user can't.
+
+| Field       | Type   | Default | Description                                                                         |
+| ----------- | ------ | ------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `value`     | `str`  | `""`    | The text to write.                                                                  |
+| `ref`       | `str   | None`   | `None`                                                                              | Snapshot ref from `<ui_state>`. Typically the ref of an `<input>` or `<textarea>`.               |
+| `target_id` | `str   | None`   | `None`                                                                              | Element id registered on the client. Used as a fallback when `ref` is not set or has gone stale. |
+| `replace`   | `bool` | `True`  | When `True` (the default), overwrite the current value. When `False`, append to it. |
+
+## SelectText
+
+Select text on the page so the user can see what the agent means. Mirror
+of the `selection` field surfaced in the snapshot. Use this to point the
+user's attention at a specific paragraph or range after the agent has
+decided what it's referring to.
+
+With `start_offset` and `end_offset` omitted, the entire target's text
+content is selected (`Range.selectNodeContents` for document elements;
+`el.select()` for `<input>` / `<textarea>`).
+
+| Field          | Type | Default | Description |
+| -------------- | ---- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ref`          | `str | None`   | `None`      | Snapshot ref from `<ui_state>`. Typically the ref of a paragraph or input element.                                                                                                   |
+| `target_id`    | `str | None`   | `None`      | Element id registered on the client. Used as a fallback when `ref` is not set or has gone stale.                                                                                     |
+| `start_offset` | `int | None`   | `None`      | Character offset within the target's text where the selection should start. For inputs/textareas this is the value offset; for documents the concatenation of descendant text nodes. |
+| `end_offset`   | `int | None`   | `None`      | End character offset, exclusive. Same coordinate system as `start_offset`.                                                                                                           |
diff --git a/api-reference/pipecat-subagents/ui-prompts.mdx b/api-reference/pipecat-subagents/ui-prompts.mdx
index b4810c8e..e7290737 100644
--- a/api-reference/pipecat-subagents/ui-prompts.mdx
+++ b/api-reference/pipecat-subagents/ui-prompts.mdx
@@ -10,7 +10,7 @@ understands the `<ui_state>` and `<ui_event>` developer messages the SDK
 injects on its behalf.
 
 ```python
-from pipecat_subagents.agents.ui_prompts import UI_STATE_PROMPT_GUIDE
+from pipecat_subagents.agents import UI_STATE_PROMPT_GUIDE
 ```
 
 The SDK updates the guide alongside the wire format, so apps get new tags
@@ -31,11 +31,15 @@ A multi-line string that documents:
   reading order.
 - How to resolve position references ("top right", "the third one") against
   the most recent `<ui_state>` tree.
+- The `<selection ref="eN">selected text</selection>` block that appears
+  inside `<ui_state>` when the user has text selected on the page, and how
+  to treat it as the deictic referent for "this" / "that" / "what I
+  selected."
 
 Use it directly inside an f-string when building your system prompt:
 
 ```python
-from pipecat_subagents.agents.ui_prompts import UI_STATE_PROMPT_GUIDE
+from pipecat_subagents.agents import UI_STATE_PROMPT_GUIDE
 
 system_prompt = f"""\
 You are a voice-driven music player agent.
diff --git a/api-reference/pipecat-subagents/ui-tools.mdx b/api-reference/pipecat-subagents/ui-tools.mdx
index 31fa7bfd..130d8775 100644
--- a/api-reference/pipecat-subagents/ui-tools.mdx
+++ b/api-reference/pipecat-subagents/ui-tools.mdx
@@ -1,100 +1,144 @@
 ---
 title: "UI Tools"
-description: "Opt-in tool mixins for UIAgent"
+description: "Bundled LLM tool mixin for UIAgent"
 ---
 
 ## Overview
 
-Tool mixins expose focused LLM tools that work with the v1 UI protocol. Apps
-compose them by inheriting alongside their `UIAgent` subclass:
+`ReplyToolMixin` is the canonical bundled-tool shape for `UIAgent`. It
+exposes a single LLM tool — `reply(answer, ...)` — that combines a
+required spoken answer with the optional standard UI actions in one
+turn-terminating call. Apps compose it by inheriting alongside their
+`UIAgent` subclass:
 
 ```python
-from pipecat_subagents.agents import UIAgent
-from pipecat_subagents.agents.ui_tools import (
-    HighlightToolMixin,
-    ScrollToToolMixin,
-)
+from pipecat_subagents.agents import ReplyToolMixin, UIAgent
 
-class MyUIAgent(ScrollToToolMixin, HighlightToolMixin, UIAgent):
+class MyUIAgent(ReplyToolMixin, UIAgent):
     ...
 ```
 
-Keeping these as separate mixins (instead of methods on `UIAgent`) means apps
-opt in to what the LLM sees: a single-screen app with no scrolling shouldn't
-have a `scroll_to` tool cluttering its tool list.
+The bundled-tool design solves a real failure mode: smaller models often
+omit the spoken terminator when scroll-and-highlight tools are exposed
+separately and chainable. Making `answer` a required argument enforced by
+the API schema closes that loop — the model can't call `reply(...)`
+without committing to what it will say.
+
+The mixin covers the canonical app shapes (pointing, reading, form-fill)
+and any blend of them. Apps don't pick a mode up front; the LLM uses
+whichever fields fit the user's request per turn, leaving the rest as
+`null`.
 
 The host class must provide
-[`send_command`](/api-reference/pipecat-subagents/ui-agent#send-command) and
-[`respond_to_task`](/api-reference/pipecat-subagents/ui-agent#respond-to-task)
-(`UIAgent` does both) and must be the target of `@tool` discovery on the LLM
+[`scroll_to`](/api-reference/pipecat-subagents/ui-agent#scroll-to),
+[`highlight`](/api-reference/pipecat-subagents/ui-agent#highlight),
+[`select_text`](/api-reference/pipecat-subagents/ui-agent#select-text),
+[`click`](/api-reference/pipecat-subagents/ui-agent#click),
+[`set_input_value`](/api-reference/pipecat-subagents/ui-agent#set-input-value),
+and [`respond_to_task`](/api-reference/pipecat-subagents/ui-agent#respond-to-task)
+(`UIAgent` does) and must be the target of `@tool` discovery on the LLM
 pipeline.
 
 <Note>
-  The shipped mixin tools are **silent fire-and-forget side effects**. They
-  dispatch a UI command, complete the in-flight task with no `speak` field,
-  and exit. The visual change on the client (the scroll, the highlight) is
-  the user-facing feedback; the voice agent stays quiet for that turn. If
-  you want spoken narration, override the mixin tool and pass a `speak`
-  argument:
-
-  ```python
-  class MyAgent(ScrollToToolMixin, UIAgent):
-      @tool
-      async def scroll_to(self, params, ref: str):
-          await self.send_command("scroll_to", ScrollTo(ref=ref))
-          await self.respond_to_task(speak="Scrolling.")
-          await params.result_callback(None)
-  ```
+  Apps with a different shape — multiple per-domain tools (`play`,
+  `navigate_to_artist`, etc.) where each tool is the whole turn — should skip
+  the mixin and write their own `@tool` methods. Use the action helpers
+  (`scroll_to`, `highlight`, `select_text`, `click`, `set_input_value`) on
+  `UIAgent` directly inside those tool bodies. See [Choosing a tool
+  shape](/subagents/learn/ui-agent#choosing-a-tool-shape) for the decision.
 </Note>
 
-## ScrollToToolMixin
-
-Exposes a `scroll_to(ref)` tool to the LLM. The LLM is meant to call it
-before acting on elements tagged `[offscreen]` in the current `<ui_state>`.
+## ReplyToolMixin
 
-The tool issues a standard
-[`ScrollTo`](/api-reference/pipecat-subagents/ui-commands#scrollto) command;
-the client's
-[`useStandardScrollToHandler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
-(or any app-defined handler) does the actual scrolling.
+Exposes a single bundled `reply(...)` LLM tool. One call per turn, no
+chaining; the required `answer` argument keeps the model from omitting the
+spoken terminator.
 
-### scroll_to
+### reply
 
 ```python
 @tool
-async def scroll_to(self, params: FunctionCallParams, ref: str) -> None
+async def reply(
+    self,
+    params: FunctionCallParams,
+    answer: str,
+    scroll_to: str | None = None,
+    highlight: list[str] | None = None,
+    select_text: str | None = None,
+    fills: list[dict] | None = None,
+    click: list[str] | None = None,
+) -> None
 ```
 
-Scroll an element into view by its snapshot ref.
+Reply to the user. Optionally point at content and act on inputs.
 
-| Parameter | Type                 | Description                                                       |
-| --------- | -------------------- | ----------------------------------------------------------------- |
-| `params`  | `FunctionCallParams` | Framework-provided tool invocation context.                       |
-| `ref`     | `str`                | Ref string from the most recent `<ui_state>` (e.g. `"e42"`). |
+Action fields are dispatched in a fixed order before the answer is spoken:
+`scroll_to`, then `highlight`, then `select_text`, then `fills`, then
+`click`, then the spoken `answer`.
 
-## HighlightToolMixin
+#### Visual / pointing actions
 
-Exposes a `highlight(ref)` tool to the LLM. Gives the LLM a way to visually
-point at a specific element on screen, e.g. answering "which one is
-Radiohead?" by flashing the tile.
+Draw the user's attention without changing app state.
 
-The tool issues a standard
-[`Highlight`](/api-reference/pipecat-subagents/ui-commands#highlight) command;
-the client's
-[`useStandardHighlightHandler`](/api-reference/client/react/hooks#usestandardhighlighthandler)
-(or a custom one) does the actual visual effect.
+- **`scroll_to`** brings an element into view (single ref).
+- **`highlight`** flashes elements briefly (list of refs). Best for short
+  emphasis like a button or a fact.
+- **`select_text`** puts the page's text selection on an element (single
+  ref). Best for "this paragraph" / "the section about X" so the user
+  sees exactly what was meant. Persists until the user clicks elsewhere.
 
-### highlight
+#### State-changing actions
 
-```python
-@tool
-async def highlight(self, params: FunctionCallParams, ref: str) -> None
+Modify form / app state.
+
+- **`fills`** writes values into inputs (list of `{"ref", "value"}`
+  objects, multi-fill in one turn).
+- **`click`** clicks elements (list of refs in order). Use for
+  checkboxes, radios, submit buttons.
+
+#### Parameters
+
+| Parameter     | Type                 | Default | Description                                                                                          |
+| ------------- | -------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `params`      | `FunctionCallParams` |         | Framework-provided tool invocation context.                                                          |
+| `answer`      | `str`                |         | The spoken reply in plain language. One short sentence. No markdown, no symbols.                     |
+| `scroll_to`   | `str \| None`        | `None`  | Optional snapshot ref. Scrolls the element into view before speaking.                                |
+| `highlight`   | `list[str] \| None`  | `None`  | Optional list of snapshot refs. Visually pulses each element.                                        |
+| `select_text` | `str \| None`        | `None`  | Optional snapshot ref. Places the page's text selection on that element.                             |
+| `fills`       | `list[dict] \| None` | `None`  | Optional list of `{"ref": "eN", "value": "..."}` objects. Writes each value into the input at `ref`. |
+| `click`       | `list[str] \| None`  | `None`  | Optional list of snapshot refs to click in order. Use for checkboxes, radios, submit buttons.        |
+
+#### Examples
+
+A pointing turn:
+
+```text
+reply(answer="Here's the iPhone 17.", scroll_to="e5", highlight=["e5"])
 ```
 
-Briefly flash an element on screen by its snapshot ref. After the flash,
-the element returns to its normal appearance.
+A read-side deixis turn:
+
+```text
+reply(
+    answer="That paragraph explains the rationale.",
+    select_text="e42",
+)
+```
+
+A form-fill turn:
+
+```text
+reply(
+    answer="Filled in your details.",
+    fills=[
+        {"ref": "e3", "value": "Marie Curie"},
+        {"ref": "e4", "value": "marie@example.com"},
+    ],
+    click=["e7"],
+)
+```
 
-| Parameter | Type                 | Description                                                       |
-| --------- | -------------------- | ----------------------------------------------------------------- |
-| `params`  | `FunctionCallParams` | Framework-provided tool invocation context.                       |
-| `ref`     | `str`                | Ref string from the most recent `<ui_state>` (e.g. `"e42"`). |
+Defensive guards on the list arguments skip non-conforming entries (a
+malformed `fills` element such as `None` or a bare string is dropped
+rather than raising) so a transient model hiccup doesn't leave the
+single-flight task lock held until the voice-task timeout fires.
diff --git a/api-reference/server/frames/system-frames.mdx b/api-reference/server/frames/system-frames.mdx
index 493729ad..8c0d91b7 100644
--- a/api-reference/server/frames/system-frames.mdx
+++ b/api-reference/server/frames/system-frames.mdx
@@ -422,6 +422,81 @@ Responds to an `RTVIClientMessageFrame`. Include the original client message fra
   `server-response`.
 </ParamField>
 
+## RTVI UI Frames
+
+Pipeline frames for the [UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) message types. The outbound frames (`RTVIUICommandFrame`, `RTVIUITaskFrame`) are pushed by application code and wrapped into the matching `ui-command` / `ui-task` envelope by the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer). The inbound frames (`RTVIUIEventFrame`, `RTVIUISnapshotFrame`, `RTVIUICancelTaskFrame`) are pushed downstream by the [`RTVIProcessor`](/api-reference/server/rtvi/rtvi-processor#ui-agent-protocol) when the matching client message arrives, alongside firing `on_ui_message`.
+
+### RTVIUICommandFrame
+
+A UI command bound for the client. Wrapped into a `UICommandMessage` envelope on the wire.
+
+<ParamField path="command_name" type="str" default='""'>
+  App-defined command name (e.g. `"toast"`, `"navigate"`, `"scroll_to"`, or any
+  app-specific name). Maps to the `data.name` field on the wire.
+</ParamField>
+
+<ParamField path="payload" type="Any" default="None">
+  App-defined payload. Standard payload pydantic models (`Toast`, `Navigate`,
+  `ScrollTo`, `Highlight`, `Focus`, `Click`, `SetInputValue`, `SelectText`)
+  should be converted to a plain dict via `model_dump()` before being placed
+  here; an arbitrary dict works as well.
+</ParamField>
+
+### RTVIUITaskFrame
+
+A UI task lifecycle envelope bound for the client. Wrapped into a `UITaskMessage` envelope on the wire.
+
+<ParamField path="data" type="UITaskData | None" default="None">
+  One of the four task-lifecycle data models from
+  `pipecat.processors.frameworks.rtvi.models`: `UITaskGroupStartedData`,
+  `UITaskUpdateData`, `UITaskCompletedData`, or `UITaskGroupCompletedData`. The
+  `kind` field on each discriminates which lifecycle phase this is.
+</ParamField>
+
+### RTVIUIEventFrame
+
+An inbound `ui-event` from the client. Pushed downstream by the `RTVIProcessor` whenever a `ui-event` message arrives, alongside firing the `on_ui_message` event handler. Pipeline observers and processors that want to react at the pipeline level can match on this frame; code that subscribes to the event handler instead receives the full parsed envelope.
+
+<ParamField path="msg_id" type="str" default='""'>
+  The RTVI message id, as set by the client.
+</ParamField>
+
+<ParamField path="event_name" type="str" default='""'>
+  App-defined event name (the wire `data.name` field).
+</ParamField>
+
+<ParamField path="payload" type="Any" default="None">
+  App-defined payload (the wire `data.payload` field).
+</ParamField>
+
+### RTVIUISnapshotFrame
+
+An inbound accessibility snapshot from the client. Pushed downstream alongside firing `on_ui_message`. Carries the serialized accessibility tree the client took of its DOM.
+
+<ParamField path="msg_id" type="str" default='""'>
+  The RTVI message id, as set by the client.
+</ParamField>
+
+<ParamField path="tree" type="Any" default="None">
+  The serialized accessibility tree.
+</ParamField>
+
+### RTVIUICancelTaskFrame
+
+An inbound user-task-group cancellation request from the client. Pushed downstream alongside firing `on_ui_message`. The server-side framework should look up the matching task group and cancel it (subject to whatever cancellable policy the group was registered with).
+
+<ParamField path="msg_id" type="str" default='""'>
+  The RTVI message id, as set by the client.
+</ParamField>
+
+<ParamField path="task_id" type="str" default='""'>
+  The task group id the client wants cancelled.
+</ParamField>
+
+<ParamField path="reason" type="str | None" default="None">
+  Optional human-readable reason.
+</ParamField>
+
 ## Task Frames
 
 Task frames provide a system-priority mechanism for requesting pipeline actions from outside the normal frame flow. They are converted into their corresponding standard frames when processed.
diff --git a/api-reference/server/rtvi/rtvi-observer.mdx b/api-reference/server/rtvi/rtvi-observer.mdx
index 1ebd5c23..f8068747 100644
--- a/api-reference/server/rtvi/rtvi-observer.mdx
+++ b/api-reference/server/rtvi/rtvi-observer.mdx
@@ -184,3 +184,8 @@ The observer maps Pipecat's internal frames to RTVI protocol messages:
 | `LLMContextFrame`             | `RTVIUserLLMTextMessage`                    |
 | `MetricsFrame`                | `RTVIMetricsMessage`                        |
 | `RTVIServerMessageFrame`      | `RTVIServerMessage`                         |
+| **UI Agent Protocol**         |
+| `RTVIUICommandFrame`          | `UICommandMessage` (`ui-command`)           |
+| `RTVIUITaskFrame`             | `UITaskMessage` (`ui-task`)                 |
+
+The UI Agent inbound message types (`ui-event`, `ui-snapshot`, `ui-cancel-task`) are dispatched directly by the [`RTVIProcessor`](./rtvi-processor#ui-agent-protocol) and don't pass through the observer; the matching pipeline frames (`RTVIUIEventFrame`, `RTVIUISnapshotFrame`, `RTVIUICancelTaskFrame`) are pushed downstream alongside the `on_ui_message` event for processors that want to react at the pipeline level.
diff --git a/api-reference/server/rtvi/rtvi-processor.mdx b/api-reference/server/rtvi/rtvi-processor.mdx
index 2d951ab1..73c132d8 100644
--- a/api-reference/server/rtvi/rtvi-processor.mdx
+++ b/api-reference/server/rtvi/rtvi-processor.mdx
@@ -49,7 +49,10 @@ async def on_client_ready(rtvi):
 ```
 
 <Note>
-  The processor validates the client's RTVI protocol version during the handshake. If the client's major version doesn't match the server's protocol version, an error response is sent but the connection continues. Check server logs for version compatibility warnings.
+  The processor validates the client's RTVI protocol version during the
+  handshake. If the client's major version doesn't match the server's protocol
+  version, an error response is sent but the connection continues. Check server
+  logs for version compatibility warnings.
 </Note>
 
 ### Bot Ready State
@@ -251,3 +254,49 @@ pcClient.onServerMessage((message) => {
 ```
 
 See [Handling Custom Messages from the Server](/client/guides/custom-messaging#handling-custom-messages-from-the-server) for more details and examples.
+
+## UI Agent Protocol
+
+The processor recognizes five first-class RTVI message types for UI Agent traffic — `ui-event`, `ui-snapshot`, `ui-cancel-task` (inbound from client) and `ui-command`, `ui-task` (outbound to client). The full wire format is documented in the [RTVI standard](/client/rtvi-standard#ui-agent-protocol).
+
+### Receiving UI messages
+
+Inbound `ui-event`, `ui-snapshot`, and `ui-cancel-task` messages fire the `on_ui_message` event handler with the parsed envelope. The same dispatch also pushes a typed pipeline frame (`RTVIUIEventFrame`, `RTVIUISnapshotFrame`, or `RTVIUICancelTaskFrame`) so processors and observers downstream can react at the pipeline level — pick whichever shape fits your code path.
+
+```python
+from pipecat.processors.frameworks.rtvi.models import (
+    UIEventMessage, UISnapshotMessage, UICancelTaskMessage,
+)
+
+@rtvi.event_handler("on_ui_message")
+async def on_ui_message(rtvi, message):
+    if isinstance(message, UIEventMessage):
+        # message.data.name, message.data.payload
+        ...
+    elif isinstance(message, UISnapshotMessage):
+        # message.data.tree
+        ...
+    elif isinstance(message, UICancelTaskMessage):
+        # message.data.task_id, message.data.reason
+        ...
+```
+
+The handler is the canonical extension point for direct integrations. Higher-level frameworks like [`pipecat-subagents`](/subagents/learn/ui-agent) subscribe to it from their UI bridge and route the parsed envelopes onto an agent bus.
+
+### Sending UI messages
+
+Outbound `ui-command` and `ui-task` messages flow through dedicated pipeline frames. Push `RTVIUICommandFrame` from any `FrameProcessor` and the `RTVIObserver` wraps it into the `ui-command` envelope on the wire:
+
+```python
+from pipecat.processors.frameworks.rtvi import RTVIUICommandFrame
+from pipecat.processors.frameworks.rtvi.models import Toast
+
+await self.push_frame(
+    RTVIUICommandFrame(
+        command_name="toast",
+        payload=Toast(title="Saved").model_dump(),
+    )
+)
+```
+
+For task-lifecycle traffic, push `RTVIUITaskFrame` carrying one of the four `UITask*Data` discriminated-union members (`UITaskGroupStartedData`, `UITaskUpdateData`, `UITaskCompletedData`, `UITaskGroupCompletedData`). See [RTVI Frames](/api-reference/server/frames/system-frames#rtvi-ui-frames) for the frame definitions and [the RTVI standard](/client/rtvi-standard#ui-task-) for the wire format.
diff --git a/client/rtvi-standard.mdx b/client/rtvi-standard.mdx
index 171417c1..cdffc1d7 100644
--- a/client/rtvi-standard.mdx
+++ b/client/rtvi-standard.mdx
@@ -6,7 +6,11 @@ description: "An overview of the RTVI standard and its key features"
 The RTVI (Real-Time Voice and Video Inference) standard defines a set of message types and structures sent between clients and servers. It is designed to facilitate real-time interactions between clients and AI applications that require voice, video, and text communication. It provides a consistent framework for building applications that can communicate with AI models and the backends running those models in real-time.
 
 <Note>
-  This page documents version 1.0 of the RTVI standard, released in June 2025.
+  This page documents version 1.3 of the RTVI standard. The UI Agent Protocol
+  message types (`ui-event`, `ui-snapshot`, `ui-cancel-task`, `ui-command`,
+  `ui-task`) were added in v1.3 as an additive extension to v1.2. Older clients
+  that pre-date v1.3 ignore the new types; the major-version compatibility check
+  the server runs on `client-ready` still passes for any 1.x peer.
 </Note>
 
 ## Key Features
@@ -299,6 +303,124 @@ Error response to a specific client message. **IMPORTANT**: The `id` should matc
 - **data**:
   - **error**: `string`
 
+### UI Agent Protocol
+
+The UI Agent Protocol lets server-side AI agents observe and drive a client GUI app through structured RTVI messages. Five top-level message types form the protocol:
+
+| Type             | Direction          | Purpose                                                                                                |
+| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `ui-event`       | 🏄 client → server | Named event with payload (e.g. button click, navigation intent)                                        |
+| `ui-snapshot`    | 🏄 client → server | Accessibility tree of the page; grounds agent reasoning in current screen state                        |
+| `ui-cancel-task` | 🏄 client → server | Cancel an in-flight user-facing task group                                                             |
+| `ui-command`     | 🤖 server → client | Named command with payload (toast, scroll, highlight, click, set input value, ...)                     |
+| `ui-task`        | 🤖 server → client | Task lifecycle envelope; one of `group_started` / `task_update` / `task_completed` / `group_completed` |
+
+Server-side, each type is a paired `*Data` / `*Message` pydantic model in `pipecat.processors.frameworks.rtvi.models`. Client-side, each type is a member of `RTVIMessageType` (e.g. `RTVIMessageType.UI_EVENT`). The full agent-side abstraction lives in [`pipecat-subagents`](/subagents/learn/ui-agent); single-LLM Pipecat apps can target this wire format directly via the new pipeline frames (`RTVIUICommandFrame`, `RTVIUITaskFrame`).
+
+#### ui-event 🏄
+
+A named event from the client carrying an app-defined payload. Unlike `client-message`, no server response is expected; the server side fans out the event to handlers and (optionally) injects it into the LLM context as a `<ui_event>` developer message.
+
+- **type**: `'ui-event'`
+- **data**:
+  - **name**: `string`
+
+    App-defined event name (e.g. `"nav_click"`, `"play_track"`, `"set_tab"`). Apps may pick any name; reserved names are prefixed with double underscore (e.g. `__ui_snapshot`).
+
+  - **payload**: `unknown` (optional)
+
+    App-defined payload. Schemaless by design.
+
+#### ui-snapshot 🏄
+
+The current accessibility tree of the page, captured by the client's a11y walker on DOM mutations, focus changes, scroll-end, resize, and tab visibility. The server stores the latest snapshot and renders it as `<ui_state>` into the LLM context so the agent reasons over the current screen.
+
+- **type**: `'ui-snapshot'`
+- **data**:
+  - **tree**: `unknown`
+
+    The serialized accessibility tree. Opaque on the server side; the client owns the shape. See [`A11ySnapshot`](/api-reference/client/js/a11y-snapshot) for the canonical shape produced by `@pipecat-ai/client-js`'s `A11ySnapshotStreamer`.
+
+#### ui-cancel-task 🏄
+
+A request to cancel an in-flight user-facing task group. The server-side framework looks up the matching task group and cancels it (subject to whatever cancellable policy the group was registered with).
+
+- **type**: `'ui-cancel-task'`
+- **data**:
+  - **task_id**: `string`
+
+    The task group id the client wants cancelled.
+
+  - **reason**: `string` (optional)
+
+    Optional human-readable reason logged on the server.
+
+#### ui-command 🤖
+
+A named UI command directing the client to take an action. Client-side dispatchers route on `data.name` to a registered handler (see [`UIAgentClient.registerCommandHandler`](/api-reference/client/js/ui-agent-client) or the `useUICommandHandler` React hook).
+
+- **type**: `'ui-command'`
+- **data**:
+  - **name**: `string`
+
+    App-defined command name. Standard names with default React handlers: `toast`, `navigate`, `scroll_to`, `highlight`, `focus`, `click`, `set_input_value`, `select_text`. Apps may publish their own command names freely.
+
+  - **payload**: `unknown` (optional)
+
+    App-defined payload. Standard payload shapes for the standard commands are documented under [Standard command payloads](#standard-command-payloads) below.
+
+#### ui-task 🤖
+
+A task lifecycle envelope for a user-facing task group dispatched by the server. The `data` field carries one of four lifecycle phases discriminated by `kind`. Client-side, `useUITasks()` from `@pipecat-ai/client-react` reduces these into a live in-flight panel with cancel support.
+
+- **type**: `'ui-task'`
+- **data** (one of):
+
+  **`group_started`** — group dispatched, worker list known.
+  - **kind**: `'group_started'`
+  - **task_id**: `string`
+  - **agents**: `string[]` (optional)
+  - **label**: `string` (optional)
+  - **cancellable**: `boolean`
+  - **at**: `number` (epoch ms)
+
+  **`task_update`** — per-worker progress.
+  - **kind**: `'task_update'`
+  - **task_id**: `string`
+  - **agent_name**: `string`
+  - **data**: `unknown` (optional, worker-defined)
+  - **at**: `number` (epoch ms)
+
+  **`task_completed`** — per-worker terminal.
+  - **kind**: `'task_completed'`
+  - **task_id**: `string`
+  - **agent_name**: `string`
+  - **status**: `string` (`"completed"`, `"cancelled"`, `"failed"`, `"error"`)
+  - **response**: `unknown` (optional)
+  - **at**: `number` (epoch ms)
+
+  **`group_completed`** — group terminal; every worker has responded or the group was cancelled.
+  - **kind**: `'group_completed'`
+  - **task_id**: `string`
+  - **at**: `number` (epoch ms)
+
+#### Standard command payloads
+
+The `ui-command` message carries a free-form `payload`, but eight standard payload shapes ship with the protocol and are recognized by the default React handlers in `@pipecat-ai/client-react`. Apps can use them as-is, override the client handler to customize rendering, or ignore them and define their own command names.
+
+| Command           | Payload shape                                                |
+| ----------------- | ------------------------------------------------------------ |
+| `toast`           | `{title, subtitle?, description?, image_url?, duration_ms?}` |
+| `navigate`        | `{view, params?}`                                            |
+| `scroll_to`       | `{ref?, target_id?, behavior?}`                              |
+| `highlight`       | `{ref?, target_id?, duration_ms?}`                           |
+| `focus`           | `{ref?, target_id?}`                                         |
+| `click`           | `{ref?, target_id?}`                                         |
+| `set_input_value` | `{value, ref?, target_id?, replace?}`                        |
+| `select_text`     | `{ref?, target_id?, start_offset?, end_offset?}`             |
+
+`ref` is a snapshot ref like `"e42"` assigned by the a11y walker; client handlers resolve `ref` first, then fall back to `target_id` (a `document.getElementById` lookup). Pydantic models for these shapes ship in `pipecat.processors.frameworks.rtvi.models` (`Toast`, `Navigate`, `ScrollTo`, `Highlight`, `Focus`, `Click`, `SetInputValue`, `SelectText`); server-side helpers like `UIAgent.send_command` accept them directly and `model_dump` to the wire shape.
+
 ### Advanced LLM Interactions
 
 #### send-text 🏄
diff --git a/docs.json b/docs.json
index aa8021a9..fc82fa36 100644
--- a/docs.json
+++ b/docs.json
@@ -147,6 +147,7 @@
               "subagents/learn/task-coordination",
               "subagents/learn/llm-agent-and-tool-decorator",
               "subagents/learn/structured-conversations-with-flows-agent",
+              "subagents/learn/ui-agent",
               "subagents/learn/custom-voices-per-agent",
               "subagents/learn/distributed-agents",
               "subagents/learn/proxy-agents",
diff --git a/subagents/examples/overview.mdx b/subagents/examples/overview.mdx
index cfee2d84..da6d1edd 100644
--- a/subagents/examples/overview.mdx
+++ b/subagents/examples/overview.mdx
@@ -18,37 +18,41 @@ These examples run all agents in a single process using the default `AsyncQueueB
     The simplest use case: one `BaseAgent` running a complete voice pipeline through the `AgentRunner`. No bus bridge, no multi-agent coordination.
   </Card>
 
-  <Card
-    title="Two LLM Agents"
-    icon="arrows-repeat"
-    href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/agent-handoff/two_llm_agents.py"
-  >
-    A greeter and a support agent that transfer control between each other. Demonstrates agent handoff with `handoff_to()` and the `@tool` decorator.
-  </Card>
+<Card
+  title="Two LLM Agents"
+  icon="arrows-repeat"
+  href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/agent-handoff/two_llm_agents.py"
+>
+  A greeter and a support agent that transfer control between each other.
+  Demonstrates agent handoff with `handoff_to()` and the `@tool` decorator.
+</Card>
 
-  <Card
-    title="Two LLM Agents with TTS"
-    icon="microphone"
-    href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/agent-handoff/two_llm_agents_with_tts.py"
-  >
-    Same as above, but each agent has its own TTS with a distinct voice. The main agent has no TTS -- audio comes from the active LLM agent through the bus.
-  </Card>
+<Card
+  title="Two LLM Agents with TTS"
+  icon="microphone"
+  href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/agent-handoff/two_llm_agents_with_tts.py"
+>
+  Same as above, but each agent has its own TTS with a distinct voice. The main
+  agent has no TTS -- audio comes from the active LLM agent through the bus.
+</Card>
 
-  <Card
-    title="LLM + Flows Agent"
-    icon="diagram-project"
-    href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/agent-handoff/llm_and_flows_agent.py"
-  >
-    An LLM router agent combined with a `FlowsAgent` for structured restaurant reservations. Demonstrates mixing agent types.
-  </Card>
+<Card
+  title="LLM + Flows Agent"
+  icon="diagram-project"
+  href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/agent-handoff/llm_and_flows_agent.py"
+>
+  An LLM router agent combined with a `FlowsAgent` for structured restaurant
+  reservations. Demonstrates mixing agent types.
+</Card>
 
-  <Card
-    title="Parallel Debate"
-    icon="comments"
-    href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/parallel-debate/parallel_debate.py"
-  >
-    A moderator spawns three worker agents in parallel using `task_group()`. Each worker argues from a different perspective. Demonstrates task coordination.
-  </Card>
+<Card
+  title="Parallel Debate"
+  icon="comments"
+  href="https://github.com/pipecat-ai/pipecat-subagents/tree/main/examples/local/parallel-debate/parallel_debate.py"
+>
+  A moderator spawns three worker agents in parallel using `task_group()`. Each
+  worker argues from a different perspective. Demonstrates task coordination.
+</Card>
 
   <Card
     title="Voice Code Assistant"
@@ -59,6 +63,20 @@ These examples run all agents in a single process using the default `AsyncQueueB
   </Card>
 </CardGroup>
 
+## Reference applications
+
+These live in their own repos and exercise a coherent slice of the framework end-to-end, not just one feature.
+
+<CardGroup cols={2}>
+  <Card
+    title="Music Player (UI Agent)"
+    icon="music"
+    href="https://github.com/pipecat-ai/pipecat-music-player"
+  >
+    A voice-driven music browser backed by a live Deezer catalog. Exercises the full [UI Agent](/subagents/learn/ui-agent) surface: voice/UI separation with `attach_ui_bridge`, `<ui_state>`-grounded Q&A, multi-turn deixis with `keep_history=True`, parallel fan-out via `start_user_task_group` with streaming worker results into a Discovery grid, ack-first ordering for slow tools, and a long-lived singleton catalog agent.
+  </Card>
+</CardGroup>
+
 ## Distributed examples
 
 These examples run agents across separate processes or machines, communicating via Redis or WebSocket.
diff --git a/subagents/learn/ui-agent.mdx b/subagents/learn/ui-agent.mdx
new file mode 100644
index 00000000..0d77e47a
--- /dev/null
+++ b/subagents/learn/ui-agent.mdx
@@ -0,0 +1,390 @@
+---
+title: "UI Agent"
+description: "Build voice-driven assistants for GUI apps with structural awareness and a typed action vocabulary."
+---
+
+`UIAgent` is the subagents abstraction for AI agents that observe and drive a client GUI app. It pairs a snapshot-aware LLM (the agent always reasons over the current screen) with a typed action vocabulary (scroll, highlight, fill, click, etc.) and a task-lifecycle protocol for fan-out work the user can see and cancel.
+
+This guide covers the why, the architecture, the action vocabulary, and the deployment shapes. It assumes familiarity with the [agents and runner basics](/subagents/learn/agents-and-runner) and the [task coordination model](/subagents/learn/task-coordination).
+
+## Why we built this
+
+Every voice-enabled GUI app reinvents the same four pieces:
+
+1. **Per-screen prose helpers** that serialize "what's on screen" into a developer message on every navigation. They worked, but they had to be hand-written per screen, drifted from the rendered UI as layouts changed, and ran on the server only when the server itself triggered the navigation. Anything client-only — the user scrolling, focusing a different element, toggling a tab — was invisible to the agent.
+2. **Ad-hoc click-event encoding** — each demo defined its own shapes for "the user clicked something" plus the deserialization back into the agent.
+3. **Ad-hoc server-to-client commands** — each demo rolled its own message dispatch and its own client-side registry of handlers for toast / scroll / navigate.
+4. **Position references with no grounding** — "top right" / "the first one" / "the last song" had no reliable anchor in the prose helpers, so apps had to plan their grid layouts around what the prompt could resolve.
+
+Hand-written prose helpers gave the agent _some_ sense of the screen, enough that "describe this page" worked on a good day. The picture broke easily: server-only state injection missed client-side changes, prose shapes were tightly coupled to the system prompt, and there was no way for the agent to issue a command targeting an element it had just described.
+
+The protocol turns those four patterns into one wire format and adds the missing piece: a **live accessibility snapshot** the agent can actually reason about. The snapshot streams from the client on DOM mutations, focus changes, scroll-end, resize, and tab visibility. The server overwrites a single `_latest_snapshot` slot; the UI agent auto-injects it as `<ui_state>` at the start of every task. Refs (`"e42"`, `"e7"`) are stable across snapshots while a DOM node is mounted, so the LLM can cross-reference between turns ("the button I mentioned earlier") and the agent can point at elements ("flash this one") using the same identifiers it just observed.
+
+### The bigger picture
+
+Most existing apps are mouse / keyboard / touch driven, and that's the right default. People know how to navigate. What they don't have is an assistant that:
+
+- **Searches by voice.** "Show me Radiohead's last album" is one sentence; finding it by clicking is several taps.
+- **Answers questions about what they're looking at.** "Did this album win a Grammy?" doesn't fit any menu.
+- **Resolves deictic references.** "Play that one." "Show me the next one." "Go back."
+- **Fills forms by voice.** "Set the address to 123 Main Street, city San Francisco, zip 94105." Three inputs, one sentence.
+- **Kicks off long-running work without blocking.** "Find me music like Radiohead." A worker fan-out runs in the background, results stream into a panel, the user keeps interacting.
+
+Layer those onto a normal app and any app becomes agent-enabled: the agent takes actions for the user when voice is faster, and answers open-world questions about whatever's on screen. The user keeps clicking when clicking is natural. The agent fills the gap when speech is.
+
+## Architecture: voice agent + UI agent
+
+The canonical shape splits responsibilities across two subagents.
+
+**The voice agent owns the conversation.** It runs the STT/TTS pipeline, the small talk, and the tool-call loop that decides what the user wants. It does not know what's on screen; it does not issue UI commands.
+
+**The UI agent owns the screen.** It receives the live accessibility snapshot from the client, dispatches user click/tap events, and issues commands back to the client when the LLM picks an action tool.
+
+The two communicate through the bus. Voice delegates to UI when an answer needs the screen or an action targets the UI:
+
+```
+                           ┌─────────────────┐
+   user speaks ──► STT ──► │   voice agent   │ ──► TTS ──► user hears
+                           └────────┬────────┘
+                                    │ task: handle_request("…")
+                                    ▼
+                           ┌─────────────────┐
+                           │    UI agent     │
+                           └────────┬────────┘
+                                    │ command: navigate / scroll / …
+                                    ▼
+                                  client
+```
+
+Three concrete scenarios make the split tangible:
+
+- **Voice-only.** "Hello." "Tell me a joke." The voice agent's LLM decides the UI agent isn't needed and replies directly.
+- **Voice + UI for information.** "What's on screen?" "Did this album win a Grammy?" The voice agent delegates to the UI agent; the UI agent's LLM looks at the latest `<ui_state>` and writes a spoken reply.
+- **Voice + UI for action.** "Show me Radiohead." "Play the last song." "Scroll to my favorites." The voice agent delegates; the UI agent's LLM picks an action tool that calls `send_command(...)`. The client re-renders, a fresh snapshot lands on the server, and the next turn starts from current state.
+
+The split keeps each agent's prompt focused: the voice agent's system prompt is about conversation; the UI agent's is about the app's tool vocabulary plus the canonical wire-format guide ([`UI_STATE_PROMPT_GUIDE`](/api-reference/pipecat-subagents/ui-prompts)) the SDK ships.
+
+## How information flows
+
+Four loops run concurrently. Knowing what each one writes is the key to the whole pattern.
+
+| Loop     | Direction       | What it writes                                                              | Triggers an LLM call?           |
+| -------- | --------------- | --------------------------------------------------------------------------- | ------------------------------- |
+| Snapshot | client → server | Latest a11y tree in `_latest_snapshot`                                      | No                              |
+| Event    | client → server | `<ui_event>` developer message in LLM context, plus `@on_ui_event` dispatch | No                              |
+| Command  | server → client | DOM change (scroll, navigate, highlight, click, fill, select, toast, …)     | Yes (response to a task)        |
+| Task     | server → client | `ui-task` lifecycle envelope; client renders an in-flight panel             | Triggered by long-running tools |
+
+**The snapshot loop is observation.** A client-side walker emits an accessibility tree on DOM mutations and other settle-points. The server overwrites a single slot — `_latest_snapshot` internally — and does nothing else. No inference. No LLM context change.
+
+**The event loop is intent.** Curated by the app, not fired automatically. Most user input (scrolls, hovers, focus changes) already shows up in the snapshot loop, so the SDK doesn't try to mirror every DOM event onto the bus. The app picks which interactions count as _intent_ worth telling the agent about and calls `UIAgentClient.sendEvent(name, payload)` for those. When an event arrives, the server appends a `<ui_event>` to the LLM's context and dispatches to any matching `@on_ui_event` handler. Still no LLM call: the click sits in history, ready for the next time the user speaks.
+
+**The command loop is action.** When the UI agent's LLM calls an action tool, the tool publishes a `BusUICommandMessage` on the bus. The bridge translates it into an `RTVIUICommandFrame` that the client routes to the matching command handler.
+
+**The task loop is async work.** When a tool calls `start_user_task_group(...)`, the SDK forwards lifecycle envelopes (`group_started`, `task_update`, `task_completed`, `group_completed`) to the client as `ui-task` messages. The React `useUITasks()` hook reduces these into a live in-flight panel with cancel support — see [Async tasks and lifecycle](#async-tasks-and-lifecycle).
+
+The actual LLM calls happen in the **task loop**: when the user speaks, the voice agent's LLM runs, and if it delegates to the UI agent, that agent's LLM runs too. The just-in-time injection of the latest snapshot happens at the start of the UI agent's task, so the agent always reasons over the current screen rather than a stale tree.
+
+## Sequence: voice + UI for action
+
+The most common turn shape:
+
+```
+ User       Voice agent       UI agent       Client          TTS
+  │              │                │             │             │
+  │              │   snapshot loop running                    │
+  │              │   ─ ─ ─ ─ ─ ─ ─ ─ ─>│ (continuous,         │
+  │              │                │     no LLM call)          │
+  │              │                │             │             │
+  │ "Show me Radiohead"           │             │             │
+  │─────────────>│                │             │             │
+  │              │ LLM picks      │             │             │
+  │              │ handle_request │             │             │
+  │              │ task           │             │             │
+  │              │───────────────>│             │             │
+  │              │                │ inject      │             │
+  │              │                │ <ui_state>  │             │
+  │              │                │ LLM picks   │             │
+  │              │                │ navigate_to │             │
+  │              │                │  _artist    │             │
+  │              │                │ ui-command  │             │
+  │              │                │────────────>│             │
+  │              │                │             │ render      │
+  │              │                │ fresh snapshot            │
+  │              │                │<────────────│             │
+  │              │ response       │             │             │
+  │              │ {speak:"…"}    │             │             │
+  │              │<───────────────│             │             │
+  │              │ speak verbatim │             │             │
+  │              │───────────────────────────────────────────>│
+  │                                                           │
+  │                        audio                              │
+  │<──────────────────────────────────────────────────────────│
+```
+
+Two LLM calls. The command flows back to the client during the same turn; the client re-renders and a fresh snapshot arrives on the server before the next user utterance, so deictic follow-ups ("play the first one") resolve against current state.
+
+## Action vocabulary
+
+The protocol ships with eight standard commands, grouped by what they do:
+
+**Pointing** — draw the user's attention without changing app state.
+
+- `scroll_to(ref)` — scroll an element into view.
+- `highlight(ref)` — briefly flash an element.
+- `focus(ref)` — move input focus.
+
+**Reading** — surface specific content for deictic reference.
+
+- `select_text(ref, [start_offset, end_offset])` — put the page's text selection on a paragraph or sub-range so the user sees exactly what the agent meant. Pairs with the `<selection>` block in `<ui_state>` for the read direction.
+
+**Writing** — modify form / app state.
+
+- `set_input_value(ref, value, [replace])` — write into a text input or textarea. The standard handler refuses `disabled`, `readonly`, and `<input type="hidden">` targets.
+- `click(ref)` — click an element. Use for checkboxes, radios, submit buttons, links. The standard handler silently no-ops on `disabled` targets.
+
+**Presentation** — surface notifications and navigate the app.
+
+- `toast({title, ...})` — transient notification. Apps wire their own toast renderer via [`useToastHandler`](/api-reference/client/react/hooks#usetoasthandler).
+- `navigate({view, params?})` — client-side navigation. Apps wire their own router via [`useNavigateHandler`](/api-reference/client/react/hooks#usenavigatehandler).
+
+Each command has a matching pydantic payload model in [`pipecat.processors.frameworks.rtvi.models`](/api-reference/pipecat-subagents/ui-commands) and a default React handler in `@pipecat-ai/client-react`'s standard handlers. Apps can use the standard handlers, override them, or define their own command names freely.
+
+`UIAgent` exposes plain-method helpers (`scroll_to`, `highlight`, `select_text`, `click`, `set_input_value`) that wrap `send_command(...)` with the standard payloads — see [Action helpers](/api-reference/pipecat-subagents/ui-agent#action-helpers).
+
+## Choosing a tool shape
+
+Three options for exposing the action vocabulary to the LLM. Pick based on your app shape.
+
+### Bundled `ReplyToolMixin`
+
+The canonical shape for general-purpose UI assistants. Inherit
+[`ReplyToolMixin`](/api-reference/pipecat-subagents/ui-tools) alongside your `UIAgent` subclass:
+
+```python
+from pipecat_subagents.agents import ReplyToolMixin, UIAgent
+
+class MyUIAgent(ReplyToolMixin, UIAgent):
+    def build_llm(self) -> LLMService:
+        return OpenAILLMService(
+            api_key=...,
+            settings=OpenAILLMSettings(
+                system_instruction=f"{APP_PROMPT}\n\n{UI_STATE_PROMPT_GUIDE}",
+            ),
+        )
+```
+
+The LLM gets one tool: `reply(answer, scroll_to=None, highlight=None, select_text=None, fills=None, click=None)`. A pointing turn ("where's the iPhone 17?") becomes one call: `reply(answer="Here's the iPhone 17.", scroll_to="e5", highlight=["e5"])`. A form-fill turn ("set the address fields") becomes `reply(answer="Filled in.", fills=[{"ref": "e3", ...}, ...], click=["e7"])`.
+
+The required `answer` argument is enforced by the API schema, so smaller models can't omit the spoken terminator (a real failure mode of the chainable shape we tried first). One tool call per turn, no chaining.
+
+Use this when your tool surface IS the action vocabulary — pointing, reading, form-fill, and any blend.
+
+### Custom `@tool reply` with helpers
+
+For apps that want a tighter schema or app-specific actions on the same turn, write your own `@tool reply` and call the action helpers in the body:
+
+```python
+from pipecat_subagents.agents import UIAgent, tool
+
+class MyUIAgent(UIAgent):
+    @tool
+    async def reply(
+        self,
+        params,
+        answer: str,
+        scroll_to: str | None = None,
+        highlight: list[str] | None = None,
+        # ... only the fields YOUR app actually uses
+    ):
+        if scroll_to:
+            await self.scroll_to(scroll_to)
+        if highlight:
+            for ref in highlight:
+                await self.highlight(ref)
+        await self.respond_to_task(speak=answer)
+        await params.result_callback(None)
+```
+
+Use this when `ReplyToolMixin`'s schema is too broad and you want the model to see only the fields you actually support.
+
+### Per-domain tools where each is the whole turn
+
+For domain-rich apps (a music player, a CRM, a dashboard) where the LLM picks among `play`, `navigate_to_artist`, `add_to_favorites`, `show_info`, etc., write each as its own `@tool`:
+
+```python
+class MyUIAgent(UIAgent):
+    @tool
+    async def navigate_to_artist(self, params, name: str):
+        artist = await self._catalog_find_artist(name)
+        await self._do_navigate_to_artist(artist)
+        await self.respond_to_task(speak=f"Showing {name}.")
+        await params.result_callback(None)
+
+    @tool
+    async def play(self, params, item_title: str):
+        ...
+```
+
+Each tool is the whole turn: it sends commands, completes the in-flight task with `respond_to_task(speak=...)`, and exits. Use the action helpers (`self.scroll_to`, `self.highlight`, etc.) inside tool bodies for visual side effects.
+
+This is the shape the [reference music player](#reference-app) uses. Skip `ReplyToolMixin` here.
+
+## Async tasks and lifecycle
+
+Long-running work — research, recommendation, exploration — shouldn't block the voice agent. The SDK ships a task-lifecycle protocol so the user can see workers in flight and cancel them.
+
+### Server side
+
+`UIAgent.start_user_task_group(...)` is the fire-and-forget primitive:
+
+```python
+@tool
+async def start_discovery(self, params, seed_artist: str):
+    """Find new music similar to a seed artist."""
+    artist = await self._catalog_find_artist(seed_artist)
+    await self.start_user_task_group(
+        "similar_artist",
+        "genre",
+        "two_hop",
+        payload={"seed": artist["name"]},
+        label=f"Discoveries: {artist['name']}",
+        cancellable=True,
+    )
+    await self.respond_to_task(speak=f"Looking for music like {seed_artist}.")
+    await params.result_callback(None)
+```
+
+The SDK manages the asyncio task that holds the group context open while workers run; the tool returns immediately so the voice agent unblocks. Lifecycle envelopes (`group_started` on dispatch, `task_update` for each worker stream emission, `task_completed` for each worker response, `group_completed` when all workers are done) flow to the client as `ui-task` messages.
+
+Workers stream results via `send_task_update`:
+
+```python
+class SimilarArtistRecommender(BaseAgent):
+    async def on_task_request(self, message):
+        for track in self._find_tracks(message.payload["seed"]):
+            await self.send_task_update(
+                message.task_id,
+                update={"kind": "track", "track": track},
+            )
+        await self.send_task_response(message.task_id, response={...})
+```
+
+To turn worker streams into UI commands (e.g. drop tracks into a Discovery grid as they arrive), override `on_task_update` on the UI agent:
+
+```python
+class MyUIAgent(UIAgent):
+    async def on_task_update(self, message):
+        await super().on_task_update(message)
+        update = message.update or {}
+        if update.get("kind") == "track":
+            await self.send_command("add_track", {"track": update["track"]})
+```
+
+### Client side
+
+The React `useUITasks()` hook reduces the lifecycle envelopes into live state:
+
+```tsx
+import { useUITasks } from "@pipecat-ai/client-react";
+
+function DiscoveryPanel() {
+  const { groups, cancelTask } = useUITasks();
+  const inflight = groups.find((g) => g.status === "running");
+  if (!inflight) return null;
+  return (
+    <div>
+      <h3>{inflight.label}</h3>
+      {inflight.cancellable && (
+        <button onClick={() => cancelTask(inflight.taskId, "user requested")}>
+          Cancel
+        </button>
+      )}
+      <progress value={inflight.completedCount} max={inflight.totalCount} />
+    </div>
+  );
+}
+```
+
+`useUITasks` requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside the [`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider).
+
+When the user clicks Cancel, `cancelTask` sends a `ui-cancel-task` message; the SDK on the server side cancels the matching group (subject to `cancellable=True` having been set when the group was dispatched).
+
+Use `start_user_task_group` for fire-and-forget. Use the [`user_task_group(...)`](/api-reference/pipecat-subagents/ui-agent#user-task-group) context manager when the caller wants to consume worker events inline (`async for event in tg`) or react to results before returning.
+
+## When (not) to use this
+
+Two questions, in order. First **does this fit your app**, then **which deployment shape**.
+
+### App-shape fit
+
+Good fit when at least one is true:
+
+- **Rich screens where voice search beats click-paths**: catalogs, browsers, dashboards, file explorers, e-commerce.
+- **Screen-grounded Q&A**: "tell me about what I'm looking at" matters.
+- **Form-fill by voice**: applications, surveys, data entry.
+- **Multi-turn deictic dialog**: "play that one", "the next one", "more like them".
+- **Parallel / long-running work the user shouldn't block on**: research, recommendation, exploration.
+
+Poor fit when:
+
+- **Pure voice-only apps with no UI to ground in**. Just use a regular Pipecat LLM agent — the snapshot machinery is dead weight.
+- **Apps that are already agent-friendly through clicking**. One-action apps, single-screen forms with three fields. The protocol's overhead outweighs the benefit.
+- **Pixel-level UI control or headless automation** (drawing, gestures, browser automation). The accessibility-tree abstraction doesn't capture spatial / pixel intent.
+
+### Deployment shape
+
+Once it fits, three shapes. From least to most infrastructure:
+
+#### Single LLM, snapshot-aware (no subagents)
+
+Drop [`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot) into your client, render the snapshot into a developer message in your Pipecat pipeline, give your LLM tools that emit the typed RTVI frames ([`RTVIUICommandFrame`](/api-reference/server/frames/system-frames#rtviuicommandframe), [`RTVIUITaskFrame`](/api-reference/server/frames/system-frames#rtviuitaskframe)). Less code than wiring up a bus + bridge.
+
+Use this when you have a single LLM doing both conversation and UI work, no multi-agent fan-out. The wire format itself ([RTVI v1.3](/client/rtvi-standard#ui-agent-protocol)) is canonical in Pipecat; subagents builds the agent abstraction on top.
+
+#### Voice + UI separation (subagents `UIAgent`)
+
+`VoiceAgent` (LLM, bridged to STT/TTS) + `UIAgent` (LLM, owns screen state) on a bus, joined by [`attach_ui_bridge`](/api-reference/pipecat-subagents/messages#attach-ui-bridge). Voice delegates every UI-touching utterance via `self.task("ui", ...)`. The UI agent's LLM runs against `<ui_state>` and emits commands; the voice agent speaks the result verbatim.
+
+Use this when the conversation layer should stay focused on TTS/STT and dialog management, and a separate agent should own screen state and the action vocabulary. **The canonical pattern**, and what most production apps will reach for.
+
+#### Multi-agent peer subagents
+
+Full subagents framework: `UIAgent` plus worker peer agents on the bus, task fan-out via `start_user_task_group`, peers that share state (catalog, search index, user profile).
+
+Use this when long-running work fans out to multiple workers, agents share state across the bus, or the agent topology is large enough that multi-agent orchestration earns its complexity.
+
+### Subagents-specific knob
+
+`UIAgent` accepts a `keep_history` flag that picks between two task-context modes:
+
+- **`keep_history=False`** (default): clear the LLM context at the start of every task. Each task starts with just the current `<ui_state>` and the user's query. Matches the canonical stateless-delegate pattern.
+- **`keep_history=True`**: accumulate history across tasks. Pair with `enable_auto_context_summarization=True` on the assistant aggregator to keep the context bounded over long sessions. Use when deixis spans multiple turns ("show me the next one", "more like them") and the agent needs to remember what was discussed.
+
+The auto-injection of `<ui_state>` is hard-wired to `on_task_request`, so a single bridged `UIAgent` would silently never inject the snapshot. The `UIAgent` constructor raises `ValueError` if you try (`bridged != None` with default `auto_inject_ui_state=True`). The canonical pattern is a non-bridged `UIAgent` receiving delegated tasks from a separate voice `LLMAgent`.
+
+## Reference app
+
+The [`pipecat-music-player`](https://github.com/pipecat-ai/pipecat-music-player) demo exercises every pattern in this guide end-to-end against a live Deezer catalog:
+
+- Voice/UI separation with `attach_ui_bridge`
+- `<ui_state>`-grounded Q&A with `keep_history=True` and auto context summarization
+- Multi-turn deixis ("play that one", "more like them")
+- Per-domain `@tool` shape (skipping `ReplyToolMixin`)
+- Parallel fan-out via `start_user_task_group` with three worker recommenders, streaming results into a Discovery grid, with cancel
+- Long-lived singleton `CatalogAgent` peer of the `MusicAgent` root
+
+Read it when "show me code" beats "tell me about it."
+
+## API reference
+
+- [`UIAgent`](/api-reference/pipecat-subagents/ui-agent) — class reference, constructor, methods, action helpers.
+- [`ReplyToolMixin`](/api-reference/pipecat-subagents/ui-tools) — bundled-tool mixin reference.
+- [Standard command payloads](/api-reference/pipecat-subagents/ui-commands) — `Toast`, `Navigate`, `ScrollTo`, `Highlight`, `Focus`, `Click`, `SetInputValue`, `SelectText`.
+- [`UI_STATE_PROMPT_GUIDE`](/api-reference/pipecat-subagents/ui-prompts) — canonical prompt fragment for the system prompt.
+- [Bus messages](/api-reference/pipecat-subagents/messages) — `BusUIEventMessage`, `BusUICommandMessage`, the four `BusUITask*` lifecycle messages, and `attach_ui_bridge`.
+- [`@on_ui_event`](/api-reference/pipecat-subagents/decorators#on_ui_event) — decorator for client-event handlers (no LLM call).
+- [RTVI standard — UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) — on-the-wire message types.
+- [RTVI UI frames](/api-reference/server/frames/system-frames#rtvi-ui-frames) — pipeline frames for direct integration.
+- [`UIAgentClient`](/api-reference/client/js/ui-agent-client) — client-side wrapper.
+- [React hooks](/api-reference/client/react/hooks) — `useA11ySnapshot`, `useUICommandHandler`, `useUITasks`, the standard handlers.

From 6ba90decec1e1a5ef6f67195492df167ce7ca1bb Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Wed, 6 May 2026 15:49:42 -0400
Subject: [PATCH 3/4] Update for latest RTVI protocol changes

---
 api-reference/client/js/a11y-snapshot.mdx     |  81 +++++---
 api-reference/client/js/callbacks.mdx         |  29 ++-
 api-reference/client/js/client-methods.mdx    | 104 +++++++++-
 api-reference/client/js/overview.mdx          |   6 +-
 api-reference/client/js/ui-agent-client.mdx   | 183 +++---------------
 api-reference/client/react/components.mdx     |  48 +----
 api-reference/client/react/hooks.mdx          |  51 ++---
 .../pipecat-subagents/decorators.mdx          |   2 +-
 api-reference/pipecat-subagents/messages.mdx  |   7 +-
 api-reference/pipecat-subagents/ui-agent.mdx  |  18 +-
 .../pipecat-subagents/ui-commands.mdx         |  63 +++---
 api-reference/server/frames/system-frames.mdx |  15 +-
 api-reference/server/rtvi/rtvi-processor.mdx  |   4 +-
 client/rtvi-standard.mdx                      |  20 +-
 subagents/learn/ui-agent.mdx                  |  24 +--
 15 files changed, 297 insertions(+), 358 deletions(-)

diff --git a/api-reference/client/js/a11y-snapshot.mdx b/api-reference/client/js/a11y-snapshot.mdx
index 39abdccb..16f2be99 100644
--- a/api-reference/client/js/a11y-snapshot.mdx
+++ b/api-reference/client/js/a11y-snapshot.mdx
@@ -1,30 +1,33 @@
 ---
 title: "Accessibility Snapshots"
-description: "Stream the document's accessibility tree to the server as <ui_state>"
+description: "Stream a web document's accessibility tree to the server as <ui_state>"
 ---
 
 ## Overview
 
-The accessibility-snapshot module produces a structured tree of the document
+The accessibility-snapshot module produces a structured tree of a web document
 that the server-side
 [`UIAgent`](/api-reference/pipecat-subagents/ui-agent) renders into LLM
 context as `<ui_state>`. Shape and filtering are inspired by Playwright's
 accessibility snapshot and the Playwright MCP server's LLM-facing format:
 the goal is a compact, semantically meaningful tree, not a raw DOM dump.
 
+This page documents the web SDK implementation. The RTVI `ui-snapshot` wire
+shape is intentionally platform-neutral: native clients can produce the same
+`A11ySnapshot` shape from iOS, Android, or other platform accessibility APIs.
+
 ```javascript
 import {
-  A11ySnapshotStreamer,
   snapshotDocument,
   findElementByRef,
 } from "@pipecat-ai/client-js";
 ```
 
-The streaming side is handled by `A11ySnapshotStreamer` (or
-[`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot) in
-React). The walker (`snapshotDocument`) is exposed for apps that need a
-one-off snapshot, and `findElementByRef` resolves a server-supplied ref
-back to a live DOM element for command handlers.
+Most apps should start streaming through the managed `PipecatClient` API
+or [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot)
+in React. The walker (`snapshotDocument`) is exposed for apps that need a
+one-off snapshot, and `findElementByRef` resolves a server-supplied ref back
+to a live DOM element for command handlers.
 
 <Note>
   Apps can mark a subtree as PII / sensitive by adding `data-a11y-exclude` to
@@ -37,34 +40,52 @@ back to a live DOM element for command handlers.
 
 ```typescript
 class A11ySnapshotStreamer {
-  constructor(client: UIAgentClient, options?: A11ySnapshotStreamerOptions);
+  constructor(
+    emitSnapshot: A11ySnapshotEmitter,
+    options?: A11ySnapshotStreamerOptions,
+  );
   start(): void;
   stop(): void;
 }
 ```
 
-Framework-agnostic helper that drives accessibility-snapshot streaming.
-Wraps the walker, a `MutationObserver`, and the other triggers
-(`scrollend`, `resize`, focus, `visibilitychange`) into a single object
-with a `start` / `stop` lifecycle.
+Low-level, framework-agnostic helper that drives accessibility-snapshot
+streaming. It wraps the walker, a `MutationObserver`, and the other triggers
+(`scrollend`, `resize`, focus, `visibilitychange`) into a single object with a
+`start` / `stop` lifecycle.
+
+Vanilla web apps should usually use the managed client methods:
 
 ```javascript
-import { A11ySnapshotStreamer, UIAgentClient } from "@pipecat-ai/client-js";
+import { PipecatClient } from "@pipecat-ai/client-js";
 
-const ui = new UIAgentClient(pcClient);
-ui.attach();
+const pcClient = new PipecatClient({
+  /* ... */
+});
 
-const streamer = new A11ySnapshotStreamer(ui);
-streamer.start();
+pcClient.startA11ySnapshotStream({ debounceMs: 200 });
 
 // Later
-streamer.stop();
+pcClient.stopA11ySnapshotStream();
+```
+
+If you need to provide your own transport or batching layer, instantiate the
+low-level streamer directly and provide an emitter callback:
+
+```javascript
+import { A11ySnapshotStreamer } from "@pipecat-ai/client-js";
+
+const streamer = new A11ySnapshotStreamer((snapshot) => {
+  emitUISnapshot({ tree: snapshot });
+});
+
+streamer.start();
 ```
 
 <Note>
   React apps should prefer
   [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), which
-  is a thin lifecycle wrapper around this class.
+  starts and stops the managed `PipecatClient` stream.
 </Note>
 
 ### Triggers
@@ -174,6 +195,16 @@ hooks call this internally.
 
 ## Types
 
+### A11ySnapshotEmitter
+
+```typescript
+type A11ySnapshotEmitter = (snapshot: A11ySnapshot) => void;
+```
+
+Callback passed to the low-level `A11ySnapshotStreamer`. The managed
+`PipecatClient` stream provides this callback internally and sends each
+snapshot as a `ui-snapshot` RTVI message with `{ tree: snapshot }`.
+
 ### A11yNode
 
 One node in the accessibility snapshot tree.
@@ -194,7 +225,7 @@ interface A11yNode {
 
 | Field      | Type         | Description                                                                                                        |
 | ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `ref`      | `string`     | Stable reference id of the form `e{N}`. Persists across snapshots while the DOM node is mounted.                   |
+| `ref`      | `string`     | Stable web reference id of the form `e{N}`. Persists across snapshots while the DOM node is mounted.               |
 | `role`     | `string`     | ARIA role (explicit or tag-derived).                                                                               |
 | `name`     | `string`     | Accessible name, truncated to 100 chars.                                                                           |
 | `value`    | `string`     | Current value for inputs (omitted for passwords), progress, etc.                                                   |
@@ -216,7 +247,9 @@ interface A11ySnapshot {
 
 Shape of the payload inside a `ui-snapshot` RTVI message. A full tree is sent
 on each update; the server keeps the latest and renders it into
-`<ui_state>...</ui_state>` when an agent injects it.
+`<ui_state>...</ui_state>` when an agent injects it. The fields are shared
+across client platforms; details in this page describe how the web SDK fills
+them from the DOM.
 
 | Field         | Type            | Description                                                                                     |
 | ------------- | --------------- | ----------------------------------------------------------------------------------------------- |
@@ -246,8 +279,6 @@ The user's current text selection. Lets the agent ground deictic references like
 
 ## See also
 
-- [`UIAgentClient`](/api-reference/client/js/ui-agent-client) — the wrapper the streamer dispatches through.
+- [`PipecatClient` UI methods](/api-reference/client/js/client-methods#ui-agent-protocol) — the client-side UI Agent Protocol API.
 - [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot) — React hook idiom.
 - [UI Agent Protocol on the wire](/client/rtvi-standard#ui-snapshot-) — the `ui-snapshot` RTVI message that carries the tree.
-
-The streamer dispatches via `PipecatClient.sendRTVIMessage(RTVIMessageType.UI_SNAPSHOT, { tree })` (RTVI v1.3); apps that build their own snapshot pipeline can target the same wire shape directly without using `UIAgentClient`.
diff --git a/api-reference/client/js/callbacks.mdx b/api-reference/client/js/callbacks.mdx
index 27e24856..7382b5cc 100644
--- a/api-reference/client/js/callbacks.mdx
+++ b/api-reference/client/js/callbacks.mdx
@@ -116,6 +116,23 @@ pcClient.on(RTVIEvent.BotReady, () => console.log("Bot ready via event"));
   is true, the client will automatically disconnect.
 </ParamField>
 
+### UI Agent Protocol
+
+<ParamField path="onUICommand" type="data:UICommandEnvelope">
+  Receives a `ui-command` envelope from the server. Switch on `data.command` to
+  route app-specific commands, or use
+  [`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler)
+  in React.
+</ParamField>
+
+<ParamField path="onUITask" type="data:UITaskEnvelope">
+  Receives each `ui-task` lifecycle envelope from the server:
+  `group_started`, `task_update`, `task_completed`, or `group_completed`.
+  React apps can use [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider)
+  and [`useUITasks`](/api-reference/client/react/hooks#useuitasks) to reduce
+  these envelopes into renderable task state.
+</ParamField>
+
 ### Media and devices
 
 <ParamField path="onAvailableMicsUpdated" type="mics:MediaDeviceInfo[]">
@@ -446,11 +463,13 @@ Here's the complete reference mapping events to their corresponding callbacks:
 
 ### Message and Error Events
 
-| Event Name      | Callback Name     | Data Type     |
-| --------------- | ----------------- | ------------- |
-| `ServerMessage` | `onServerMessage` | `any`         |
-| `MessageError`  | `onMessageError`  | `RTVIMessage` |
-| `Error`         | `onError`         | `RTVIMessage` |
+| Event Name      | Callback Name     | Data Type           |
+| --------------- | ----------------- | ------------------- |
+| `ServerMessage` | `onServerMessage` | `any`               |
+| `MessageError`  | `onMessageError`  | `RTVIMessage`       |
+| `Error`         | `onError`         | `RTVIMessage`       |
+| `UICommand`     | `onUICommand`     | `UICommandEnvelope` |
+| `UITask`        | `onUITask`        | `UITaskEnvelope`    |
 
 ### Media Events
 
diff --git a/api-reference/client/js/client-methods.mdx b/api-reference/client/js/client-methods.mdx
index 42529e03..51570504 100644
--- a/api-reference/client/js/client-methods.mdx
+++ b/api-reference/client/js/client-methods.mdx
@@ -181,22 +181,106 @@ Sends a custom request to the bot and expects a response. This is useful for que
   type `'error-response'`.
 </ParamField>
 
-### sendRTVIMessage()
+## UI Agent Protocol
 
-`sendRTVIMessage(msgType: RTVIMessageType, data?: unknown): void`
+These methods implement the client side of the [UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) directly on `PipecatClient`.
 
-Send a first-class typed RTVI message. Bypasses the `client-message` envelope (which `sendClientMessage` uses) and dispatches the supplied type directly. Used internally by [`UIAgentClient.sendEvent`](/api-reference/client/js/ui-agent-client#sendevent), [`UIAgentClient.cancelTask`](/api-reference/client/js/ui-agent-client#canceltask), and [`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot) to emit `ui-event`, `ui-cancel-task`, and `ui-snapshot` messages respectively.
+### sendUIEvent()
 
-Available to apps that want to emit a typed RTVI message themselves (e.g. an app-specific subscriber to one of the `ui-*` types, or a future protocol extension).
+`sendUIEvent<T = unknown>(event: string, payload?: T): void`
 
-<ParamField path="msgType" type="RTVIMessageType" required>
-  A member of the `RTVIMessageType` enum (e.g. `RTVIMessageType.UI_EVENT`,
-  `RTVIMessageType.UI_SNAPSHOT`, `RTVIMessageType.UI_CANCEL_TASK`).
+Send a named UI event to the server as a first-class `ui-event` RTVI message. Unlike `sendClientMessage`, this does not expect a server response.
+
+```typescript
+pcClient.sendUIEvent("nav_click", { view: "settings" });
+```
+
+<ParamField path="event" type="string" required>
+  App-defined event name. Must match the `name` argument on a server-side
+  `@on_ui_event(name)` handler if a subagent should react.
 </ParamField>
 
-<ParamField path="data" type="unknown">
-  Optional `data` payload for the message. The shape depends on the `msgType`;
-  see the [RTVI standard](/client/rtvi-standard) for the canonical shapes.
+<ParamField path="payload" type="T">
+  App-defined payload. Schemaless. Optional.
+</ParamField>
+
+### startA11ySnapshotStream()
+
+`startA11ySnapshotStream(options?: A11ySnapshotStreamerOptions): void`
+
+Start a managed accessibility snapshot stream. The client emits `ui-snapshot` messages when the document changes or settles. Calling this again replaces the previous managed stream with the new options.
+
+```typescript
+pcClient.startA11ySnapshotStream({ debounceMs: 200 });
+```
+
+<ParamField path="options" type="A11ySnapshotStreamerOptions">
+  Optional debounce, viewport tracking, and logging options. See
+  [Accessibility Snapshots](/api-reference/client/js/a11y-snapshot).
+</ParamField>
+
+### stopA11ySnapshotStream()
+
+`stopA11ySnapshotStream(): void`
+
+Stop the managed accessibility snapshot stream, if one is active. `disconnect()` also stops the managed stream.
+
+```typescript
+pcClient.stopA11ySnapshotStream();
+```
+
+### UI command events
+
+Subscribe to `RTVIEvent.UICommand` and filter by `data.command` for named `ui-command` messages sent by the server. See [Callbacks and events](/api-reference/client/js/callbacks) for the full event/callback mapping.
+
+```typescript
+import { RTVIEvent } from "@pipecat-ai/client-js";
+
+const onCommand = (data) => {
+  if (data.command !== "toast") return;
+  showToast(data.payload.title, data.payload.description);
+};
+
+pcClient.on(RTVIEvent.UICommand, onCommand);
+
+// Later
+pcClient.off(RTVIEvent.UICommand, onCommand);
+```
+
+You can also use the `onUICommand` constructor callback for one central handler, or [`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler) in React.
+
+### UI task events
+
+Subscribe to `RTVIEvent.UITask` for every `ui-task` lifecycle envelope from the server. The listener fires for each lifecycle phase: `group_started`, `task_update`, `task_completed`, and `group_completed`. Switch on `envelope.kind` to react to specific phases. See [Callbacks and events](/api-reference/client/js/callbacks) for the full event/callback mapping.
+
+```typescript
+const onTask = (envelope) => {
+  if (envelope.kind === "task_update") {
+    console.log(envelope.agent_name, envelope.data);
+  }
+};
+
+pcClient.on(RTVIEvent.UITask, onTask);
+
+// Later
+pcClient.off(RTVIEvent.UITask, onTask);
+```
+
+You can also use the `onUITask` constructor callback for one central handler, or [`useUITasks`](/api-reference/client/react/hooks#useuitasks) in React.
+
+### cancelUITask()
+
+`cancelUITask(taskId: string, reason?: string): void`
+
+Ask the server to cancel an in-flight user task group. Sends a first-class `ui-cancel-task` RTVI message. The server honors the request only when the group was registered as cancellable.
+
+<ParamField path="taskId" type="string" required>
+  Shared task identifier of the group to cancel. Read this from a task group's
+  `taskId`, or from the `task_id` on a raw task envelope.
+</ParamField>
+
+<ParamField path="reason" type="string">
+  Optional human-readable reason logged on the server.
 </ParamField>
 
 ## Devices
diff --git a/api-reference/client/js/overview.mdx b/api-reference/client/js/overview.mdx
index 772e46db..58a38eb2 100644
--- a/api-reference/client/js/overview.mdx
+++ b/api-reference/client/js/overview.mdx
@@ -86,11 +86,11 @@ pcClient.connect({
     Daily, SmallWebRTC, WebSocket, and other transports
   </Card>
   <Card
-    title="UIAgentClient"
+    title="UI Agent Protocol"
     icon="window"
-    href="/api-reference/client/js/ui-agent-client"
+    href="/api-reference/client/js/client-methods#ui-agent-protocol"
   >
-    Send UI events and dispatch UI commands with the v1 UI Agent protocol
+    Send UI events and dispatch UI commands with PipecatClient
   </Card>
   <Card
     title="A11y Snapshots"
diff --git a/api-reference/client/js/ui-agent-client.mdx b/api-reference/client/js/ui-agent-client.mdx
index 8b5cb372..f4be1c86 100644
--- a/api-reference/client/js/ui-agent-client.mdx
+++ b/api-reference/client/js/ui-agent-client.mdx
@@ -1,183 +1,48 @@
 ---
-title: "UIAgentClient"
-description: "Client-side surface for the UI Agent pattern"
+title: "UI Agent Protocol"
+description: "Client-side PipecatClient methods for the UI Agent Protocol"
 ---
 
 ## Overview
 
-`UIAgentClient` wraps an existing `PipecatClient` with the [UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) (RTVI v1.3):
-
-- **`sendEvent(name, payload)`** for client → server events. Sends as a first-class `ui-event` RTVI message.
-- **`registerCommandHandler(name, handler)`** for server → client commands. Handlers dispatch on the command name extracted from `RTVIEvent.UICommand` payloads (the `ui-command` envelope).
-- **`addTaskListener(listener)`** for server → client task lifecycle envelopes (`ui-task`). Listeners receive every `group_started` / `task_update` / `task_completed` / `group_completed` envelope in arrival order.
-- **`cancelTask(task_id, reason?)`** to ask the server to cancel an in-flight user task group.
-
-Construction does not subscribe to anything. Call `attach()` to start listening for `RTVIEvent.UICommand` and `RTVIEvent.UITask`, and store the returned detach function to stop. The React provider ([`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider)) does this automatically inside a `useEffect` so subscription lifecycle follows mount/unmount (including `StrictMode`'s double-invoke).
+The UI Agent Protocol is exposed directly on `PipecatClient`. There is no separate client wrapper.
 
 ```javascript
-import { PipecatClient, UIAgentClient } from "@pipecat-ai/client-js";
+import { PipecatClient, RTVIEvent } from "@pipecat-ai/client-js";
 
 const pcClient = new PipecatClient({
   /* ... */
 });
-const uiClient = new UIAgentClient(pcClient);
-const detach = uiClient.attach();
 
-uiClient.registerCommandHandler("toast", (payload) => {
-  showToast(payload.title, payload.subtitle);
-});
+const onCommand = (data) => {
+  if (data.command === "toast") {
+    showToast(data.payload.title, data.payload.subtitle);
+  }
+};
 
-uiClient.sendEvent("nav_click", { view: "settings" });
+pcClient.on(RTVIEvent.UICommand, onCommand);
+pcClient.startA11ySnapshotStream({ debounceMs: 200 });
+pcClient.sendUIEvent("nav_click", { view: "settings" });
 
 // Later, on cleanup
-detach();
-```
-
-## Constructor
-
-```typescript
-new UIAgentClient(client: PipecatClient)
-```
-
-<ParamField path="client" type="PipecatClient" required>
-  An existing Pipecat client. The UI agent client wraps this without taking
-  ownership; the host is still responsible for connecting and disconnecting the
-  underlying client.
-</ParamField>
-
-## Properties
-
-### pipecatClient
-
-```typescript
-get pipecatClient: PipecatClient
+pcClient.off(RTVIEvent.UICommand, onCommand);
+pcClient.stopA11ySnapshotStream();
 ```
 
-The underlying Pipecat client, exposed as an escape hatch when an app needs to call `PipecatClient` methods directly.
-
 ## Methods
 
-### sendEvent
-
-```typescript
-sendEvent<T = unknown>(name: string, payload?: T): void
-```
-
-Send a named UI event to the server as a first-class `ui-event` RTVI message. Internally calls `PipecatClient.sendRTVIMessage(RTVIMessageType.UI_EVENT, ...)`. The server-side bridge installed by `attach_ui_bridge` republishes the event as `BusUIEventMessage` on the agent bus, where matching `@on_ui_event(name)` handlers run.
-
-<ParamField path="name" type="string" required>
-  App-defined event name. Must match the `name` argument on a server-side
-  `@on_ui_event(name)` handler if the agent should react.
-</ParamField>
-
-<ParamField path="payload" type="T">
-  App-defined payload. Schemaless. Optional.
-</ParamField>
-
-### registerCommandHandler
-
-```typescript
-registerCommandHandler<T = unknown>(
-  name: string,
-  handler: UICommandHandler<T>,
-): void
-```
-
-Register a handler for a named UI command. Overwrites any existing handler for the same name.
-
-<ParamField path="name" type="string" required>
-  App-defined command name. Must match the `name` argument the server passes to
-  `UIAgent.send_command(name, payload)`.
-</ParamField>
-
-<ParamField path="handler" type="UICommandHandler<T>" required>
-  Callback invoked with the command payload. Sync or async; rejected promises
-  surface to the host's unhandled-rejection channel rather than being swallowed.
-</ParamField>
-
-### unregisterCommandHandler
-
-```typescript
-unregisterCommandHandler(name: string): void
-```
-
-Remove the handler previously registered for `name`, if any. No-op when no handler is registered.
-
-### unregisterAllCommandHandlers
-
-```typescript
-unregisterAllCommandHandlers(): void
-```
-
-Remove all registered command handlers.
-
-### addTaskListener
-
-```typescript
-addTaskListener(listener: UITaskListener): void
-```
-
-Subscribe a listener to every `ui-task` envelope. The listener fires for each lifecycle phase: `group_started`, `task_update`, `task_completed`, `group_completed`. Switch on `envelope.kind` to react to specific phases.
-
-The React `useUITasks` hook is the recommended consumer for app code; this lower-level listener is for hosts that want to drive their own state.
-
-<ParamField path="listener" type="UITaskListener" required>
-  Callback invoked once per envelope:
-  `(envelope: UITaskEnvelope) => void`. The discriminated `kind` field
-  (`"group_started"` / `"task_update"` / `"task_completed"` /
-  `"group_completed"`) selects which envelope shape arrived.
-</ParamField>
-
-### removeTaskListener
-
-```typescript
-removeTaskListener(listener: UITaskListener): void
-```
-
-Remove a previously added task listener. No-op when the listener is not registered.
-
-### removeAllTaskListeners
-
-```typescript
-removeAllTaskListeners(): void
-```
-
-Remove every task listener.
-
-### cancelTask
-
-```typescript
-cancelTask(task_id: string, reason?: string): void
-```
-
-Ask the server to cancel an in-flight user task group. Sends a first-class `ui-cancel-task` RTVI message; the server-side `UIAgent` routes this to `cancel_task` on the matching group. The server honors the request only when the group was registered with `cancellable=True`; otherwise the request is silently ignored.
-
-<ParamField path="task_id" type="string" required>
-  The shared task identifier of the group to cancel. Read this from a task
-  group's `taskId` (`useUITasks` surfaces it) or from the `task_id` on any
-  envelope you saw for the group.
-</ParamField>
-
-<ParamField path="reason" type="string">
-  Optional human-readable reason. Logged on the server alongside the cancel
-  request.
-</ParamField>
-
-### attach
-
-```typescript
-attach(): () => void
-```
-
-Subscribe to `RTVIEvent.UICommand` and `RTVIEvent.UITask` on the underlying `PipecatClient`. Returns a detach function that unsubscribes.
-
-Safe to call more than once: each call installs an independent pair of listeners. Invoke the returned function to remove them. The React provider calls this inside `useEffect` and uses the returned function as the cleanup, so subscription lifecycle follows React's mount/unmount cycle (including `StrictMode`'s double-invoke in development).
+See [`PipecatClient` methods](/api-reference/client/js/client-methods#ui-agent-protocol) for:
 
-**Returns:** A `() => void` detach function.
+- `sendUIEvent(event, payload?)`
+- `startA11ySnapshotStream(options?)`
+- `stopA11ySnapshotStream()`
+- `RTVIEvent.UICommand` / `onUICommand`
+- `RTVIEvent.UITask` / `onUITask`
+- `cancelUITask(taskId, reason?)`
 
 ## See also
 
-- [`PipecatClient.sendRTVIMessage`](/api-reference/client/js/client-methods#sendrtvimessage) — the underlying primitive `sendEvent` and `cancelTask` use to send first-class typed RTVI messages.
-- [`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot) — streams the accessibility tree as `ui-snapshot` messages.
-- [`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider) — React idiom for the same surface.
+- [`PipecatClient` UI methods](/api-reference/client/js/client-methods#ui-agent-protocol) — the client-side API.
+- [`Accessibility Snapshots`](/api-reference/client/js/a11y-snapshot) — snapshot shape, managed streaming, and low-level helpers.
+- [`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler) — React command handler hook.
 - [UI Agent Protocol on the wire](/client/rtvi-standard#ui-agent-protocol) — the underlying RTVI message types.
diff --git a/api-reference/client/react/components.mdx b/api-reference/client/react/components.mdx
index 68473237..194839f5 100644
--- a/api-reference/client/react/components.mdx
+++ b/api-reference/client/react/components.mdx
@@ -21,55 +21,17 @@ The root component for providing Pipecat client context to your application. It
   A singleton instance of `PipecatClient`
 </ParamField>
 
-## UIAgentProvider
-
-Wraps its children with a `UIAgentClient` bound to a Pipecat client. Mount
-inside (or alongside) `PipecatClientProvider`. Descendants can then call
-[`useUIAgentClient`](/api-reference/client/react/hooks#useuiagentclient),
-[`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler),
-[`useUIEventSender`](/api-reference/client/react/hooks#useuieventsender),
-[`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), and
-the [`useStandard*Handler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
-hooks.
-
-The provider subscribes to `RTVIEvent.UICommand` and `RTVIEvent.UITask` on the underlying Pipecat client (the `ui-command` and `ui-task` envelopes). On unmount (or when the underlying Pipecat client changes), the subscription is torn down via the detach function returned from `client.attach()`, including under `StrictMode`'s double-invoke in development.
-
-```jsx
-<PipecatClientProvider client={pcClient}>
-  <UIAgentProvider>
-    <App />
-  </UIAgentProvider>
-</PipecatClientProvider>
-```
-
-**Props**
-
-<ParamField path="client" type="PipecatClient">
-  The Pipecat client to bind the UI agent to. When omitted, the provider
-  reads the client from the ambient `PipecatClientProvider` via
-  `usePipecatClient`. When set, the prop takes precedence and the context
-  is ignored.
-
-Pass this explicitly when the host provides the client via a render prop
-(for example, `PipecatAppBase` from `@pipecat-ai/voice-ui-kit`) so the
-UI agent binds to the exact same client instance without relying on
-React-context identity.
-
-</ParamField>
-
 ## UITasksProvider
 
-Drives the in-flight task-group state surfaced by [`useUITasks`](/api-reference/client/react/hooks#useuitasks). Subscribes to the `UIAgentClient`'s task-listener channel (every `ui-task` envelope: `group_started`, `task_update`, `task_completed`, `group_completed`) and reduces them into a `groups` array consumers can render.
+Drives the in-flight task-group state surfaced by [`useUITasks`](/api-reference/client/react/hooks#useuitasks). Subscribes to the ambient `PipecatClient`'s `RTVIEvent.UITask` event stream (every `ui-task` envelope: `group_started`, `task_update`, `task_completed`, `group_completed`) and reduces them into a `groups` array consumers can render.
 
-Mount inside `UIAgentProvider` (the tasks provider depends on the bound `UIAgentClient`). Apps that don't surface in-flight task state to the user can skip this provider; `useUITasks` returns an empty list and a no-op `cancelTask` when no `UITasksProvider` is mounted.
+Mount inside `PipecatClientProvider`. Apps that don't surface in-flight task state to the user can skip this provider; `useUITasks` returns an empty list and a no-op `cancelTask` when no `UITasksProvider` is mounted.
 
 ```jsx
 <PipecatClientProvider client={pcClient}>
-  <UIAgentProvider>
-    <UITasksProvider>
-      <App />
-    </UITasksProvider>
-  </UIAgentProvider>
+  <UITasksProvider>
+    <App />
+  </UITasksProvider>
 </PipecatClientProvider>
 ```
 
diff --git a/api-reference/client/react/hooks.mdx b/api-reference/client/react/hooks.mdx
index e6fc44f3..be0eff98 100644
--- a/api-reference/client/react/hooks.mdx
+++ b/api-reference/client/react/hooks.mdx
@@ -279,36 +279,13 @@ function TextInput() {
 
 ## UI Agent hooks
 
-These hooks require an ambient
-[`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider).
-
-### useUIAgentClient
-
-Returns the [`UIAgentClient`](/api-reference/client/js/ui-agent-client) from
-the ambient `UIAgentProvider`, or `undefined` if the provider is not mounted
-or the Pipecat client has not been initialized yet.
-
-```tsx
-import { useUIAgentClient } from "@pipecat-ai/client-react";
-
-function Diagnostics() {
-  const ui = useUIAgentClient();
-  // Escape hatch: call low-level methods directly.
-  return <button onClick={() => ui?.sendEvent("ping")}>Ping</button>;
-}
-```
-
-**Returns**
-
-<ParamField path="client" type="UIAgentClient | undefined">
-  The active `UIAgentClient`, or `undefined` while the underlying client is not
-  yet initialized.
-</ParamField>
+These hooks use the `PipecatClient` from the ambient
+[`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider).
 
 ### useUIEventSender
 
 Returns a callable that sends a named UI event to the server. The returned
-function is a no-op until a `UIAgentClient` is available.
+function is a no-op until a `PipecatClient` is available.
 
 ```tsx
 import { useUIEventSender } from "@pipecat-ai/client-react";
@@ -321,8 +298,8 @@ function NavLink({ view, label }: { view: string; label: string }) {
 
 **Returns**
 
-<ParamField path="sendEvent" type="<T>(name: string, payload?: T) => void">
-  Function that emits a UI event with the given name and optional payload.
+<ParamField path="sendEvent" type="<T>(event: string, payload?: T) => void">
+  Function that emits a UI event with the given event name and optional payload.
 </ParamField>
 
 ### useUICommandHandler
@@ -359,15 +336,15 @@ function Toaster() {
 ### useA11ySnapshot
 
 Capture a structured accessibility snapshot of the document and stream it
-to the server as a reserved UI event (`__ui_snapshot`). The server-side
+to the server as a first-class `ui-snapshot` RTVI message. The server-side
 [`UIAgent`](/api-reference/pipecat-subagents/ui-agent) stores the latest
 snapshot and renders it into LLM context as `<ui_state>` so the agent can
 reason about what's on screen.
 
-Call once near the root of your app, inside a `UIAgentProvider`. This hook
-is a thin lifecycle wrapper around the framework-agnostic
-[`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot#a11ysnapshotstreamer);
-non-React apps can instantiate the streamer directly.
+Call once near the root of your app, inside a `PipecatClientProvider`. This hook
+is a thin lifecycle wrapper around
+[`PipecatClient.startA11ySnapshotStream`](/api-reference/client/js/client-methods#starta11ysnapshotstream);
+non-React apps should use the managed client method directly.
 
 ```tsx
 import { useA11ySnapshot } from "@pipecat-ai/client-react";
@@ -384,8 +361,8 @@ function App() {
 - Re-emits on DOM mutations, ARIA attribute changes, focus changes,
   scroll-end, window resize, and tab visibility change, coalesced by
   `debounceMs`.
-- No-op until a `UIAgentClient` is available from the ambient
-  `UIAgentProvider`.
+- No-op until a `PipecatClient` is available from the ambient
+  `PipecatClientProvider`.
 
 **Options**
 
@@ -665,7 +642,7 @@ function NavWiring() {
 
 Subscribe to the in-flight task-group state surfaced by the server's [`ui-task`](/client/rtvi-standard#ui-task-) lifecycle envelopes. Returns the live list of task groups plus a `cancelTask` method.
 
-Requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside [`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider). The provider listens to `RTVIEvent.UITask` envelopes from the underlying `UIAgentClient` and reduces them into `groups` state.
+Requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider). The provider listens to `RTVIEvent.UITask` envelopes from the underlying `PipecatClient` and reduces them into `groups` state.
 
 ```tsx
 import { useUITasks } from "@pipecat-ai/client-react";
@@ -699,7 +676,7 @@ function DiscoveryPanel() {
 
 <ParamField path="cancelTask" type="(taskId: string, reason?: string) => void">
   Ask the server to cancel the named task group. Forwards to
-  [`UIAgentClient.cancelTask`](/api-reference/client/js/ui-agent-client#canceltask).
+  [`PipecatClient.cancelUITask`](/api-reference/client/js/client-methods#canceluitask).
   Honored only when the group was registered with `cancellable=True` on the
   server.
 </ParamField>
diff --git a/api-reference/pipecat-subagents/decorators.mdx b/api-reference/pipecat-subagents/decorators.mdx
index 1909c50d..1367b965 100644
--- a/api-reference/pipecat-subagents/decorators.mdx
+++ b/api-reference/pipecat-subagents/decorators.mdx
@@ -164,7 +164,7 @@ class MyUIAgent(UIAgent):
 
 <ParamField path="name" type="str" required>
   The UI event name to match. Must match the `name` argument the client
-  passes to `UIAgentClient.sendEvent(name, payload)`.
+  passes to `PipecatClient.sendUIEvent(event, payload)`.
 </ParamField>
 
 ### Method Signature
diff --git a/api-reference/pipecat-subagents/messages.mdx b/api-reference/pipecat-subagents/messages.mdx
index 408362d8..e19a74b5 100644
--- a/api-reference/pipecat-subagents/messages.mdx
+++ b/api-reference/pipecat-subagents/messages.mdx
@@ -213,7 +213,7 @@ live in `pipecat_subagents.agents.ui.ui_messages`.
 ### BusUIEventMessage
 
 Emitted by [`attach_ui_bridge`](#attach-ui-bridge) when the client dispatches
-an event via `UIAgentClient.sendEvent(name, payload)`.
+an event via `PipecatClient.sendUIEvent(event, payload)`.
 [`UIAgent`](/api-reference/pipecat-subagents/ui-agent) subclasses dispatch
 these to [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event)
 handlers.
@@ -232,8 +232,9 @@ Published by
 The bridge installed by `attach_ui_bridge` turns this into an
 `RTVIUICommandFrame` on the root agent's pipeline; the
 [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer) wraps the frame
-into a `ui-command` envelope on the wire and the client's `UIAgentClient`
-dispatches by name to a registered handler.
+into a `ui-command` envelope on the wire and the client's `PipecatClient`
+emits `RTVIEvent.UICommand` and invokes the `onUICommand` callback, where
+apps can dispatch by command name.
 
 | Field          | Type  | Default | Description                                                     |
 | -------------- | ----- | ------- | --------------------------------------------------------------- | -------------------------------------- |
diff --git a/api-reference/pipecat-subagents/ui-agent.mdx b/api-reference/pipecat-subagents/ui-agent.mdx
index 6f5eeb2e..b55e6177 100644
--- a/api-reference/pipecat-subagents/ui-agent.mdx
+++ b/api-reference/pipecat-subagents/ui-agent.mdx
@@ -7,9 +7,9 @@ description: "LLM agent that dispatches UI events from the client and reasons ab
 
 `UIAgent` extends `LLMContextAgent` (an internal `LLMAgent` subclass that bundles an `LLMContext` plus the user/assistant aggregator pair) with a UI-aware loop:
 
-- **UI events** sent from the client via `UIAgentClient.sendEvent(name, payload)` are dispatched to methods marked with [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event), and (by default) appended to the LLM context as `<ui_event name="...">payload</ui_event>` developer messages.
-- **Accessibility snapshots** captured by the client's a11y walker arrive on a reserved event name and are stored as the latest `<ui_state>`. By default, the snapshot is auto-injected into the LLM context at the start of every task request, so the agent always reasons over the current screen.
-- **UI commands** flow back the other way via `send_command(name, payload)`. The bridge installed by [`attach_ui_bridge`](/api-reference/pipecat-subagents/messages#attach-ui-bridge) translates each command into an `RTVIUICommandFrame` (or `RTVIUITaskFrame` for task-lifecycle traffic) on the root agent's pipeline; the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer) wraps it into a `ui-command` / `ui-task` envelope on the wire and the client's `UIAgentClient` dispatches by name to a registered handler.
+- **UI events** sent from the client via `PipecatClient.sendUIEvent(event, payload)` are dispatched to methods marked with [`@on_ui_event(name)`](/api-reference/pipecat-subagents/decorators#on_ui_event), and (by default) appended to the LLM context as `<ui_event name="...">payload</ui_event>` developer messages.
+- **Accessibility snapshots** captured by the client arrive as first-class `ui-snapshot` RTVI messages, then the bridge republishes them internally under a reserved event name and stores the latest `<ui_state>`. By default, the snapshot is auto-injected into the LLM context at the start of every task request, so the agent always reasons over the current screen.
+- **UI commands** flow back the other way via `send_command(name, payload)`. The bridge installed by [`attach_ui_bridge`](/api-reference/pipecat-subagents/messages#attach-ui-bridge) translates each command into an `RTVIUICommandFrame` (or `RTVIUITaskFrame` for task-lifecycle traffic) on the root agent's pipeline; the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer) wraps it into a `ui-command` / `ui-task` envelope on the wire and the client receives it through `RTVIEvent.UICommand`, `onUICommand`, or React's `useUICommandHandler`.
 
 ```python
 from pipecat_subagents.agents import UIAgent, on_ui_event
@@ -312,8 +312,8 @@ Send a named UI command to the client. Publishes a
 which the bridge installed by `attach_ui_bridge` turns into an
 `RTVIUICommandFrame` on the root agent's pipeline; the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer)
 wraps that into a `ui-command` envelope on the wire. Client-side handlers
-registered via `registerCommandHandler` (or one of the `useStandard*Handler`
-hooks) dispatch on the command name.
+subscribed through `RTVIEvent.UICommand`, `onUICommand`, or one of the React
+`useStandard*Handler` hooks dispatch on the command name.
 
 | Parameter | Type  | Default | Description                                                                        |
 | --------- | ----- | ------- | ---------------------------------------------------------------------------------- |
@@ -379,9 +379,9 @@ async def select_text(
 
 Dispatch a `select_text` UI command for the given snapshot ref. With
 `start_offset` / `end_offset` set, the client's standard handler selects a
-sub-range of the element's text; with both `None` (the default), the entire
-element's contents are selected. Offsets are character offsets over the
-element's concatenated `textContent`.
+sub-range of the target's text; with both `None` (the default), the entire
+target text is selected. Offsets are character offsets over the target's
+text content.
 
 #### click
 
@@ -503,7 +503,7 @@ def render_ui_state(self) -> str
 
 Render the latest accessibility snapshot as a `<ui_state>` block.
 
-Produces Playwright-MCP-style indented text with stable element refs. Each
+Produces Playwright-MCP-style indented text with stable UI node refs. Each
 line is `- role "name" [level=N] [cols=N] [rows=N] [state] [ref=eN]`, with
 children nested one indent deeper. Returns an empty string if no snapshot has
 been received yet.
diff --git a/api-reference/pipecat-subagents/ui-commands.mdx b/api-reference/pipecat-subagents/ui-commands.mdx
index 20bee13b..1578fb7a 100644
--- a/api-reference/pipecat-subagents/ui-commands.mdx
+++ b/api-reference/pipecat-subagents/ui-commands.mdx
@@ -66,47 +66,47 @@ Client-side navigation to a named view. Wire into your router of choice via
 
 ## ScrollTo
 
-Scroll a target element into view.
+Scroll a target UI node into view.
 
 The client resolves the target by `ref` first (a snapshot ref like `"e42"`
-assigned by the a11y walker), then falls back to `target_id`
-(`document.getElementById`). Supply whichever you have; `ref` is the normal
-choice when acting on a node from `<ui_state>`.
+assigned by the client), then falls back to `target_id`, an app-defined stable
+target identifier. Supply whichever you have; `ref` is the normal choice when
+acting on a node from `<ui_state>`.
 
 | Field       | Type | Default | Description |
 | ----------- | ---- | ------- | ----------- | ----------------------------------------------------------------------- |
 | `ref`       | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.                                         |
-| `target_id` | `str | None`   | `None`      | Element id registered on the client.                                    |
+| `target_id` | `str | None`   | `None`      | App-defined stable target id registered on the client.                  |
 | `behavior`  | `str | None`   | `None`      | Optional behavior hint (`"smooth"` or `"instant"`). Clients may ignore. |
 
 ## Highlight
 
-Briefly emphasize a target element (flash, glow, pulse).
+Briefly emphasize a target UI node (flash, glow, pulse).
 
 | Field         | Type | Default | Description |
 | ------------- | ---- | ------- | ----------- | ------------------------------------------------------------ |
 | `ref`         | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.                              |
-| `target_id`   | `str | None`   | `None`      | Element id registered on the client.                         |
+| `target_id`   | `str | None`   | `None`      | App-defined stable target id registered on the client.       |
 | `duration_ms` | `int | None`   | `None`      | Optional duration in ms. Client default applies when `None`. |
 
 ## Focus
 
-Move input focus to a target element.
+Move input focus to a target UI node.
 
 | Field       | Type | Default | Description |
 | ----------- | ---- | ------- | ----------- | ------------------------------------ |
 | `ref`       | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.      |
-| `target_id` | `str | None`   | `None`      | Element id registered on the client. |
+| `target_id` | `str | None`   | `None`      | App-defined stable target id registered on the client. |
 
 ## Click
 
-Click an element on the client. Closes the form-fill loop for non-text
-inputs (checkboxes, radios) and exposes the rest of the action vocabulary
-(submit buttons, links, app-specific clickable nodes). The standard handler
-silently no-ops on `disabled` targets so the agent can't bypass UI
-affordances meant to be user-controlled.
+Activate a target UI node on the client. Closes the form-fill loop for
+non-text inputs (checkboxes, radios) and exposes the rest of the action
+vocabulary (submit buttons, links, app-specific clickable nodes). The web
+standard handler silently no-ops on `disabled` targets so the agent can't
+bypass UI affordances meant to be user-controlled.
 
-For native `<select>`, prefer [`SetInputValue`](#setinputvalue) (clicking
+For HTML `<select>`, prefer [`SetInputValue`](#setinputvalue) (clicking
 options doesn't reliably change the selection); for custom comboboxes
 (ARIA listbox + popup), apps wire their own command matching the library's
 interaction model.
@@ -114,40 +114,39 @@ interaction model.
 | Field       | Type | Default | Description |
 | ----------- | ---- | ------- | ----------- | ------------------------------------------------------------------------------------------------ |
 | `ref`       | `str | None`   | `None`      | Snapshot ref from `<ui_state>`.                                                                  |
-| `target_id` | `str | None`   | `None`      | Element id registered on the client. Used as a fallback when `ref` is not set or has gone stale. |
+| `target_id` | `str | None`   | `None`      | App-defined stable target id registered on the client. Used as a fallback when `ref` is not set or has gone stale. |
 
 ## SetInputValue
 
-Write a value into a text input or textarea on the client. Use this for
-form-filling: the agent has decided what should go into a field
-(clarifying answer, tax form entry, etc.) and asks the client to populate
-it.
+Write a value into a text input on the client. Use this for form-filling: the
+agent has decided what should go into a field (clarifying answer, tax form
+entry, etc.) and asks the client to populate it.
 
-The standard handler silently no-ops on `disabled`, `readonly`, and
+The web standard handler silently no-ops on `disabled`, `readonly`, and
 `<input type="hidden">` targets so the agent can't write into fields the
 user can't.
 
 | Field       | Type   | Default | Description                                                                         |
 | ----------- | ------ | ------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `value`     | `str`  | `""`    | The text to write.                                                                  |
-| `ref`       | `str   | None`   | `None`                                                                              | Snapshot ref from `<ui_state>`. Typically the ref of an `<input>` or `<textarea>`.               |
-| `target_id` | `str   | None`   | `None`                                                                              | Element id registered on the client. Used as a fallback when `ref` is not set or has gone stale. |
+| `ref`       | `str   | None`   | `None`                                                                              | Snapshot ref from `<ui_state>`. Typically the ref of an editable text field.                     |
+| `target_id` | `str   | None`   | `None`                                                                              | App-defined stable target id registered on the client. Used as a fallback when `ref` is not set or has gone stale. |
 | `replace`   | `bool` | `True`  | When `True` (the default), overwrite the current value. When `False`, append to it. |
 
 ## SelectText
 
-Select text on the page so the user can see what the agent means. Mirror
+Select text in the client UI so the user can see what the agent means. Mirror
 of the `selection` field surfaced in the snapshot. Use this to point the
-user's attention at a specific paragraph or range after the agent has
-decided what it's referring to.
+user's attention at a specific text node or range after the agent has decided
+what it's referring to.
 
-With `start_offset` and `end_offset` omitted, the entire target's text
-content is selected (`Range.selectNodeContents` for document elements;
-`el.select()` for `<input>` / `<textarea>`).
+With `start_offset` and `end_offset` omitted, the entire target's text content
+is selected. Web clients implement this with DOM selection APIs; native clients
+can map it to their platform text-selection primitives.
 
 | Field          | Type | Default | Description |
 | -------------- | ---- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ref`          | `str | None`   | `None`      | Snapshot ref from `<ui_state>`. Typically the ref of a paragraph or input element.                                                                                                   |
-| `target_id`    | `str | None`   | `None`      | Element id registered on the client. Used as a fallback when `ref` is not set or has gone stale.                                                                                     |
-| `start_offset` | `int | None`   | `None`      | Character offset within the target's text where the selection should start. For inputs/textareas this is the value offset; for documents the concatenation of descendant text nodes. |
+| `ref`          | `str | None`   | `None`      | Snapshot ref from `<ui_state>`. Typically the ref of text content or an editable text field.                                                                                         |
+| `target_id`    | `str | None`   | `None`      | App-defined stable target id registered on the client. Used as a fallback when `ref` is not set or has gone stale.                                                                   |
+| `start_offset` | `int | None`   | `None`      | Character offset within the target's text where the selection should start.                                                                                                          |
 | `end_offset`   | `int | None`   | `None`      | End character offset, exclusive. Same coordinate system as `start_offset`.                                                                                                           |
diff --git a/api-reference/server/frames/system-frames.mdx b/api-reference/server/frames/system-frames.mdx
index 8c0d91b7..547d989a 100644
--- a/api-reference/server/frames/system-frames.mdx
+++ b/api-reference/server/frames/system-frames.mdx
@@ -430,9 +430,9 @@ Pipeline frames for the [UI Agent Protocol](/client/rtvi-standard#ui-agent-proto
 
 A UI command bound for the client. Wrapped into a `UICommandMessage` envelope on the wire.
 
-<ParamField path="command_name" type="str" default='""'>
+<ParamField path="command" type="str" default='""'>
   App-defined command name (e.g. `"toast"`, `"navigate"`, `"scroll_to"`, or any
-  app-specific name). Maps to the `data.name` field on the wire.
+  app-specific name). Maps to the `data.command` field on the wire.
 </ParamField>
 
 <ParamField path="payload" type="Any" default="None">
@@ -461,8 +461,8 @@ An inbound `ui-event` from the client. Pushed downstream by the `RTVIProcessor`
   The RTVI message id, as set by the client.
 </ParamField>
 
-<ParamField path="event_name" type="str" default='""'>
-  App-defined event name (the wire `data.name` field).
+<ParamField path="event" type="str" default='""'>
+  App-defined event name (the wire `data.event` field).
 </ParamField>
 
 <ParamField path="payload" type="Any" default="None">
@@ -471,14 +471,15 @@ An inbound `ui-event` from the client. Pushed downstream by the `RTVIProcessor`
 
 ### RTVIUISnapshotFrame
 
-An inbound accessibility snapshot from the client. Pushed downstream alongside firing `on_ui_message`. Carries the serialized accessibility tree the client took of its DOM.
+An inbound accessibility snapshot from the client. Pushed downstream alongside firing `on_ui_message`. Carries the serialized platform accessibility tree captured by the client.
 
 <ParamField path="msg_id" type="str" default='""'>
   The RTVI message id, as set by the client.
 </ParamField>
 
-<ParamField path="tree" type="Any" default="None">
-  The serialized accessibility tree.
+<ParamField path="tree" type="A11ySnapshot" default="None">
+  The serialized accessibility tree, matching the client-side
+  [`A11ySnapshot`](/api-reference/client/js/a11y-snapshot#a11ysnapshot) shape.
 </ParamField>
 
 ### RTVIUICancelTaskFrame
diff --git a/api-reference/server/rtvi/rtvi-processor.mdx b/api-reference/server/rtvi/rtvi-processor.mdx
index 73c132d8..c388b78f 100644
--- a/api-reference/server/rtvi/rtvi-processor.mdx
+++ b/api-reference/server/rtvi/rtvi-processor.mdx
@@ -271,7 +271,7 @@ from pipecat.processors.frameworks.rtvi.models import (
 @rtvi.event_handler("on_ui_message")
 async def on_ui_message(rtvi, message):
     if isinstance(message, UIEventMessage):
-        # message.data.name, message.data.payload
+        # message.data.event, message.data.payload
         ...
     elif isinstance(message, UISnapshotMessage):
         # message.data.tree
@@ -293,7 +293,7 @@ from pipecat.processors.frameworks.rtvi.models import Toast
 
 await self.push_frame(
     RTVIUICommandFrame(
-        command_name="toast",
+        command="toast",
         payload=Toast(title="Saved").model_dump(),
     )
 )
diff --git a/client/rtvi-standard.mdx b/client/rtvi-standard.mdx
index cdffc1d7..bd1f622f 100644
--- a/client/rtvi-standard.mdx
+++ b/client/rtvi-standard.mdx
@@ -310,7 +310,7 @@ The UI Agent Protocol lets server-side AI agents observe and drive a client GUI
 | Type             | Direction          | Purpose                                                                                                |
 | ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
 | `ui-event`       | 🏄 client → server | Named event with payload (e.g. button click, navigation intent)                                        |
-| `ui-snapshot`    | 🏄 client → server | Accessibility tree of the page; grounds agent reasoning in current screen state                        |
+| `ui-snapshot`    | 🏄 client → server | Platform accessibility tree; grounds agent reasoning in current UI state                               |
 | `ui-cancel-task` | 🏄 client → server | Cancel an in-flight user-facing task group                                                             |
 | `ui-command`     | 🤖 server → client | Named command with payload (toast, scroll, highlight, click, set input value, ...)                     |
 | `ui-task`        | 🤖 server → client | Task lifecycle envelope; one of `group_started` / `task_update` / `task_completed` / `group_completed` |
@@ -323,9 +323,9 @@ A named event from the client carrying an app-defined payload. Unlike `client-me
 
 - **type**: `'ui-event'`
 - **data**:
-  - **name**: `string`
+  - **event**: `string`
 
-    App-defined event name (e.g. `"nav_click"`, `"play_track"`, `"set_tab"`). Apps may pick any name; reserved names are prefixed with double underscore (e.g. `__ui_snapshot`).
+    App-defined event name (e.g. `"nav_click"`, `"play_track"`, `"set_tab"`). Apps may pick any name.
 
   - **payload**: `unknown` (optional)
 
@@ -333,13 +333,13 @@ A named event from the client carrying an app-defined payload. Unlike `client-me
 
 #### ui-snapshot 🏄
 
-The current accessibility tree of the page, captured by the client's a11y walker on DOM mutations, focus changes, scroll-end, resize, and tab visibility. The server stores the latest snapshot and renders it as `<ui_state>` into the LLM context so the agent reasons over the current screen.
+The current accessibility tree for the client UI, captured from the platform's accessibility or semantic UI model. Web clients can produce this from the DOM; native mobile clients can produce the same shape from iOS or Android accessibility metadata. The server stores the latest snapshot and renders it as `<ui_state>` into the LLM context so the agent reasons over the current UI state.
 
 - **type**: `'ui-snapshot'`
 - **data**:
-  - **tree**: `unknown`
+  - **tree**: [`A11ySnapshot`](/api-reference/client/js/a11y-snapshot#a11ysnapshot)
 
-    The serialized accessibility tree. Opaque on the server side; the client owns the shape. See [`A11ySnapshot`](/api-reference/client/js/a11y-snapshot) for the canonical shape produced by `@pipecat-ai/client-js`'s `A11ySnapshotStreamer`.
+    The serialized platform accessibility tree. The server-side model mirrors the shared snapshot shape and allows extra fields for platform-specific metadata and forward compatibility. The web SDK's managed stream (`PipecatClient.startA11ySnapshotStream` or React's `useA11ySnapshot`) produces this shape; `A11ySnapshotStreamer` is available as a low-level helper.
 
 #### ui-cancel-task 🏄
 
@@ -357,11 +357,11 @@ A request to cancel an in-flight user-facing task group. The server-side framewo
 
 #### ui-command 🤖
 
-A named UI command directing the client to take an action. Client-side dispatchers route on `data.name` to a registered handler (see [`UIAgentClient.registerCommandHandler`](/api-reference/client/js/ui-agent-client) or the `useUICommandHandler` React hook).
+A named UI command directing the client to take an action. Client apps can subscribe to `RTVIEvent.UICommand`, use the `onUICommand` constructor callback, or use the `useUICommandHandler` React hook to filter by `data.command`.
 
 - **type**: `'ui-command'`
 - **data**:
-  - **name**: `string`
+  - **command**: `string`
 
     App-defined command name. Standard names with default React handlers: `toast`, `navigate`, `scroll_to`, `highlight`, `focus`, `click`, `set_input_value`, `select_text`. Apps may publish their own command names freely.
 
@@ -406,7 +406,7 @@ A task lifecycle envelope for a user-facing task group dispatched by the server.
 
 #### Standard command payloads
 
-The `ui-command` message carries a free-form `payload`, but eight standard payload shapes ship with the protocol and are recognized by the default React handlers in `@pipecat-ai/client-react`. Apps can use them as-is, override the client handler to customize rendering, or ignore them and define their own command names.
+The `ui-command` message carries a free-form `payload`, but eight standard payload shapes ship with the protocol. Apps can use them as-is, override the client handler to customize behavior, or ignore them and define their own command names.
 
 | Command           | Payload shape                                                |
 | ----------------- | ------------------------------------------------------------ |
@@ -419,7 +419,7 @@ The `ui-command` message carries a free-form `payload`, but eight standard paylo
 | `set_input_value` | `{value, ref?, target_id?, replace?}`                        |
 | `select_text`     | `{ref?, target_id?, start_offset?, end_offset?}`             |
 
-`ref` is a snapshot ref like `"e42"` assigned by the a11y walker; client handlers resolve `ref` first, then fall back to `target_id` (a `document.getElementById` lookup). Pydantic models for these shapes ship in `pipecat.processors.frameworks.rtvi.models` (`Toast`, `Navigate`, `ScrollTo`, `Highlight`, `Focus`, `Click`, `SetInputValue`, `SelectText`); server-side helpers like `UIAgent.send_command` accept them directly and `model_dump` to the wire shape.
+`ref` is an opaque snapshot reference like `"e42"` assigned by the client and emitted in the latest `ui-snapshot`. Client handlers should resolve `ref` first, then fall back to `target_id`, an optional app-defined stable target identifier outside the snapshot system. Web clients commonly map `target_id` to a DOM id; native clients might map it to an accessibility identifier, view id, or app-specific component id. Pydantic models for these shapes ship in `pipecat.processors.frameworks.rtvi.models` (`Toast`, `Navigate`, `ScrollTo`, `Highlight`, `Focus`, `Click`, `SetInputValue`, `SelectText`); server-side helpers like `UIAgent.send_command` accept them directly and `model_dump` to the wire shape.
 
 ### Advanced LLM Interactions
 
diff --git a/subagents/learn/ui-agent.mdx b/subagents/learn/ui-agent.mdx
index 0d77e47a..c706f949 100644
--- a/subagents/learn/ui-agent.mdx
+++ b/subagents/learn/ui-agent.mdx
@@ -18,7 +18,7 @@ Every voice-enabled GUI app reinvents the same four pieces:
 
 Hand-written prose helpers gave the agent _some_ sense of the screen, enough that "describe this page" worked on a good day. The picture broke easily: server-only state injection missed client-side changes, prose shapes were tightly coupled to the system prompt, and there was no way for the agent to issue a command targeting an element it had just described.
 
-The protocol turns those four patterns into one wire format and adds the missing piece: a **live accessibility snapshot** the agent can actually reason about. The snapshot streams from the client on DOM mutations, focus changes, scroll-end, resize, and tab visibility. The server overwrites a single `_latest_snapshot` slot; the UI agent auto-injects it as `<ui_state>` at the start of every task. Refs (`"e42"`, `"e7"`) are stable across snapshots while a DOM node is mounted, so the LLM can cross-reference between turns ("the button I mentioned earlier") and the agent can point at elements ("flash this one") using the same identifiers it just observed.
+The protocol turns those four patterns into one wire format and adds the missing piece: a **live accessibility snapshot** the agent can actually reason about. The snapshot streams from the client as the UI changes. The server overwrites a single `_latest_snapshot` slot; the UI agent auto-injects it as `<ui_state>` at the start of every task. Refs (`"e42"`, `"e7"`) are stable across snapshots while the underlying UI node exists, so the LLM can cross-reference between turns ("the button I mentioned earlier") and the agent can point at UI nodes ("flash this one") using the same identifiers it just observed.
 
 ### The bigger picture
 
@@ -68,16 +68,16 @@ The split keeps each agent's prompt focused: the voice agent's system prompt is
 
 Four loops run concurrently. Knowing what each one writes is the key to the whole pattern.
 
-| Loop     | Direction       | What it writes                                                              | Triggers an LLM call?           |
-| -------- | --------------- | --------------------------------------------------------------------------- | ------------------------------- |
-| Snapshot | client → server | Latest a11y tree in `_latest_snapshot`                                      | No                              |
-| Event    | client → server | `<ui_event>` developer message in LLM context, plus `@on_ui_event` dispatch | No                              |
-| Command  | server → client | DOM change (scroll, navigate, highlight, click, fill, select, toast, …)     | Yes (response to a task)        |
-| Task     | server → client | `ui-task` lifecycle envelope; client renders an in-flight panel             | Triggered by long-running tools |
+| Loop     | Direction       | What it writes                                                                | Triggers an LLM call?           |
+| -------- | --------------- | ----------------------------------------------------------------------------- | ------------------------------- |
+| Snapshot | client → server | Latest a11y tree in `_latest_snapshot`                                        | No                              |
+| Event    | client → server | `<ui_event>` developer message in LLM context, plus `@on_ui_event` dispatch   | No                              |
+| Command  | server → client | Client UI change (scroll, navigate, highlight, click, fill, select, toast, …) | Yes (response to a task)        |
+| Task     | server → client | `ui-task` lifecycle envelope; client renders an in-flight panel               | Triggered by long-running tools |
 
-**The snapshot loop is observation.** A client-side walker emits an accessibility tree on DOM mutations and other settle-points. The server overwrites a single slot — `_latest_snapshot` internally — and does nothing else. No inference. No LLM context change.
+**The snapshot loop is observation.** A client-side snapshotter emits an accessibility tree when the UI changes or settles. The server overwrites a single slot — `_latest_snapshot` internally — and does nothing else. No inference. No LLM context change.
 
-**The event loop is intent.** Curated by the app, not fired automatically. Most user input (scrolls, hovers, focus changes) already shows up in the snapshot loop, so the SDK doesn't try to mirror every DOM event onto the bus. The app picks which interactions count as _intent_ worth telling the agent about and calls `UIAgentClient.sendEvent(name, payload)` for those. When an event arrives, the server appends a `<ui_event>` to the LLM's context and dispatches to any matching `@on_ui_event` handler. Still no LLM call: the click sits in history, ready for the next time the user speaks.
+**The event loop is intent.** Curated by the app, not fired automatically. Most user input (scrolls, hovers, focus changes) already shows up in the snapshot loop, so the SDK doesn't try to mirror every DOM event onto the bus. The app picks which interactions count as _intent_ worth telling the agent about and calls `PipecatClient.sendUIEvent(event, payload)` for those. When an event arrives, the server appends a `<ui_event>` to the LLM's context and dispatches to any matching `@on_ui_event` handler. Still no LLM call: the click sits in history, ready for the next time the user speaks.
 
 **The command loop is action.** When the UI agent's LLM calls an action tool, the tool publishes a `BusUICommandMessage` on the bus. The bridge translates it into an `RTVIUICommandFrame` that the client routes to the matching command handler.
 
@@ -306,7 +306,7 @@ function DiscoveryPanel() {
 }
 ```
 
-`useUITasks` requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside the [`UIAgentProvider`](/api-reference/client/react/components#uiagentprovider).
+`useUITasks` requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside the [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider).
 
 When the user clicks Cancel, `cancelTask` sends a `ui-cancel-task` message; the SDK on the server side cancels the matching group (subject to `cancellable=True` having been set when the group was dispatched).
 
@@ -338,7 +338,7 @@ Once it fits, three shapes. From least to most infrastructure:
 
 #### Single LLM, snapshot-aware (no subagents)
 
-Drop [`A11ySnapshotStreamer`](/api-reference/client/js/a11y-snapshot) into your client, render the snapshot into a developer message in your Pipecat pipeline, give your LLM tools that emit the typed RTVI frames ([`RTVIUICommandFrame`](/api-reference/server/frames/system-frames#rtviuicommandframe), [`RTVIUITaskFrame`](/api-reference/server/frames/system-frames#rtviuitaskframe)). Less code than wiring up a bus + bridge.
+Start the managed client snapshot stream with [`PipecatClient.startA11ySnapshotStream`](/api-reference/client/js/client-methods#starta11ysnapshotstream) or [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), render the snapshot into a developer message in your Pipecat pipeline, give your LLM tools that emit the typed RTVI frames ([`RTVIUICommandFrame`](/api-reference/server/frames/system-frames#rtviuicommandframe), [`RTVIUITaskFrame`](/api-reference/server/frames/system-frames#rtviuitaskframe)). Less code than wiring up a bus + bridge.
 
 Use this when you have a single LLM doing both conversation and UI work, no multi-agent fan-out. The wire format itself ([RTVI v1.3](/client/rtvi-standard#ui-agent-protocol)) is canonical in Pipecat; subagents builds the agent abstraction on top.
 
@@ -386,5 +386,5 @@ Read it when "show me code" beats "tell me about it."
 - [`@on_ui_event`](/api-reference/pipecat-subagents/decorators#on_ui_event) — decorator for client-event handlers (no LLM call).
 - [RTVI standard — UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) — on-the-wire message types.
 - [RTVI UI frames](/api-reference/server/frames/system-frames#rtvi-ui-frames) — pipeline frames for direct integration.
-- [`UIAgentClient`](/api-reference/client/js/ui-agent-client) — client-side wrapper.
+- [`PipecatClient` UI methods](/api-reference/client/js/client-methods#ui-agent-protocol) — client-side API for UI events, commands, and tasks.
 - [React hooks](/api-reference/client/react/hooks) — `useA11ySnapshot`, `useUICommandHandler`, `useUITasks`, the standard handlers.

From 506cf0d8423fe28d98b0b245e78f170196c810e8 Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Sat, 9 May 2026 07:04:21 -0700
Subject: [PATCH 4/4] Update UI Agent client docs

---
 api-reference/client/js/a11y-snapshot.mdx     | 30 ++++--
 api-reference/client/js/callbacks.mdx         |  8 +-
 api-reference/client/js/client-methods.mdx    | 14 +--
 api-reference/client/js/ui-agent-client.mdx   | 48 ---------
 api-reference/client/react/components.mdx     |  9 +-
 api-reference/client/react/hooks.mdx          | 97 ++++++++++---------
 api-reference/pipecat-subagents/ui-agent.mdx  |  2 +-
 api-reference/server/frames/system-frames.mdx |  2 +
 api-reference/server/rtvi/rtvi-processor.mdx  |  2 +
 client/rtvi-standard.mdx                      | 10 +-
 docs.json                                     |  1 -
 subagents/learn/ui-agent.mdx                  | 11 ++-
 12 files changed, 112 insertions(+), 122 deletions(-)
 delete mode 100644 api-reference/client/js/ui-agent-client.mdx

diff --git a/api-reference/client/js/a11y-snapshot.mdx b/api-reference/client/js/a11y-snapshot.mdx
index 16f2be99..c993699e 100644
--- a/api-reference/client/js/a11y-snapshot.mdx
+++ b/api-reference/client/js/a11y-snapshot.mdx
@@ -20,14 +20,16 @@ shape is intentionally platform-neutral: native clients can produce the same
 import {
   snapshotDocument,
   findElementByRef,
+  findRefForElement,
 } from "@pipecat-ai/client-js";
 ```
 
 Most apps should start streaming through the managed `PipecatClient` API
-or [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot)
+or [`useUISnapshot`](/api-reference/client/react/hooks#useuisnapshot)
 in React. The walker (`snapshotDocument`) is exposed for apps that need a
-one-off snapshot, and `findElementByRef` resolves a server-supplied ref back
-to a live DOM element for command handlers.
+one-off snapshot, `findElementByRef` resolves a server-supplied ref back
+to a live DOM element for command handlers, and `findRefForElement` returns
+the snapshot ref assigned to a DOM element after it has appeared in a snapshot.
 
 <Note>
   Apps can mark a subtree as PII / sensitive by adding `data-a11y-exclude` to
@@ -63,10 +65,10 @@ const pcClient = new PipecatClient({
   /* ... */
 });
 
-pcClient.startA11ySnapshotStream({ debounceMs: 200 });
+pcClient.startUISnapshotStream({ debounceMs: 200 });
 
 // Later
-pcClient.stopA11ySnapshotStream();
+pcClient.stopUISnapshotStream();
 ```
 
 If you need to provide your own transport or batching layer, instantiate the
@@ -84,7 +86,7 @@ streamer.start();
 
 <Note>
   React apps should prefer
-  [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), which
+  [`useUISnapshot`](/api-reference/client/react/hooks#useuisnapshot), which
   starts and stops the managed `PipecatClient` stream.
 </Note>
 
@@ -102,6 +104,7 @@ A snapshot is scheduled (debounced via `debounceMs`) on:
 - **Window resize** (debounced because the viewport rect shifts which nodes
   are `[offscreen]`).
 - **Tab visibility** transition to `visible`.
+- **Text selection changes** (`selectionchange`).
 
 An initial snapshot is scheduled immediately on `start()`.
 
@@ -190,9 +193,19 @@ long as the element stays mounted and survive across snapshots. Command
 handlers use this to act on nodes the server referenced from `<ui_state>`.
 
 The
-[`useStandard*Handler`](/api-reference/client/react/hooks#usestandardscrolltohandler)
+[`useDefault*Handler`](/api-reference/client/react/hooks#usedefaultscrolltohandler)
 hooks call this internally.
 
+## findRefForElement
+
+```typescript
+function findRefForElement(el: Element): string | null;
+```
+
+Return the snapshot ref assigned to a DOM element, if any. Returns `null` for
+elements the walker has not visited yet. This is useful when an app needs to
+associate a user interaction with the nearest snapshot-known node.
+
 ## Types
 
 ### A11ySnapshotEmitter
@@ -280,5 +293,6 @@ The user's current text selection. Lets the agent ground deictic references like
 ## See also
 
 - [`PipecatClient` UI methods](/api-reference/client/js/client-methods#ui-agent-protocol) — the client-side UI Agent Protocol API.
-- [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot) — React hook idiom.
+- [`useUISnapshot`](/api-reference/client/react/hooks#useuisnapshot) — React hook idiom.
+- [UI Agent guide](/subagents/learn/ui-agent) — end-to-end SDK usage with a server-side UI agent.
 - [UI Agent Protocol on the wire](/client/rtvi-standard#ui-snapshot-) — the `ui-snapshot` RTVI message that carries the tree.
diff --git a/api-reference/client/js/callbacks.mdx b/api-reference/client/js/callbacks.mdx
index 7382b5cc..0017dbb4 100644
--- a/api-reference/client/js/callbacks.mdx
+++ b/api-reference/client/js/callbacks.mdx
@@ -118,14 +118,14 @@ pcClient.on(RTVIEvent.BotReady, () => console.log("Bot ready via event"));
 
 ### UI Agent Protocol
 
-<ParamField path="onUICommand" type="data:UICommandEnvelope">
+<ParamField path="onUICommand" type="data:UICommandData">
   Receives a `ui-command` envelope from the server. Switch on `data.command` to
   route app-specific commands, or use
   [`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler)
   in React.
 </ParamField>
 
-<ParamField path="onUITask" type="data:UITaskEnvelope">
+<ParamField path="onUITask" type="data:UITaskData">
   Receives each `ui-task` lifecycle envelope from the server:
   `group_started`, `task_update`, `task_completed`, or `group_completed`.
   React apps can use [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider)
@@ -468,8 +468,8 @@ Here's the complete reference mapping events to their corresponding callbacks:
 | `ServerMessage` | `onServerMessage` | `any`               |
 | `MessageError`  | `onMessageError`  | `RTVIMessage`       |
 | `Error`         | `onError`         | `RTVIMessage`       |
-| `UICommand`     | `onUICommand`     | `UICommandEnvelope` |
-| `UITask`        | `onUITask`        | `UITaskEnvelope`    |
+| `UICommand`     | `onUICommand`     | `UICommandData`     |
+| `UITask`        | `onUITask`        | `UITaskData`        |
 
 ### Media Events
 
diff --git a/api-reference/client/js/client-methods.mdx b/api-reference/client/js/client-methods.mdx
index 51570504..cd467372 100644
--- a/api-reference/client/js/client-methods.mdx
+++ b/api-reference/client/js/client-methods.mdx
@@ -185,6 +185,8 @@ Sends a custom request to the bot and expects a response. This is useful for que
 
 These methods implement the client side of the [UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) directly on `PipecatClient`.
 
+For an end-to-end explanation of how the client SDK fits with a server-side UI agent, see the [UI Agent guide](/subagents/learn/ui-agent).
+
 ### sendUIEvent()
 
 `sendUIEvent<T = unknown>(event: string, payload?: T): void`
@@ -204,14 +206,14 @@ pcClient.sendUIEvent("nav_click", { view: "settings" });
   App-defined payload. Schemaless. Optional.
 </ParamField>
 
-### startA11ySnapshotStream()
+### startUISnapshotStream()
 
-`startA11ySnapshotStream(options?: A11ySnapshotStreamerOptions): void`
+`startUISnapshotStream(options?: A11ySnapshotStreamerOptions): void`
 
 Start a managed accessibility snapshot stream. The client emits `ui-snapshot` messages when the document changes or settles. Calling this again replaces the previous managed stream with the new options.
 
 ```typescript
-pcClient.startA11ySnapshotStream({ debounceMs: 200 });
+pcClient.startUISnapshotStream({ debounceMs: 200 });
 ```
 
 <ParamField path="options" type="A11ySnapshotStreamerOptions">
@@ -219,14 +221,14 @@ pcClient.startA11ySnapshotStream({ debounceMs: 200 });
   [Accessibility Snapshots](/api-reference/client/js/a11y-snapshot).
 </ParamField>
 
-### stopA11ySnapshotStream()
+### stopUISnapshotStream()
 
-`stopA11ySnapshotStream(): void`
+`stopUISnapshotStream(): void`
 
 Stop the managed accessibility snapshot stream, if one is active. `disconnect()` also stops the managed stream.
 
 ```typescript
-pcClient.stopA11ySnapshotStream();
+pcClient.stopUISnapshotStream();
 ```
 
 ### UI command events
diff --git a/api-reference/client/js/ui-agent-client.mdx b/api-reference/client/js/ui-agent-client.mdx
deleted file mode 100644
index f4be1c86..00000000
--- a/api-reference/client/js/ui-agent-client.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: "UI Agent Protocol"
-description: "Client-side PipecatClient methods for the UI Agent Protocol"
----
-
-## Overview
-
-The UI Agent Protocol is exposed directly on `PipecatClient`. There is no separate client wrapper.
-
-```javascript
-import { PipecatClient, RTVIEvent } from "@pipecat-ai/client-js";
-
-const pcClient = new PipecatClient({
-  /* ... */
-});
-
-const onCommand = (data) => {
-  if (data.command === "toast") {
-    showToast(data.payload.title, data.payload.subtitle);
-  }
-};
-
-pcClient.on(RTVIEvent.UICommand, onCommand);
-pcClient.startA11ySnapshotStream({ debounceMs: 200 });
-pcClient.sendUIEvent("nav_click", { view: "settings" });
-
-// Later, on cleanup
-pcClient.off(RTVIEvent.UICommand, onCommand);
-pcClient.stopA11ySnapshotStream();
-```
-
-## Methods
-
-See [`PipecatClient` methods](/api-reference/client/js/client-methods#ui-agent-protocol) for:
-
-- `sendUIEvent(event, payload?)`
-- `startA11ySnapshotStream(options?)`
-- `stopA11ySnapshotStream()`
-- `RTVIEvent.UICommand` / `onUICommand`
-- `RTVIEvent.UITask` / `onUITask`
-- `cancelUITask(taskId, reason?)`
-
-## See also
-
-- [`PipecatClient` UI methods](/api-reference/client/js/client-methods#ui-agent-protocol) — the client-side API.
-- [`Accessibility Snapshots`](/api-reference/client/js/a11y-snapshot) — snapshot shape, managed streaming, and low-level helpers.
-- [`useUICommandHandler`](/api-reference/client/react/hooks#useuicommandhandler) — React command handler hook.
-- [UI Agent Protocol on the wire](/client/rtvi-standard#ui-agent-protocol) — the underlying RTVI message types.
diff --git a/api-reference/client/react/components.mdx b/api-reference/client/react/components.mdx
index 194839f5..1c5cffc7 100644
--- a/api-reference/client/react/components.mdx
+++ b/api-reference/client/react/components.mdx
@@ -29,13 +29,18 @@ Mount inside `PipecatClientProvider`. Apps that don't surface in-flight task sta
 
 ```jsx
 <PipecatClientProvider client={pcClient}>
-  <UITasksProvider>
+  <UITasksProvider maxGroups={20}>
     <App />
   </UITasksProvider>
 </PipecatClientProvider>
 ```
 
-The provider takes no props.
+**Props**
+
+<ParamField path="maxGroups" type="number">
+  Maximum number of groups to retain. When exceeded, oldest non-running groups
+  are dropped first; running groups are never dropped. Omitted means unbounded.
+</ParamField>
 
 ## PipecatClientAudio
 
diff --git a/api-reference/client/react/hooks.mdx b/api-reference/client/react/hooks.mdx
index be0eff98..8351dae5 100644
--- a/api-reference/client/react/hooks.mdx
+++ b/api-reference/client/react/hooks.mdx
@@ -281,6 +281,8 @@ function TextInput() {
 
 These hooks use the `PipecatClient` from the ambient
 [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider).
+For the full client/server pattern, including snapshots, commands, and task
+lifecycle, see the [UI Agent guide](/subagents/learn/ui-agent).
 
 ### useUIEventSender
 
@@ -333,7 +335,7 @@ function Toaster() {
   Callback invoked with the command payload.
 </ParamField>
 
-### useA11ySnapshot
+### useUISnapshot
 
 Capture a structured accessibility snapshot of the document and stream it
 to the server as a first-class `ui-snapshot` RTVI message. The server-side
@@ -343,14 +345,14 @@ reason about what's on screen.
 
 Call once near the root of your app, inside a `PipecatClientProvider`. This hook
 is a thin lifecycle wrapper around
-[`PipecatClient.startA11ySnapshotStream`](/api-reference/client/js/client-methods#starta11ysnapshotstream);
+[`PipecatClient.startUISnapshotStream`](/api-reference/client/js/client-methods#startuisnapshotstream);
 non-React apps should use the managed client method directly.
 
 ```tsx
-import { useA11ySnapshot } from "@pipecat-ai/client-react";
+import { useUISnapshot } from "@pipecat-ai/client-react";
 
 function App() {
-  useA11ySnapshot();
+  useUISnapshot();
   return <Routes>...</Routes>;
 }
 ```
@@ -359,8 +361,8 @@ function App() {
 
 - Emits an initial snapshot shortly after mount.
 - Re-emits on DOM mutations, ARIA attribute changes, focus changes,
-  scroll-end, window resize, and tab visibility change, coalesced by
-  `debounceMs`.
+  scroll-end, window resize, tab visibility change, and text selection changes,
+  coalesced by `debounceMs`.
 - No-op until a `PipecatClient` is available from the ambient
   `PipecatClientProvider`.
 
@@ -385,17 +387,17 @@ function App() {
   rough token estimate, raw tree).
 </ParamField>
 
-### useStandardScrollToHandler
+### useDefaultScrollToHandler
 
 Install the default `scroll_to` handler: `scrollIntoView` on the resolved
 target. Resolves by snapshot `ref` first, then falls back to
 `document.getElementById(target_id)`.
 
 ```tsx
-import { useStandardScrollToHandler } from "@pipecat-ai/client-react";
+import { useDefaultScrollToHandler } from "@pipecat-ai/client-react";
 
 function App() {
-  useStandardScrollToHandler({
+  useDefaultScrollToHandler({
     block: "center",
     container: () => document.querySelector(".main"),
   });
@@ -443,13 +445,13 @@ function App() {
   Only applied when `container` is set.
 </ParamField>
 
-### useStandardFocusHandler
+### useDefaultFocusHandler
 
 Install the default `focus` handler: `.focus()` on the resolved target.
 
 ```tsx
-import { useStandardFocusHandler } from "@pipecat-ai/client-react";
-useStandardFocusHandler({ preventScroll: true });
+import { useDefaultFocusHandler } from "@pipecat-ai/client-react";
+useDefaultFocusHandler({ preventScroll: true });
 ```
 
 **Options**
@@ -460,7 +462,7 @@ useStandardFocusHandler({ preventScroll: true });
   explicit `scroll_to`.
 </ParamField>
 
-### useStandardHighlightHandler
+### useDefaultHighlightHandler
 
 Install the default `highlight` handler: toggle a CSS class on the resolved
 target for `duration_ms`. Apps style the class themselves, e.g.
@@ -473,9 +475,9 @@ target for `duration_ms`. Apps style the class themselves, e.g.
 ```
 
 ```tsx
-import { useStandardHighlightHandler } from "@pipecat-ai/client-react";
+import { useDefaultHighlightHandler } from "@pipecat-ai/client-react";
 
-useStandardHighlightHandler({
+useDefaultHighlightHandler({
   className: "ui-highlight",
   defaultDurationMs: 2000,
   scrollIntoViewFirst: true,
@@ -497,14 +499,14 @@ useStandardHighlightHandler({
   the flash is visible to the user even if the target is currently offscreen.
 </ParamField>
 
-### useStandardSelectTextHandler
+### useDefaultSelectTextHandler
 
 Enable the default `select_text` handler. Resolves the target by ref / target_id and applies the page text selection (`Range.selectNodeContents` for document elements, `el.select()` for `<input>` / `<textarea>`). With `start_offset` / `end_offset` set, walks descendant text nodes to apply a sub-range selection.
 
 ```tsx
-import { useStandardSelectTextHandler } from "@pipecat-ai/client-react";
+import { useDefaultSelectTextHandler } from "@pipecat-ai/client-react";
 
-useStandardSelectTextHandler({ scrollIntoViewFirst: true });
+useDefaultSelectTextHandler({ scrollIntoViewFirst: true });
 ```
 
 **Options**
@@ -518,16 +520,16 @@ useStandardSelectTextHandler({ scrollIntoViewFirst: true });
   `scrollIntoView` block position when scrolling first.
 </ParamField>
 
-### useStandardSetInputValueHandler
+### useDefaultSetInputValueHandler
 
 Enable the default `set_input_value` handler. Resolves the target by ref / target_id; refuses on `disabled`, `readonly`, and `<input type="hidden">` (silent no-op so the agent can't bypass UI affordances the user is meant to control), then assigns `el.value` and dispatches single-shot `input` and `change` events so React-controlled inputs and vanilla `onChange` listeners pick up the new value naturally.
 
 With `replace: false` on the payload, the new text is appended to the current value; the default replaces. The flag is ignored for native `<select>` since a select either has the value or doesn't. Native `<select>` is supported alongside text inputs and textareas (the handler sets `el.value` and dispatches `change`).
 
 ```tsx
-import { useStandardSetInputValueHandler } from "@pipecat-ai/client-react";
+import { useDefaultSetInputValueHandler } from "@pipecat-ai/client-react";
 
-useStandardSetInputValueHandler({ focusFirst: true });
+useDefaultSetInputValueHandler({ focusFirst: true });
 ```
 
 **Options**
@@ -538,28 +540,28 @@ useStandardSetInputValueHandler({ focusFirst: true });
   to avoid stealing keyboard focus mid-conversation.
 </ParamField>
 
-### useStandardClickHandler
+### useDefaultClickHandler
 
 Enable the default `click` handler. Resolves the target by ref / target_id and calls `el.click()`. Silently no-ops on `disabled` and `aria-disabled="true"` targets so the agent can't bypass UI affordances meant to be user-controlled.
 
 ```tsx
-import { useStandardClickHandler } from "@pipecat-ai/client-react";
+import { useDefaultClickHandler } from "@pipecat-ai/client-react";
 
-useStandardClickHandler();
+useDefaultClickHandler();
 ```
 
 Takes no options.
 
-### useStandardCommandHandlers
+### useDefaultUICommandHandlers
 
 Install all DOM-based default handlers (`scroll_to`, `focus`, `highlight`,
 `select_text`, `set_input_value`, `click`) at once. Pass per-handler option
 objects to customize.
 
 ```tsx
-import { useStandardCommandHandlers } from "@pipecat-ai/client-react";
+import { useDefaultUICommandHandlers } from "@pipecat-ai/client-react";
 
-useStandardCommandHandlers({
+useDefaultUICommandHandlers({
   scrollTo: { block: "center" },
   highlight: { defaultDurationMs: 2000 },
   setInputValue: { focusFirst: true },
@@ -568,27 +570,27 @@ useStandardCommandHandlers({
 
 **Options**
 
-<ParamField path="scrollTo" type="StandardScrollToOptions">
-  Forwarded to `useStandardScrollToHandler`.
+<ParamField path="scrollTo" type="DefaultScrollToOptions">
+  Forwarded to `useDefaultScrollToHandler`.
 </ParamField>
 
-<ParamField path="focus" type="StandardFocusOptions">
-  Forwarded to `useStandardFocusHandler`.
+<ParamField path="focus" type="DefaultFocusOptions">
+  Forwarded to `useDefaultFocusHandler`.
 </ParamField>
 
-<ParamField path="highlight" type="StandardHighlightOptions">
-  Forwarded to `useStandardHighlightHandler`.
+<ParamField path="highlight" type="DefaultHighlightOptions">
+  Forwarded to `useDefaultHighlightHandler`.
 </ParamField>
 
-<ParamField path="selectText" type="StandardSelectTextOptions">
-  Forwarded to `useStandardSelectTextHandler`.
+<ParamField path="selectText" type="DefaultSelectTextOptions">
+  Forwarded to `useDefaultSelectTextHandler`.
 </ParamField>
 
-<ParamField path="setInputValue" type="StandardSetInputValueOptions">
-  Forwarded to `useStandardSetInputValueHandler`.
+<ParamField path="setInputValue" type="DefaultSetInputValueOptions">
+  Forwarded to `useDefaultSetInputValueHandler`.
 </ParamField>
 
-`useStandardClickHandler` takes no options and is always installed.
+`useDefaultClickHandler` takes no options and is always installed.
 
 ### useToastHandler
 
@@ -640,9 +642,9 @@ function NavWiring() {
 
 ### useUITasks
 
-Subscribe to the in-flight task-group state surfaced by the server's [`ui-task`](/client/rtvi-standard#ui-task-) lifecycle envelopes. Returns the live list of task groups plus a `cancelTask` method.
+Subscribe to the in-flight task-group state surfaced by the server's [`ui-task`](/client/rtvi-standard#ui-task-) lifecycle envelopes. Returns the live list of task groups plus methods to cancel and prune task groups.
 
-Requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider). The provider listens to `RTVIEvent.UITask` envelopes from the underlying `PipecatClient` and reduces them into `groups` state.
+For live task state, mount a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) inside [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider). The provider listens to `RTVIEvent.UITask` envelopes from the underlying `PipecatClient` and reduces them into `groups` state.
 
 ```tsx
 import { useUITasks } from "@pipecat-ai/client-react";
@@ -669,9 +671,8 @@ function DiscoveryPanel() {
 <ParamField path="groups" type="TaskGroup[]">
   Live array of in-flight and recently completed task groups, in arrival order.
   Each group has `taskId`, `label`, `status` (`"running"` / `"completed"` /
-  `"cancelled"` / `"failed"` / `"error"`), `cancellable`, per-worker entries
-  with status and response, and aggregate `completedCount` / `totalCount`
-  counters.
+  `"cancelled"` / `"error"`), `cancellable`, timestamps, and per-worker
+  entries with status, progress updates, and response.
 </ParamField>
 
 <ParamField path="cancelTask" type="(taskId: string, reason?: string) => void">
@@ -681,4 +682,12 @@ function DiscoveryPanel() {
   server.
 </ParamField>
 
-When no `UITasksProvider` is mounted, `useUITasks` returns an empty `groups` list and a no-op `cancelTask` rather than throwing.
+<ParamField path="dismissTask" type="(taskId: string) => void">
+  Remove a non-running group from local UI state. Running groups are kept.
+</ParamField>
+
+<ParamField path="clearCompleted" type="() => void">
+  Remove every non-running group from local UI state.
+</ParamField>
+
+When no `UITasksProvider` is mounted, `useUITasks` returns an empty `groups` list and no-op methods rather than throwing.
diff --git a/api-reference/pipecat-subagents/ui-agent.mdx b/api-reference/pipecat-subagents/ui-agent.mdx
index b55e6177..5b9f6e1e 100644
--- a/api-reference/pipecat-subagents/ui-agent.mdx
+++ b/api-reference/pipecat-subagents/ui-agent.mdx
@@ -313,7 +313,7 @@ which the bridge installed by `attach_ui_bridge` turns into an
 `RTVIUICommandFrame` on the root agent's pipeline; the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer)
 wraps that into a `ui-command` envelope on the wire. Client-side handlers
 subscribed through `RTVIEvent.UICommand`, `onUICommand`, or one of the React
-`useStandard*Handler` hooks dispatch on the command name.
+`useDefault*Handler` hooks dispatch on the command name.
 
 | Parameter | Type  | Default | Description                                                                        |
 | --------- | ----- | ------- | ---------------------------------------------------------------------------------- |
diff --git a/api-reference/server/frames/system-frames.mdx b/api-reference/server/frames/system-frames.mdx
index 547d989a..6a0a3937 100644
--- a/api-reference/server/frames/system-frames.mdx
+++ b/api-reference/server/frames/system-frames.mdx
@@ -426,6 +426,8 @@ Responds to an `RTVIClientMessageFrame`. Include the original client message fra
 
 Pipeline frames for the [UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) message types. The outbound frames (`RTVIUICommandFrame`, `RTVIUITaskFrame`) are pushed by application code and wrapped into the matching `ui-command` / `ui-task` envelope by the [`RTVIObserver`](/api-reference/server/rtvi/rtvi-observer). The inbound frames (`RTVIUIEventFrame`, `RTVIUISnapshotFrame`, `RTVIUICancelTaskFrame`) are pushed downstream by the [`RTVIProcessor`](/api-reference/server/rtvi/rtvi-processor#ui-agent-protocol) when the matching client message arrives, alongside firing `on_ui_message`.
 
+Most apps should start with the [UI Agent guide](/subagents/learn/ui-agent); use these frames directly when building a custom integration without the subagents UI bridge.
+
 ### RTVIUICommandFrame
 
 A UI command bound for the client. Wrapped into a `UICommandMessage` envelope on the wire.
diff --git a/api-reference/server/rtvi/rtvi-processor.mdx b/api-reference/server/rtvi/rtvi-processor.mdx
index c388b78f..4ee628ab 100644
--- a/api-reference/server/rtvi/rtvi-processor.mdx
+++ b/api-reference/server/rtvi/rtvi-processor.mdx
@@ -259,6 +259,8 @@ See [Handling Custom Messages from the Server](/client/guides/custom-messaging#h
 
 The processor recognizes five first-class RTVI message types for UI Agent traffic — `ui-event`, `ui-snapshot`, `ui-cancel-task` (inbound from client) and `ui-command`, `ui-task` (outbound to client). The full wire format is documented in the [RTVI standard](/client/rtvi-standard#ui-agent-protocol).
 
+For the recommended higher-level SDK flow, see the [UI Agent guide](/subagents/learn/ui-agent). This page focuses on direct `RTVIProcessor` integrations.
+
 ### Receiving UI messages
 
 Inbound `ui-event`, `ui-snapshot`, and `ui-cancel-task` messages fire the `on_ui_message` event handler with the parsed envelope. The same dispatch also pushes a typed pipeline frame (`RTVIUIEventFrame`, `RTVIUISnapshotFrame`, or `RTVIUICancelTaskFrame`) so processors and observers downstream can react at the pipeline level — pick whichever shape fits your code path.
diff --git a/client/rtvi-standard.mdx b/client/rtvi-standard.mdx
index bd1f622f..8169412a 100644
--- a/client/rtvi-standard.mdx
+++ b/client/rtvi-standard.mdx
@@ -317,6 +317,8 @@ The UI Agent Protocol lets server-side AI agents observe and drive a client GUI
 
 Server-side, each type is a paired `*Data` / `*Message` pydantic model in `pipecat.processors.frameworks.rtvi.models`. Client-side, each type is a member of `RTVIMessageType` (e.g. `RTVIMessageType.UI_EVENT`). The full agent-side abstraction lives in [`pipecat-subagents`](/subagents/learn/ui-agent); single-LLM Pipecat apps can target this wire format directly via the new pipeline frames (`RTVIUICommandFrame`, `RTVIUITaskFrame`).
 
+For a higher-level walkthrough of using this protocol from the web client SDK with a server-side UI agent, see the [UI Agent guide](/subagents/learn/ui-agent).
+
 #### ui-event 🏄
 
 A named event from the client carrying an app-defined payload. Unlike `client-message`, no server response is expected; the server side fans out the event to handlers and (optionally) injects it into the LLM context as a `<ui_event>` developer message.
@@ -339,7 +341,7 @@ The current accessibility tree for the client UI, captured from the platform's a
 - **data**:
   - **tree**: [`A11ySnapshot`](/api-reference/client/js/a11y-snapshot#a11ysnapshot)
 
-    The serialized platform accessibility tree. The server-side model mirrors the shared snapshot shape and allows extra fields for platform-specific metadata and forward compatibility. The web SDK's managed stream (`PipecatClient.startA11ySnapshotStream` or React's `useA11ySnapshot`) produces this shape; `A11ySnapshotStreamer` is available as a low-level helper.
+    The serialized platform accessibility tree. The server-side model mirrors the shared snapshot shape and allows extra fields for platform-specific metadata and forward compatibility. The web SDK's managed stream (`PipecatClient.startUISnapshotStream` or React's `useUISnapshot`) produces this shape; `A11ySnapshotStreamer` is available as a low-level helper.
 
 #### ui-cancel-task 🏄
 
@@ -365,7 +367,7 @@ A named UI command directing the client to take an action. Client apps can subsc
 
     App-defined command name. Standard names with default React handlers: `toast`, `navigate`, `scroll_to`, `highlight`, `focus`, `click`, `set_input_value`, `select_text`. Apps may publish their own command names freely.
 
-  - **payload**: `unknown` (optional)
+  - **payload**: `unknown`
 
     App-defined payload. Standard payload shapes for the standard commands are documented under [Standard command payloads](#standard-command-payloads) below.
 
@@ -379,7 +381,7 @@ A task lifecycle envelope for a user-facing task group dispatched by the server.
   **`group_started`** — group dispatched, worker list known.
   - **kind**: `'group_started'`
   - **task_id**: `string`
-  - **agents**: `string[]` (optional)
+  - **agents**: `string[]`
   - **label**: `string` (optional)
   - **cancellable**: `boolean`
   - **at**: `number` (epoch ms)
@@ -388,7 +390,7 @@ A task lifecycle envelope for a user-facing task group dispatched by the server.
   - **kind**: `'task_update'`
   - **task_id**: `string`
   - **agent_name**: `string`
-  - **data**: `unknown` (optional, worker-defined)
+  - **data**: `unknown` (worker-defined)
   - **at**: `number` (epoch ms)
 
   **`task_completed`** — per-worker terminal.
diff --git a/docs.json b/docs.json
index fc82fa36..f7f67ef4 100644
--- a/docs.json
+++ b/docs.json
@@ -691,7 +691,6 @@
                   {
                     "group": "UI Agent",
                     "pages": [
-                      "api-reference/client/js/ui-agent-client",
                       "api-reference/client/js/a11y-snapshot"
                     ]
                   },
diff --git a/subagents/learn/ui-agent.mdx b/subagents/learn/ui-agent.mdx
index c706f949..68f9c670 100644
--- a/subagents/learn/ui-agent.mdx
+++ b/subagents/learn/ui-agent.mdx
@@ -300,13 +300,16 @@ function DiscoveryPanel() {
           Cancel
         </button>
       )}
-      <progress value={inflight.completedCount} max={inflight.totalCount} />
+      <progress
+        value={inflight.tasks.filter((t) => t.status !== "running").length}
+        max={inflight.tasks.length}
+      />
     </div>
   );
 }
 ```
 
-`useUITasks` requires a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) mounted inside the [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider).
+For live task state, mount a [`UITasksProvider`](/api-reference/client/react/components#uitasksprovider) inside the [`PipecatClientProvider`](/api-reference/client/react/components#pipecatclientprovider). Without the provider, `useUITasks` returns an empty list and no-op methods.
 
 When the user clicks Cancel, `cancelTask` sends a `ui-cancel-task` message; the SDK on the server side cancels the matching group (subject to `cancellable=True` having been set when the group was dispatched).
 
@@ -338,7 +341,7 @@ Once it fits, three shapes. From least to most infrastructure:
 
 #### Single LLM, snapshot-aware (no subagents)
 
-Start the managed client snapshot stream with [`PipecatClient.startA11ySnapshotStream`](/api-reference/client/js/client-methods#starta11ysnapshotstream) or [`useA11ySnapshot`](/api-reference/client/react/hooks#usea11ysnapshot), render the snapshot into a developer message in your Pipecat pipeline, give your LLM tools that emit the typed RTVI frames ([`RTVIUICommandFrame`](/api-reference/server/frames/system-frames#rtviuicommandframe), [`RTVIUITaskFrame`](/api-reference/server/frames/system-frames#rtviuitaskframe)). Less code than wiring up a bus + bridge.
+Start the managed client snapshot stream with [`PipecatClient.startUISnapshotStream`](/api-reference/client/js/client-methods#startuisnapshotstream) or [`useUISnapshot`](/api-reference/client/react/hooks#useuisnapshot), render the snapshot into a developer message in your Pipecat pipeline, give your LLM tools that emit the typed RTVI frames ([`RTVIUICommandFrame`](/api-reference/server/frames/system-frames#rtviuicommandframe), [`RTVIUITaskFrame`](/api-reference/server/frames/system-frames#rtviuitaskframe)). Less code than wiring up a bus + bridge.
 
 Use this when you have a single LLM doing both conversation and UI work, no multi-agent fan-out. The wire format itself ([RTVI v1.3](/client/rtvi-standard#ui-agent-protocol)) is canonical in Pipecat; subagents builds the agent abstraction on top.
 
@@ -387,4 +390,4 @@ Read it when "show me code" beats "tell me about it."
 - [RTVI standard — UI Agent Protocol](/client/rtvi-standard#ui-agent-protocol) — on-the-wire message types.
 - [RTVI UI frames](/api-reference/server/frames/system-frames#rtvi-ui-frames) — pipeline frames for direct integration.
 - [`PipecatClient` UI methods](/api-reference/client/js/client-methods#ui-agent-protocol) — client-side API for UI events, commands, and tasks.
-- [React hooks](/api-reference/client/react/hooks) — `useA11ySnapshot`, `useUICommandHandler`, `useUITasks`, the standard handlers.
+- [React hooks](/api-reference/client/react/hooks) — `useUISnapshot`, `useUICommandHandler`, `useUITasks`, the default handlers.