Skip to main content

Python Minimal Producer Example

A minimal but complete AAEP producer implementation in Python. This example demonstrates the manual loop pattern from the Implementer's Guide §2.5 at production quality.

This is the reference example. If you're building an AAEP producer from scratch in Python without using a framework like LangChain, copy this code and adapt it. Every other example in this repository follows patterns established here.


What this example demonstrates

  • A complete agent loop emitting valid AAEP events
  • All 12 core AAEP event types in realistic usage
  • The confirmation flow for irreversible actions
  • Streaming output with proper coalescing
  • Tool invocation with arguments redaction
  • Session lifecycle management with terminal events on success, cancellation, and error
  • HTTP/SSE transport binding for subscribers
  • Conformance Level 2 ready (passes the full aaep-conformance producer --level 2 test suite)

This example does NOT include:

  • LangChain or any other framework integration (see ../python-langchain/)
  • Real LLM integration (uses a mock LLM client for portability)
  • Production-grade authentication or rate limiting (those belong at a higher layer)

Installation

cd examples/producers/python-minimal
pip install -e .

Requires Python 3.10 or newer.


Quick start

Start the producer server:

python -m aaep_minimal_producer.server --port 8080

In another terminal, run a session:

curl -X POST http://localhost:8080/sessions \
    -H "Content-Type: application/json" \
    -d '{"user_message": "Tell me about retirement planning."}'

Subscribe to events via SSE:

curl -N http://localhost:8080/events

You'll see properly-formatted AAEP events stream in real time.


Running the conformance suite against it

Verify the example passes AAEP Conformance Level 2:

# Terminal 1: start the producer
python -m aaep_minimal_producer.server --port 8080

# Terminal 2: run conformance tests
aaep-conformance producer --endpoint http://localhost:8080 --level 2

Expected output: VERDICT: PASS. If you see anything else, please file a bug — this is the reference; it must pass.


Project layout

python-minimal/
├── README.md
├── pyproject.toml
├── aaep_minimal_producer/
│   ├── __init__.py
│   ├── emitter.py         # AAEPEmitter, StreamCoalescer, make_id
│   ├── agent.py           # AgentLoop with full lifecycle
│   └── server.py          # HTTP/SSE server
└── tests/
    ├── __init__.py
    └── test_agent.py

The intent: someone reading this code top-to-bottom in an hour can understand exactly how AAEP is emitted. No magic, no framework wrappers, no implicit machinery.


Key design decisions

1. The emitter is a thin wrapper, not a framework

AAEPEmitter is ~200 lines. It exposes one method per event type. You can read the whole thing in fifteen minutes.

There's no plugin system, no middleware chain, no decorator magic. If you want those, see the other examples — they each demonstrate one pattern. This one shows the underlying machinery directly.

2. The agent loop is explicit

AgentLoop.run() shows every state transition, every tool call cycle, every output emission. It's verbose by design — verbosity is the price of transparency.

If your agent has different needs (concurrent tools, recovery from failures, multi-turn within one session), you'll edit this loop. That's the point: it's a starting template, not a black box.

3. Errors are emitted as terminal events, never swallowed

Every exception path in the loop emits agent.session.errored with the appropriate error_category and re-raises. A session that started MUST end with one of the three terminal event types. The conformance suite verifies this.

4. The HTTP/SSE transport is replaceable

server.py is a working HTTP/SSE transport, but the agent logic doesn't depend on HTTP. If you need WebSockets, gRPC, or stdio JSON-RPC, replace server.py and the agent code works unchanged.


See also

Metadata

Release files for aaep-minimal-producer 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-minimal-producer 1.0.0
File Size Uploaded Provenance Actions
aaep_minimal_producer-1.0.0.tar.gz 20.8 kB Without provenance Details for aaep_minimal_producer-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 38.6 kB

Release files / aaep_minimal_producer-1.0.0.tar.gz

Download URL aaep_minimal_producer-1.0.0.tar.gz
Size 20.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1376a67f675e013d7dea641db14454f88adf5e3dc51715df6d42ae5e2dea47a1
BLAKE2b-256 checksum
How to use checksums
fa0478e7bcecc5a37b562b76c30c622b3264839f787a17a079dc5c3e1738988f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

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

Download URL aaep_minimal_producer-1.0.0-py3-none-any.whl
Size 17.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2549b15bd4748a8b411706fd05549e1043bb3b3970c9aeaa7cb511f77e9ca2db
BLAKE2b-256 checksum
How to use checksums
c526013f0404d5d63f1d9fd984d1325697ef64c9a6616841fbb3ab906b656398
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for aaep-minimal-producer 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