Skip to main content

aaep-tools

Official command-line tools for the Agent Accessibility Event Protocol. Install once, get three commands for working with AAEP event streams.

pip install aaep-tools

After installation:

aaep-validate --help
aaep-capture --help
aaep-replay --help

Requires Python 3.10 or newer.


What's included

Command What it does
aaep-validate Validates events against the AAEP JSON Schemas
aaep-capture Records SSE event streams from a running producer to JSONL
aaep-replay Replays JSONL streams as SSE servers for testing subscribers

All three are language-and-framework agnostic. They work with any conformant AAEP producer or subscriber regardless of implementation language.


Quick reference

Validate

# Validate a single event from stdin
cat event.json | aaep-validate

# Validate a captured stream
aaep-validate captured.jsonl

# Validate multiple files
aaep-validate event1.json event2.json stream.jsonl

# Machine-readable JSON output
aaep-validate --json captured.jsonl | jq 'select(.valid == false)'

# CI mode (silent, exit code only)
aaep-validate --quiet captured.jsonl

Exit codes: 0 (all valid), 1 (any invalid), 2 (usage/I/O error).

Capture

# Capture from a running producer until Ctrl-C
aaep-capture --endpoint http://localhost:8080 --output session.jsonl

# Capture for 60 seconds
aaep-capture --endpoint http://localhost:8080 --output session.jsonl --timeout 60

# Capture exactly 100 events
aaep-capture --endpoint http://localhost:8080 --output session.jsonl --max-events 100

# Capture only critical-urgency events
aaep-capture --endpoint http://localhost:8080 --output critical.jsonl --filter-urgency critical

# Capture only tool events from one session
aaep-capture --endpoint http://localhost:8080 --output debug.jsonl \
    --filter-type tool.invoked --filter-type tool.completed \
    --filter-session sess_abc123

The output file is always closed cleanly on Ctrl-C — no partial JSON lines.

Replay

# Replay a captured stream at original pace on port 9000
aaep-replay --file session.jsonl --port 9000

# Replay 10x faster
aaep-replay --file session.jsonl --port 9000 --speed 10

# Replay as fast as possible (no inter-event delay)
aaep-replay --file session.jsonl --port 9000 --no-delay

# Loop replay continuously for soak testing
aaep-replay --file session.jsonl --port 9000 --loop --no-delay

The server provides standard AAEP endpoints:

  • GET /events — SSE stream of replayed events
  • GET /healthz — health check with current state

Programmatic API

If you need to invoke the functionality from Python code rather than the CLI:

from aaep_tools.validate import validate_event, validate_stream
from aaep_tools.capture import capture_stream
from aaep_tools.replay import load_events, run_replay

# Validate a single event
result = validate_event({
    "type": "aaep:agent.session.started",
    # ... rest of event ...
})
if not result.valid:
    for error in result.errors:
        print(error)

# Validate a JSONL stream
with open("captured.jsonl") as f:
    for result in validate_stream(f):
        if not result.valid:
            print(f"{result.location}: {result.errors}")

# Capture (async)
import asyncio, sys
async def grab():
    captured, reason = await capture_stream(
        endpoint="http://localhost:8080",
        output=sys.stdout,
        timeout_seconds=30,
    )
    return captured

asyncio.run(grab())

# Load and inspect captured events
events = load_events(Path("captured.jsonl"))
print(f"Captured {len(events)} events")

Use cases

Producer development. Run aaep-validate in CI on every captured event stream. Catch malformed events before they ship.

Subscriber development. Capture real production traces with aaep-capture, then replay them with aaep-replay to test subscribers against canonical inputs. Replays are deterministic and shareable.

Conformance verification. The aaep-conformance package uses these tools for advanced test scenarios. They also stand alone as a lightweight verification harness.

Production debugging. Capture an incident in real time:

aaep-capture --endpoint http://prod.example.com --output incident.jsonl --timeout 300

Then inspect offline, validate, and share with your team.

Accessibility research. Capture event streams from various producers, share as datasets, analyze cross-producer behavior. Researchers can study how different agents emit AAEP events without needing to run those agents themselves.


Design philosophy

These tools are intentionally minimal:

  • One thing each, well. Following the Unix tradition. Validate doesn't capture, capture doesn't validate, replay doesn't filter.
  • Composable. Chain them together with pipes. Use them in scripts. Run them in CI.
  • Offline-friendly. Schemas are bundled with the package. Works behind firewalls and air gaps.
  • Standard I/O conventions. Reads from stdin, writes to stdout, exit codes follow Unix convention.
  • No surprises. No GUI, no configuration files, no plugins. What you type is what happens.

If you need richer functionality (live web dashboards, complex pipelines, multi-step automation), build it on top of these tools rather than asking us to bloat them.


Stability

aaep-tools is Production/Stable. The three commands have stable CLIs and stable programmatic APIs. Breaking changes follow semver: a major version bump (2.0.0) signals breaking changes; minor versions add features compatibly.

The bundled JSON Schemas track the AAEP specification version. Currently AAEP 1.0.0.



License

MIT. See LICENSE in the repository.

Metadata

Release files for aaep-tools 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aaep-tools 1.0.0
File Size Uploaded Provenance Actions
aaep_tools-1.0.0.tar.gz 16.2 kB Without provenance Details for aaep_tools-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aaep-tools 1.0.0
File Interpreter ABI Platform Actions
aaep_tools-1.0.0-py3-none-any.whl Python 3 none any Details for aaep_tools-1.0.0-py3-none-any.whl

Total release size: 31.7 kB

Release files / aaep_tools-1.0.0.tar.gz

Download URL aaep_tools-1.0.0.tar.gz
Size 16.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5a42a4e2bbcc481e242e9f1ae913e3d0c1520f2d335ab9a02fd6ae476f00debb
BLAKE2b-256 checksum
How to use checksums
f152973033f347c3791e5a7f6bc41253fd7746bc05a1895b68da6fd5401c1682
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / aaep_tools-1.0.0-py3-none-any.whl

Download URL aaep_tools-1.0.0-py3-none-any.whl
Size 15.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8430932a551ec36dc5cf85959e9a9358e8ad0cb693263bc9ac0e8089945db8ab
BLAKE2b-256 checksum
How to use checksums
333a5750c4838b249cabfddf5087353c2a9cf7a678c7a1c8cb3a5562ab71af27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for aaep-tools 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page