Metadata-Version: 2.4
Name: openai-agents-zambo
Version: 0.1.0
Summary: Zambo's 100+ tools for the OpenAI Agents SDK, with a verifiable receipt on every call.
Author-email: Zambo <brennanzambo@zambo.dev>
License: MIT
Project-URL: Homepage, https://zambo.dev
Keywords: openai,agents,ai-agents,zambo,mcp,receipts,verification
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

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.

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