Skip to main content

Python Anthropic SDK Producer Example

AAEP integration with the official Anthropic Python SDK. This example demonstrates how to emit AAEP events from agents built directly on anthropic.Anthropic() and client.messages.stream(), without any agent framework.

If you're building Claude-powered agents using the Anthropic SDK and want AAEP support, this is the example to copy.


What this example demonstrates

  • Direct integration with client.messages.stream() and client.messages.create()
  • Native handling of Anthropic's streaming event format (content_block_delta, content_block_start, etc.)
  • Tool use translation: Anthropic's tool_use content blocks → AAEP agent.tool.invoked
  • Multi-turn conversation handling
  • Proper Claude model version reporting in producer.model
  • Streaming output with sentence-boundary coalescing
  • All 12 core AAEP event types in realistic Anthropic-API-driven usage

This example reuses the AAEPEmitter from python-minimal — same machinery, different integration. The Anthropic-specific code is just the adapter between Anthropic's API and the emitter.


When to use this pattern vs others

Pick this pattern when:

  • You use the Anthropic Python SDK directly
  • You want to leverage Anthropic's native tool use, prompt caching, or extended thinking
  • You don't need (or don't want) a framework abstraction

Pick python-langchain when: you already use LangChain (regardless of LLM provider).

Pick python-minimal when: you're building everything from scratch, including your own LLM client.


Installation

cd examples/producers/python-anthropic-sdk
pip install -e .

You'll need an Anthropic API key in your environment:

export ANTHROPIC_API_KEY="sk-ant-..."

Requires Python 3.10 or newer.


Quick start

import anthropic
from aaep_anthropic_sdk import AnthropicAAEPAdapter

# Step 1: Set up your Anthropic client normally
client = anthropic.Anthropic()

# Step 2: Wrap it with the AAEP adapter
def my_transport(event):
    """Send the event to subscribers (HTTP/SSE, WebSocket, etc.)"""
    print(event)  # in production: serialize and send

adapter = AnthropicAAEPAdapter(send_event=my_transport, model="claude-opus-4-7")

# Step 3: Run a session through the adapter
session_id = await adapter.run_session(
    user_message="Tell me about retirement planning.",
    tools=[
        {
            "name": "fetch_balance",
            "description": "Look up an account balance",
            "input_schema": {
                "type": "object",
                "properties": {"account": {"type": "string"}},
            },
        },
    ],
    tool_handlers={
        "fetch_balance": lambda account: f"Balance for {account}: $3,247.18",
    },
)

That's all. The adapter calls Claude, processes the streaming response, executes any tool_use blocks (with confirmation for irreversible tools), and emits AAEP events throughout.


Running the included demo

python -m aaep_anthropic_sdk.example_agent

This runs three example sessions (basic query, tool use, multi-turn) against Claude and prints every emitted AAEP event.

Note: the demo requires ANTHROPIC_API_KEY to be set. If not set, it falls back to a mock mode that doesn't call the real API.


Running the conformance suite against it

# Terminal 1: start the server (uses mock mode by default for portability)
python -m aaep_anthropic_sdk.server --port 8082

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

The conformance suite drives the adapter with synthetic user prompts and verifies the resulting AAEP event streams.


Project layout

python-anthropic-sdk/
├── README.md
├── pyproject.toml
├── aaep_anthropic_sdk/
│   ├── __init__.py
│   ├── adapter.py             # AnthropicAAEPAdapter
│   ├── example_agent.py       # Runnable demo with real Anthropic API
│   └── server.py              # HTTP/SSE wrapper for conformance testing
└── tests/
    ├── __init__.py
    └── test_adapter.py

Key design decisions

1. The adapter directly consumes Anthropic's streaming events

Anthropic's client.messages.stream() returns a structured event stream:

  • message_start — model begins responding
  • content_block_start — new content block (text, tool_use, etc.)
  • content_block_delta — incremental update (text_delta, input_json_delta)
  • content_block_stop — content block done
  • message_delta — usage stats, stop_reason
  • message_stop — full message done

The adapter translates each into the appropriate AAEP event. Text deltas feed the StreamCoalescer; tool_use blocks become tool.invoked/tool.completed pairs; stop_reason informs the terminal event.

2. Tool use safety enforced before execution

When Claude emits a tool_use content block, the adapter:

  1. Emits agent.tool.invoked BEFORE calling the handler
  2. For irreversible or high-risk tools: emits agent.awaiting.confirmation and blocks on the reply
  3. Only executes the tool handler on decision: "accept"
  4. Emits agent.tool.completed with the result

This means an unsafe action (e.g., send_email) cannot execute without explicit user consent — regardless of what the model "wants" to do.

3. Model version included in producer

The adapter reports the exact Claude model version in producer.model, so subscribers know which model is responding (different models may need different verbosity treatment for accessibility). When using claude-opus-4-7, you'll see "model": "claude-opus-4-7" in every emitted event.

4. Same emitter as python-minimal

The adapter imports AAEPEmitter, StreamCoalescer, and make_id from the python-minimal package. Bug fixes propagate; safety guarantees are uniform across all examples.


See also

Metadata

Release files for aaep-anthropic-sdk-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-anthropic-sdk-producer 1.0.0
File Size Uploaded Provenance Actions
aaep_anthropic_sdk_producer-1.0.0.tar.gz 19.0 kB Without provenance Details for aaep_anthropic_sdk_producer-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 35.0 kB

Release files / aaep_anthropic_sdk_producer-1.0.0.tar.gz

Download URL aaep_anthropic_sdk_producer-1.0.0.tar.gz
Size 19.0 kB
Tags Source
SHA-256 checksum
How to use checksums
aea37d126f3a8d449ead25cdf1c49dbf593e17ff4e8e006025ee75959d91152a
BLAKE2b-256 checksum
How to use checksums
278bb7bcb0ed61598deda0e4cc6de0129f324d3936ca10cbc4d71b6b200362cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

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

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

Security for aaep-anthropic-sdk-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