AAEPAgent Accessibility Event Protocol

Agent Accessibility Event Protocol (AAEP)

Version: 0.1.0-draft Status: Draft Specification Date: 2026-05-24 Editors: Abdulrafiu Izuafa (Abdulrafiu@izusoft.tech) Repository: github.com/Ramseyxlil/aaep License: Creative Commons Attribution 4.0 International

Status of this document

This document is a Draft Specification of the Agent Accessibility Event Protocol (AAEP). It is published for community review and early implementation feedback. Substantive changes may occur in response to:

Implementations against this draft should be considered experimental. Producers and subscribers may claim "AAEP 0.1-draft compliance" but should not yet claim "AAEP v1 compliance" until a stable 1.0 specification is published.

This specification will be considered stable when:

  1. At least two independent reference implementations of each conformance level exist and pass the conformance test suite.
  2. Formative review with at least eight disabled developers has been completed and findings incorporated.
  3. A W3C Community Group has formed around AAEP and reviewed at least one draft.
  4. At least one major agent framework (Microsoft Agent Framework, AutoGen, LangChain, or Semantic Kernel) has shipped or publicly committed to ship AAEP support.

The current roadmap toward stability is documented in governance/ROADMAP.md.

Abstract

The Agent Accessibility Event Protocol (AAEP) defines a standardized, vendor-neutral, programming-language-neutral format and exchange model that enables AI agents to communicate their lifecycle, internal state, tool invocations, and confirmation requests to assistive technology consumers such as screen readers, voice control software, switch control devices, and other accessibility tools.

AAEP addresses a gap that has emerged with the rise of agentic AI systems: while output rendered to a visual display can be inferred by assistive technology through existing accessibility APIs (UIA on Windows, AT-SPI on Linux, AX API on macOS, ARIA on the web), the internal reasoning state, tool invocations, and asynchronous action streams of an AI agent are not exposed through those APIs. The result is that disabled users frequently experience AI agents as opaque systems that perform actions silently, surface confirmations late or not at all, and produce output flooded with un-paced streaming text. AAEP provides a uniform vocabulary and exchange mechanism so that any compliant agent can interoperate with any compliant subscriber, regardless of programming language, framework, or operating system.

AAEP is designed to coexist with related protocols rather than compete with them. In particular, AAEP is complementary to the Model Context Protocol (MCP), which standardizes how agents discover and call tools; AAEP standardizes how agents communicate about that calling to accessibility consumers. AAEP is also intended to align with W3C Accessible Rich Internet Applications (WAI-ARIA) for web contexts and with platform accessibility APIs (UIA, AT-SPI, AX) for native contexts.

Document organization

This specification is published as a set of chapter files. Readers may consume the chapters individually in the order listed below, or use the joined SPEC.md document generated by the project's continuous integration workflow.

Chapters

# Chapter Summary
1 Introduction Motivation, scope, audience, and high-level overview.
2 Terminology and conventions Definitions of all terms used in normative text; conformance keywords (MUST, SHOULD, MAY) per RFC 2119; notation conventions.
3 Event envelope The required fields every AAEP event carries: @context, type, event_id, session_id, timestamp, producer, verbosity, urgency, localization_hints, and extensions.
4 Core event types The twelve normative event types: lifecycle, reasoning state, tool and action, and human-in-the-loop.
5 Subscription handshake How a subscriber declares its capabilities and a producer negotiates rate, verbosity, languages, and coalescing.
6 Confirmation protocol The blocking flow for irreversible actions: reply tokens, timeouts, default decisions, and security considerations.
7 Extensions How third parties add new event types, fields, and capabilities without breaking interoperability.
8 Transports Transport-agnostic requirements; non-normative bindings for Server-Sent Events, WebSocket, local IPC (Windows named pipes, Unix domain sockets), gRPC, and stdio JSON-RPC.
9 Conformance The three conformance levels (Notification, Interactive, Negotiated) and their normative requirements.
10 Security considerations Threat model, mitigations, signed manifests, and information-disclosure boundaries.
11 Internationalization Language declaration, locale negotiation, Unicode normalization, right-to-left, and culturally-sensitive verbosity.
12 Versioning and evolution How AAEP changes over time, what constitutes a breaking change, and how implementers track conformance across versions.

Appendices

Appendix Title Status
A Event state machine Non-normative reference for legal event orderings within a session.
B Transport bindings Non-normative concrete examples for each major transport.
C Glossary Alphabetical index of terms.
D References Normative and informative references cited throughout the specification.

Reading paths for different audiences

The full specification is approximately 60 pages of prose. Most readers do not need to read all of it. The following reading paths are recommended:

For framework authors and agent developers

Read in order: 1. Introduction 2. Event envelope 3. Core event types 4. Subscription handshake 5. Conformance, sections on Level 1 and Level 2

Then read the Implementer's Guide for integration patterns.

For assistive technology vendors

Read in order: 1. Introduction 2. Event envelope 3. Core event types 4. Subscription handshake 5. Confirmation protocol 6. Internationalization

Then read the Subscribers' Guide.

For standards reviewers and protocol designers

Read the full specification in chapter order, with particular attention to: - Terminology and conventions for normative language usage - Extensions for the protocol's evolution model - Security considerations for the threat model - Versioning and evolution for stability guarantees

