Agent Event Protocol

One event language for many agents

What AEP makes explicit

Most coding agents already expose a basic pre-tool hook. AEP is about the activity model around that hook: stable event identity, action correlation, catalog identity for tools and MCP servers, session and workspace context, execution outcomes, and control responses. Those are the pieces consumers need for approvals, audit trails, policy evaluation, and observability as agents move beyond one tool call at a time.

Choose a provider to see how its current hook surface maps into the same canonical needs. The AEP column is the shape consumers can target; the provider column shows where that data comes from today or where the source is still implicit. Top-level event fields stay top-level in the spec: no wrapper object is implied.

The basic tool request stays simple: a provider can emit action.requestedwith action.input and tool.name. The same envelope can then carry richer activity without adding a new one-off schema for each agent capability.

At a glance

The full canonical envelope. aep_version, id, type, time, and optional hook are top-level fields. Catalog nouns (tool, server, skill) are top-level peers; the action object is the verb that references them via discriminators.

Example AEP event

Snake_case JSON. Producers omit fields they don't provide rather than emitting null. Consumers tolerate omitted fields and ignore unknown extensions.x-* keys.

{
  "aep_version": "0.1",
  "id": "evt_01HXY7GZ3K8MZ9",
  "type": "action.requested",
  "time": "2026-05-09T12:00:00.000Z",
  "hook": "PreToolUse",

  "agent": {
    "slug": "claude",
    "display_name": "Claude Code",
    "version": "1.4.2"
  },
  "session": {
    "id": "sess_abc",
    "conversation_id": "conv_8a1",
    "permission_mode": "default"
  },
  "user": { "email": "user@example.com" },
  "workspace": { "cwd": "/workspace/project" },
  "model": { "id": "claude-sonnet-4-6", "provider": "anthropic" },

  "action": {
    "type": "tool_call",
    "id": "call_xyz",
    "input": { "command": "bun test" }
  },
  "tool": {
    "id": "01HXY7QWPZ6PR0XEHZ3M2Q3WYZ",
    "type": "native",
    "name": "Bash",
    "description": "Executes a given bash command and returns its output. The working directory persists between commands, but shell state does not.",
    "version": "1.4.2",
    "schema": {
      "type": "object",
      "required": ["command"],
      "properties": {
        "command":           { "type": "string",  "description": "The command to execute" },
        "description":       { "type": "string",  "description": "5-10 word description of what the command does" },
        "timeout":           { "type": "number",  "description": "Optional timeout in milliseconds (max 600000, default 120000)" },
        "run_in_background": { "type": "boolean", "description": "Run command in background; use Read/Monitor for output" }
      }
    }
  }
}

Objects in detail

Every group in the envelope, expanded. All fields documented here are optional unless noted; unset fields SHOULD be omitted from the wire.

Event types

Twenty-one canonical types organized into five families. Past-participle for actions that completed (action.completed, prompt.submitted); bare noun for entities (model.thought, session.start).

Required fields below are in addition to the core envelope:aep_version, id, type, time, and agent. Parenthetical chips are conditional on the action kind or tool type.

Hook responses

Blocking hooks have two sides: an immutable AEP event sent into the hook, and a separate AEP response returned to the agent runtime. Apps can join both records by action.id to show one activity row.

{
  "aep_version": "0.1",
  "id": "rsp_01HXY7GZ3K8MZ9",
  "request_event_id": "evt_01HXY7GZ3K8MZ9",
  "action_id": "call_xyz",
  "time": "2026-05-09T12:00:04.820Z",
  "control": {
    "behavior": "allow",
    "message": "Matched allowlist rule shell.tests",
    "updated_input": { "command": "bun test --filter api" }
  },
  "decision": {
    "outcome": "approved",
    "by": "auto-policy",
    "reason": "matched allowlist rule shell.tests",
    "response_time_ms": 4820
  }
}

Display styles

Producer hints for how a content/value field is intended to render. Consumers may ignore them and substitute their own.

Integrate your agent

Two paths, same wire format. Pick native AEP if you can change your hook output; pick a mapping if you ship an existing agent and don't want to.

Mapping files

A mapping file says: for each of my hook events, this is the AEP type and these are the JSON Pointer paths to the source fields. Declarative, reviewable, swappable without a consumer rebuild.

schema_version: aep.mapping/v1
agent: cursor
display_name: Cursor

events:
  - id: cursor.shell_approval
    source_event: beforeShellExecution
    when:
      /event_name: beforeShellExecution
    canonical_event: action.requested
    fields:
      action.id:
        source: /tool_call_id
      action.input:
        source: /tool_input
        display_style: indented_json
      tool.name:
        source: /tool_name
        display_style: plain_text
      workspace.cwd:
        source: /cwd
        display_style: path
    content:
      - type: prompt
        text:
          source: /prompt
        style: markdown

Versioning and conformance

Agent Approve uses AEP to render every supported agent on iPhone and Apple Watch with one rendering layer. See the changelog for AEP draft updates and product changes.