Metadata-Version: 2.1
Name: openai-agents-zambo
Version: 0.1.14
Summary: Verifiable execution receipts for OpenAI Agents SDK agents. Every tool call mints a verifiable AER-1 receipt at zambo.dev.
Author-email: Zambo <brennanzambo@zambo.dev>
License: MIT
Project-URL: AER-1 standard, https://zambo.dev/aer1/
Project-URL: Add Zambo to your AI, https://zambo.dev/add
Project-URL: Homepage, https://zambo.dev
Keywords: openai,agents,ai-agents,zambo,mcp,receipts,verification,verifiable-execution-receipts,execution-receipts,verifiable-receipt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# openai-agents-zambo

**AER-1, the agent execution receipt standard: [zambo.dev/aer-1](https://zambo.dev/aer-1/) | Add Zambo to your AI: [zambo.dev/add](https://zambo.dev/add)**

Zambo is the verifiable work layer for AI. This package mints a verifiable AER-1 receipt for every OpenAI Agents SDK tool event at zambo.dev.

Receipt format: AER-1, IETF Internet-Draft [draft-zambo-aer1-26](https://datatracker.ietf.org/doc/draft-zambo-aer1/26/).

Verifiable AER-1 execution receipts for OpenAI Agents SDK agents. OpenAI Agents SDK integration for [Zambo](https://zambo.dev): give any `agents` agent a tool backed by Zambo's MCP tools, and mint a verifiable execution receipt for every tool event.

Receipts follow [AER-1](https://zambo.dev/aer-1/), the IETF draft for verifiable execution receipts created by Brennan Zambo.

- Every call can mint a public, verifiable receipt (`https://zambo.dev/run/<id>`).
- Free tier: 20 calls + 1 wrap-up free every day, no account.
- Endpoint override via `ZAMBO_API_URL` (default `https://zambo.dev/mcp`).
- Hook failures are recorded in `receipt_errors` and never break the run.

> For whole-run workflow receipts with a Merkle root (AER-1 Section 8), see [aer1-openai-agents](https://pypi.org/project/aer1-openai-agents/).

## Install

```bash
pip install openai-agents-zambo openai-agents
```

## Example

```python
import asyncio
from agents import Agent, Runner
from openai_agents_zambo import ZamboRunHooks, zambo_function_tool

hooks = ZamboRunHooks()

agent = Agent(
    name="researcher",
    instructions="Use ask_zambo for anything Zambo's tools can do.",
    tools=[zambo_function_tool()],
)

result = asyncio.run(Runner.run(agent, "What is the capital of France?", hooks=hooks))
print(result.final_output)
print("Receipts:", hooks.receipt_urls)  # public verifiable receipt URLs
print("Errors:", hooks.receipt_errors)
```

Requires OPENAI_API_KEY in your environment.

## API

- `ZamboRunHooks(timeout=30.0)` subclasses `agents.RunHooks`. Its `on_tool_start`/`on_tool_end` publish a receipt for the tool event. Tracks `receipt_urls`, `receipt_errors`, `last_receipt_url`.
- `zambo_function_tool(name="ask_zambo", description=..., timeout=30.0)` returns an `agents.FunctionTool` wrapping `zambo_universal`. On invocation it calls the endpoint, captures the public receipt URL, and appends it to the returned text. Same receipt tracking attributes. Raises an informative `ImportError` if `openai-agents` is not installed.

## Honesty note

Receipts record what the Zambo endpoint observed: the goal it received, the result it produced, and the public receipt URL it minted. They do not independently certify anything the endpoint did not see.

## Links

- Zambo: https://zambo.dev
- AER-1 receipt spec: https://zambo.dev/aer-1/

## Guides

- [Execution Receipts for AI Agent Frameworks](https://zambo.dev/guides/framework-agent-execution-receipts/)
- [What Is an AI Agent Execution Receipt?](https://zambo.dev/guides/ai-agent-execution-receipt/)

## Local AER-1 receipts (no network needed)

The package also mints AER-1 execution receipts locally, with no API calls:

```python
from openai_agents_zambo import mint_receipt, verify_receipt

receipt = mint_receipt("my_tool", {"query": "hello"}, {"answer": "hi"}, ms=42)
assert verify_receipt(receipt)  # recomputes the SHA-256 locally
```

Local receipts follow the AER-1 core members (`id`, `created_at`, `tool`, `provenance_class`, `canonical_bytes`, `output_hash`) and use the provenance class `EXECUTED BY OPENAI-AGENTS-ZAMBO`, naming this package as the recording system. They pass the same hash-recomputation check as any AER-1 receipt.

## Where these receipts run live: Zambo

openai-agents-zambo mints a verifiable AER-1 receipt for every OpenAI Agents SDK tool event, and it has been downloaded 7,804 times on PyPI. The live home of those receipts is Zambo, the verifiable work layer for AI. Connect any AI to the live endpoint at https://zambo.dev/mcp or add Zambo to your AI in one step at https://zambo.dev/add/

Free tier: 20 calls + 1 wrap-up free every day; picking up in another AI is always free. The Day Pass is $0.99 for 24 hours, unlimited.

Install:

    pip install openai-agents-zambo
