Metadata-Version: 2.4
Name: openai-agents-zambo
Version: 0.1.4
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: 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
Dynamic: license-file

# openai-agents-zambo

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 100+ tools, and mint a verifiable execution receipt for every tool event.

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

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

## 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 100+ 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)
```

## 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.
