Accessible AI agents and tool execution
Design screen-reader announcements for AI agent progress, tool calls, approvals, interruptions, failures, retries, and results.
Agent interfaces have more states than a chat transcript
An agent can start a long-running tool, report progress, request a decision, lose its connection, retry, and finish with a result. Visual indicators may make these transitions obvious, while a screen-reader user remains on the composer, transcript, or another part of the page.
Accessibility depends on communicating consequential state changes without narrating every internal operation. Announcements should describe the user-facing lifecycle, not expose raw tool payloads, backend errors, or chain-of-thought-like implementation detail.
Map confirmed agent state to normalized events
Choose events from confirmed application state. Tool argument streaming does not establish that execution started; a disappearing approval control does not establish that a decision was submitted. Keep stable IDs across each operation and attach an instance ID when work can retry.
| Agent state | Normalized event | Announcement purpose |
|---|---|---|
| Tool begins | tool.started | Set context for a user-relevant operation |
| Meaningful milestone | tool.progress | Report progress without flooding |
| Approval needed | interaction.requested | Make a required decision discoverable |
| Tool fails | tool.failed | Communicate the safe user-facing failure label |
| Response retries | response.retrying | Cancel stale response work and identify the retry |
| Connection changes | connection.lost / restored | Report confirmed availability changes |
Prioritize decisions and failures without stealing focus
An AI agent approval request should be announced as a confirmed request for input, while the approval control remains part of the host application’s normal keyboard and focus model. Routine progress can stay polite; required decisions and safe failure labels can receive higher priority. The event stream must keep each update attached to a stable response, tool, or approval identity so stale work can be cancelled after retries and interruptions.
If an approval control needs focus, the host application makes that interaction decision through its accessible dialog, disclosure, or inline workflow. See interactions and approvals for the event contract.
Bounded queues and terminal-event cleanup prevent outdated progress from being delivered after a retry, failure, interruption, or disposal.
Choose an adapter by observable lifecycle fidelity
The AI SDK, assistant-ui, and AG-UI adapters translate documented public framework state into the normalized event model. Their pages list what they can observe. When the host application knows about additional connection, retry, or approval states, it can dispatch those core events directly instead of asking an adapter to infer them from rendered UI.
Sources and evidence
ARIA live regions for generative AI
Understand what ARIA live regions provide, why streaming tokens are a poor announcement unit, and how generative-a11y separates policy from delivery.
Accessibility model and architecture
Follow an AI lifecycle event through the framework-independent runtime, scheduling policy, and DOM delivery that produce paced screen-reader updates.