Agent Event Protocol (AEP) is a proposed open protocol for asynchronous communication between large language model agents, tools, memory systems, context providers, environment observers, and multi-agent runtimes.
AEP is designed as the asynchronous counterpart to MCP. MCP is good at synchronous capability invocation: listing tools, calling tools, reading resources, and returning immediate results. AEP focuses on the communication patterns MCP does not naturally cover: event streams, long-running task lifecycle, background feedback, memory updates, context invalidation, durable delivery, replay, cancellation, and agent-to-agent coordination.
AEP 0.1 draft is a multi-language protocol repository with:
- 16 protocol specifications covering session, subscription, task, error, versioning, delivery, reliability, security, conformance, and transport layers
- 4 reference implementations (TypeScript, Python, Go, Java) with cross-language conformance verified against shared fixtures
- 4 transport bindings (stdio, WebSocket, SSE, gRPC) implemented across all languages
- SQLite-backed delivery stores with retry, dead-letter, and replay support in every language
- ~320 tests across four languages, all passing
- Spec site at axisrobo.github.io/aep
Agents should not only ask for capabilities. They also need to listen, react, coordinate, and recover.
AEP defines a common event model so that agents can receive asynchronous feedback from tools, other agents, memory systems, external environments, and runtime infrastructure without forcing every system to invent a custom callback, polling, or message queue interface.
AEP covers:
- Asynchronous events and notifications
- Publish / subscribe communication
- Long-running tool and task lifecycle
- Progress, output, completion, failure, cancellation, and timeout events
- Context and memory change streams
- Environment observation streams
- Agent-to-agent messages
- Delivery acknowledgement, replay, and correlation
- Transport bindings for local and distributed runtimes
AEP does not replace:
- MCP synchronous tool invocation
- LLM completion APIs
- Vector database APIs
- Business-specific memory schemas
- General-purpose message brokers
| MCP | AEP |
|---|---|
| Synchronous request / response | Asynchronous event streams |
| Tool invocation | Task lifecycle and tool feedback |
| Resource reading | Context updates and invalidation |
| Client-driven calls | Producer-driven events |
| Immediate result | Deferred, incremental, replayable results |
AEP should interoperate with MCP rather than fork it. AEP can carry events about MCP tool calls, but it should remain protocol-independent enough to support non-MCP agents, tools, memory systems, robotics systems, browsers, IDEs, and cloud runtimes.
docs/vision.md— project vision, goals, non-goals, and principlesdocs/architecture.md— system architecture and major protocol layersdocs/protocol-design.md— initial protocol model, envelope, events, and lifecycledocs/mcp-relationship.md— detailed comparison and interop model with MCPdocs/roadmap.md— proposed phases toward a usable open protocoldocs/specs/session.md— session lifecycle specificationdocs/specs/subscription.md— subscription model specificationdocs/specs/task-lifecycle.md— task lifecycle specificationdocs/specs/error-model.md— error model specificationdocs/specs/versioning.md— versioning rules specificationdocs/specs/transport-stdio.md— stdio transport specificationdocs/specs/transport-websocket.md— WebSocket transport specificationdocs/specs/transport-sse.md— HTTP SSE transport specificationdocs/specs/transport-grpc.md— gRPC streaming transport specificationdocs/specs/delivery.md— delivery semantics, acknowledgement, and replay specificationdocs/specs/reliability.md— retry, durability, and dead-letter handling specificationdocs/specs/security.md— identity, authorization, audit, and tenant isolation specificationdocs/specs/conformance.md— draft conformance levels and shared fixture manifest rulesdocs/specs/event-registry-governance.md— event type registry governance and versioningCONTRIBUTING.md— contribution guide and repository conventionsCODE_OF_CONDUCT.md— contributor code of conduct
docs/— protocol vision, architecture, design drafts, specifications, roadmap, and Superpowers artifactsdocs/specs/— per-layer protocol specifications (session, subscription, task lifecycle, error model, versioning)schemas/— shared draft JSON Schema assetsconformance/— shared fixtures for reference implementation parityreference/— language-specific reference implementationsreference/typescript/— primary runnable AEP reference implementationreference/python/— second-priority reference implementation with full transport and delivery supportreference/go/— Go reference implementation with C0/C1 conformancereference/java/— Java reference implementation with C0/C1 conformance (JDK 21).github/workflows/— repository CI
This project uses Superpowers as its agent development harness. OpenCode loads it through opencode.json; durable specs and plans live under .superpowers/.
AGENTS.md— OpenCode project rulesCLAUDE.md— Claude Code project rules.superpowers/specs/— Superpowers-backed design specs.superpowers/plans/— Superpowers-backed execution plans
The repository includes a minimal local AEP 0.1 draft conformance harness that uses newline-delimited JSON over stdio.
Run tests:
cd reference/typescript && npm install
cd reference/typescript && npm testRun TypeScript conformance fixtures:
cd reference/typescript && npm run conformanceRun cross-language conformance:
node tools/conformance-runner.jsThis runs shared fixtures across all four language references and prints a unified pass/fail matrix.
Run the stdio harness:
cd reference/typescript && npm run harness < ../../conformance/fixtures/task-lifecycle.ndjsonRun examples:
cd reference/typescript && npm run demo:async-tool
cd reference/typescript && npm run demo:memory
cd reference/typescript && npm run demo:agent
cd reference/typescript && npm run demo:mcp-bridge
cd reference/typescript && npm run demo:mcp-aep-consumer
cd reference/typescript && npm run demo:production-e2eThe harness validates draft envelope fields, checks event types against the standard registry, creates subscriptions, tracks task lifecycle, supports stdio/WebSocket/SSE transports, validates shared JSON Schemas, and demonstrates MCP interop.
The rendered specification is published at https://axisrobo.github.io/aep/.
AEP is a draft open protocol with four active reference implementations (TypeScript, Python, Go, Java) maintaining cross-language parity. The repo includes layered specifications for session, subscription, task lifecycle, error model, versioning, conformance, delivery, reliability, security, event registry governance, and four transport bindings (stdio, WebSocket, SSE, gRPC). Each reference supports SQLite-backed delivery stores, and a cross-language conformance runner (node tools/conformance-runner.js) validates shared fixtures across all four languages.