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
Dispatch tool.started when a named user-relevant operation begins, tool.progress only for meaningful milestones, and tool.completed or tool.failed at the confirmed terminal state. Use interaction.requested and interaction.resolved for approval or other user decisions. Report connection and response retry events only when the application or framework provides reliable evidence.
| 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
Approval requests and failures can use higher announcement priority than routine progress, but ordinary agent lifecycle updates do not move focus. If an approval control needs focus, the host application must make that separate interaction decision using its own accessible dialog, disclosure, or inline workflow.
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.