What is the Agent Event Protocol?

AEP is an open, vendor-neutral standard for agent activity events and control: any agent emits lifecycle, tool, progress, and attention events once, and any dashboard, bridge, or automation consumes them once, for every agent.

AEP (Agent Event Protocol) is an open, vendor-neutral standard for agent activity events and control.

An AI agent doing work generates a stream of facts: a run started, a tool ran, a step is 40% through, a human needs to approve something. Every agent runtime emits those facts differently, so anything that wants to watch them (a dashboard, a history store, a notifier, an automation) is written once per runtime. AEP standardizes the wire format instead: any agent emits lifecycle, tool, progress, and attention events once, over stdio (JSONL), HTTP, SSE, or WebSocket, and any consumer reads one vocabulary for every agent it watches.

Think of AEP the way syslog works for daemons, or OTLP for services: not a new place to send your data, but one agreed shape for it, so the tools that read it stop caring who produced it.

graph TD
    A["Any agent runtime"] --> AD[Adapter]
    AD -->|"AEP Events"| R[Relay]
    R --> C["Dashboard, notifier, automation"]
    C -->|"control commands"| R

Events flow out; control commands flow back along the same stream, so approving a tool call or answering an agent's question lands in the same replayable history as everything else. See AEP-0001 §4.2 for the architecture and AEP-0004 for the control profile.

What AEP makes possible

• One timeline across every runtime you run. A coding agent, a support bot, and a batch job runner appear on the same stream, in the same vocabulary.
• Agent-needs-a-human as a routable event. attention.requested can reach a phone, a chat channel, or a policy automation, and be answered from there, without the agent knowing which. See the taxonomy tour.
• Approve, cancel, or pause from anywhere. Control commands are ordinary events, so every control action is audit-logged by construction rather than written to a separate log.
• Kill a consumer and reattach without losing events. (epoch, seq) resume returns exactly the tail that was missed. See the envelope and identity.
• Feed your existing pipeline. Normative bridges map the same stream into CloudEvents and OTLP, so adopting AEP does not mean a second instrumentation pass. See AEP-0005.

Why AEP matters

Where you sit determines which part matters most.

• Agent authors. Write one adapter and every AEP consumer works with your runtime. You do not negotiate a format with each dashboard vendor.
• Consumer authors. Write against one contract and support every agent that speaks it, including runtimes that did not exist when you shipped.
• Fleet observers. Watch many sessions you did not initiate, retain them uniformly, and act on the ones that need a human. This is the case no adjacent protocol was built for; see what and why AEP.
• Security and compliance readers. Capture levels decide what content leaves the machine, per event, and the control round-trip leaves an audit trail in the stream itself.

The envelope in one glance

Every Event is a self-describing JSON object: 16 context attributes plus data. The attributes are what make fleet-wide ordering, causality, capture levels, and replay possible.

{
  "aep": "0.1", "id": "01JZX7Q4R8T0V2W4X6Y8Z0AB1C",
  "source": "aep://host-1/agent/claude-code/session/s_9f2c",
  "type": "tool.completed", "subject": "Bash",
  "agent": "claude-code", "session": "s_9f2c", "run": "r_01",
  "step": "turn-3", "seq": 42, "epoch": 1,
  "time": "2026-07-04T12:00:00.000Z",
  "cause": "01JZX7Q4R8T0V2W4X6Y8Z0AB0B",
  "severity": "info", "capture": "metadata",
  "data": { "tool": { "name": "Bash", "call_id": "t_91" },
            "status": "success", "duration_ms": 412 }
}

The taxonomy that fills type is fixed rather than open-ended: 13 categories, 14 mandatory types, defined in AEP-0002. A field-by-field walk through the envelope is in the envelope and identity.

Start here

New to AEP? Read these two in order, then pick a task below.

Build something

Learn the concepts

Ecosystem

The standard lives here; the runnable code lives in sibling repositories. The reference stack ships twelve adapters, eight bridge sidecars (2 outbound, 6 inbound), an MCP server, and the aep CLI, and self-certifies its conformance classes in CI against this repository's checker.

Which runtimes are covered today, and what each one exposes, is tracked in supported agents and vendor surfaces. How the reference code is put together is documented under components.

Contribute

Spec changes follow the AEP proposal process, and the one rule that never bends is that normative text lands with its conformance fixtures in the same change.

• Contributing: how to propose a change.
• Governance: the AEP process, the firewall, versioning.
• AEP-TEMPLATE.md: start a proposal.

About these docs

These docs explain. The specification defines: it is the single normative source, and every page here links into it rather than restating it (the firewall). When a doc and the spec disagree, the spec wins.

• Docs style & conventions: read before writing any doc.
• _TEMPLATE.md: copy to start a new doc.
• check-docs.sh: the offline QA gate (mermaid, links, spec terms, running counts), run in CI as its own docs job so public docs cannot drift.