For domain experts designing AAEP extensions

Read: 1. Introduction (for context) 2. Event envelope (for the structure extensions plug into) 3. Extensions (the extension model in full)

Then read the Extensions Guide for examples.

For users with disabilities and accessibility advocates

The specification itself is technical, but the Introduction is written to be accessible to non-technical readers. Many readers in this audience may prefer the project FAQ as a starting point.

Notation conventions

The specification uses the following notation conventions throughout.

Conformance keywords

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14] ([RFC 2119], [RFC 8174]) when, and only when, they appear in all capitals, as shown here.

A statement that uses MUST describes an absolute requirement of the protocol. A statement that uses SHOULD describes a strong recommendation that may be deviated from in particular circumstances with full understanding of the consequences. A statement that uses MAY describes an optional feature.

Code blocks

Code blocks render in monospace font and indicate one of:

Real-language code appears only as illustrative example. The normative definition of any protocol element is always the prose specification and the JSON Schema in the schemas/ directory.

Schema references

When the specification refers to a JSON Schema, it cites the schema file relative to the repository root, for example:

The envelope MUST conform to schemas/envelope.schema.json.

The schema file is the canonical machine-readable definition. The prose definition in the specification is canonical for human interpretation. In the event of unresolvable conflict between prose and schema, the prose specification takes precedence; the schema MUST then be corrected in a subsequent patch release.

Normative vs. informative

Each chapter, section, or appendix is marked as either normative or informative at its head.

Appendices and rationale sub-sections within chapters are informative unless explicitly marked otherwise.

Versioning of internal references

Cross-references within the specification use chapter and section numbers, not page numbers. For example, "see §4.3" refers to chapter 4, section 3. Chapter numbers are stable across minor versions of the specification; major versions may renumber chapters and will document the mapping in CHANGELOG.md.

Relationship to other specifications

AAEP is designed to interoperate with, not replace, the following specifications. Implementers building AAEP support should be familiar with the relevant ones for their domain.

Web Accessibility Initiative — Accessible Rich Internet Applications (WAI-ARIA)

[WAI-ARIA] defines roles, states, and properties for accessible web content. ARIA addresses the static and DOM-level accessibility of web interfaces. AAEP addresses the dynamic, agent-state-level accessibility of AI systems that may render through web or native interfaces. Where an AAEP-compliant agent renders output to a web page, the rendered output SHOULD conform to ARIA; the AAEP events about that output complement, not replace, ARIA markup.

Model Context Protocol (MCP)

[MCP] standardizes how LLM applications discover and call tools and resources. AAEP is complementary: where MCP defines the agent-to-tool connection, AAEP defines the agent-to-assistive-technology connection. An agent that uses MCP for tool integration can simultaneously use AAEP for accessibility announcements; the two protocols address orthogonal concerns and do not conflict. A non-normative MCP-to-AAEP bridge example is provided in examples/bridges/mcp-aaep-bridge/.

Platform accessibility APIs

Operating systems expose accessibility trees through platform APIs: UI Automation (UIA) on Windows, the Accessibility API (AX) on macOS, AT-SPI on Linux, and Android Accessibility Service on Android. AAEP runs at a higher abstraction layer: rather than describing the visual state of a UI, AAEP describes the semantic state of an agent's reasoning and actions. Assistive technologies typically receive both signals: AAEP for agent state, and platform APIs for UI state. AAEP subscribers SHOULD coordinate their announcements with platform accessibility APIs to avoid duplication.

W3C Activity Streams 2.0 / JSON-LD

AAEP events are JSON-LD documents. The use of @context and namespaced types follows the conventions established by [ActivityStreams] and the broader JSON-LD ecosystem. This deliberately constrains AAEP's extension model to one with a successful prior track record, including in ActivityPub, Solid, and W3C Verifiable Credentials.

Server-Sent Events (SSE), WebSocket, gRPC, JSON-RPC

These are transport protocols. AAEP defines its own message format and exchange semantics, then specifies how those messages can be carried over multiple transports. Chapter 8 and Appendix B detail the bindings.

Editors and contributors

Lead editor

Abdulrafiu Izuafa — Founder, AAEP project Email: Abdulrafiu@izusoft.tech GitHub: @Ramseyxlil Website: abdulrafiu.me

Contributors

A current list of contributors is maintained in the Git history and surfaced on the project website. Significant contributions are also credited in governance/MAINTAINERS.md and in the acknowledgments section of this specification once a stable 1.0 is published.

Co-authorship invitation

This specification is in active development and welcomes co-authorship contributions, particularly from:

Substantial contributors are credited by name in the specification. See governance/CONTRIBUTING.md for the contribution process.

Acknowledgments

(This section will list named co-authors, formative-study participants, reviewers, and other named contributors as the specification matures. At the time of the 0.1.0-draft release, formal acknowledgments are deferred to the 0.2.0 revision following formative review.)

The author thanks the following prior works for intellectual foundation:

License

This specification is licensed under Creative Commons Attribution 4.0 International (CC-BY-4.0). Implementations, code, and reference materials in this repository are licensed under the MIT License. See LICENSE for the combined notice.

Next steps for readers

Continue to Chapter 1: Introduction, or jump to the chapter most relevant to your role using the reading paths above.