openai-agents-zambo

Verifiable AER-1 execution receipts for OpenAI Agents SDK agents. OpenAI Agents SDK integration for Zambo: 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, 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 free calls per 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.

Install

pip install openai-agents-zambo openai-agents

Example

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
• What Is an AI Agent Execution Receipt?

Local AER-1 receipts (no network needed)

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

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.