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 2test 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
../python-langchain/— same agent, LangChain callback pattern../python-anthropic-sdk/— direct Anthropic SDK integration../typescript-minimal/— equivalent in TypeScript- Implementer's Guide §2.5 — the manual loop pattern theory
- Quickstart — the 50-line version of this example
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.