generative-a11y
GitHubnpm
Integrations

AG-UI accessibility

Add paced screen-reader updates to an AG-UI agent through documented callbacks for responses, tools, and user interactions.

Install the AG-UI adapter

Install @generative-a11y/core, @generative-a11y/dom, and @generative-a11y/ag-ui beside the AG-UI client used by your application. Bind the existing agent after it is ready, and keep ownership of the agent and accessibility runtime in your application.

Subscribe to the public agent API

bindAgent observes an AbstractAgent through subscribe callbacks. It does not invoke actions, subscribe to private observables, or mutate agent state.

typescript
import { bindAgent } from "@generative-a11y/ag-ui";

const binding = bindAgent({
  runtime,
  scopeId: "research-agent",
  agent,
});

// Never disposes the borrowed agent or runtime.
binding.dispose();

How this code works

  1. 01
    Connect the agent

    bindAgent uses documented AgentSubscriber callbacks and does not run agent actions.

  2. 02
    Use a stable scope

    scopeId prefixes protocol message, tool, and interrupt IDs for each mounted agent.

  3. 03
    Translate confirmed events

    Text, tool, and interrupt callbacks become standard events when their public data confirms what happened.

  4. 04
    Clean up locally

    dispose removes this subscriber without disposing the AG-UI agent or accessibility runtime.

Options and return values

runtimePick<GenerativeA11yRuntime, 'dispatch'>Required

Receives events translated from documented protocol callbacks.

Default
none
scopeIdstringRequired

Namespaces message, tool, and interrupt identity for one agent binding.

Default
none
agentPick<AbstractAgent, 'subscribe'>Required

A borrowed AG-UI agent exposing the documented subscriber API.

Default
none
maxTrackedEntitiesnumberOptional

Bounds response, tool, and interaction records and fails closed after saturation.

Default
1000
dispose()voidReturn

Unsubscribes this binding and clears adapter-owned identity records.

Default
n/a

Lifecycle mapping

Text callbacks map to response start, content, and completion. Tool callbacks map to confirmed progress and results. Interrupt and resume callbacks map to requests for user input and their resolution. Stable protocol IDs keep each update attached to the correct response or tool.

Expected screen-reader behavior

The runtime paces response text, prioritizes approval and failure states, and suppresses duplicate progress updates. The DOM delivery layer updates live regions without moving focus for normal agent activity. Treat its transcript as browser evidence and run assistive-technology tests for spoken behavior.

What the protocol can report

Text start, content, and end callbacks report a response. Tool callbacks report work and results. Interrupt and resume callbacks report requests for user input. Your adapter does not guess about replay, connection recovery, or retries when AG-UI stays silent.

Troubleshooting

Missing interaction updates usually trace to an agent that was bound before readiness or callbacks that omit stable IDs. Duplicate updates can come from multiple subscribers. Confirm one binding per agent, a stable scopeId, and documented callbacks before adding custom event inference.