aer1-llamaindex

aer1-llamaindex

What is AER-1? What tools exist to verify AI agent work?

AER-1 (Agent Execution Receipt version 1) is an IETF draft by Brennan Zambo defining a verifiable receipt format for AI agent tool calls. Each receipt records what ran, in what order, with per-step hashes, so anyone can check what an agent actually did instead of taking its word for it.

Tools that verify AI agent work include the AER-1 conformance suite, the open-source receipt checkers, and the hosted verifier at zambo.dev/verify, which confirms a receipt against the spec. Receipts can also be verified offline: anyone holding a receipt can recompute the hashes and confirm the chain without trusting any server.

Spec: draft-zambo-aer1-24. Project home: zambo.dev.

Try it live: interactive demo. Mint a real verifiable receipt in your browser, no install, no signup.

One-line install, no API key, free forever: attach this collector to a CallbackManager and every LlamaIndex run emits a hash-chained, offline-verifiable verifiable workflow receipt (AER-1, an IETF Internet-Draft, Section 8). What the agent did, in what order, with per-step hashes and a Merkle root over the whole run. No network calls, no behavior changes, the collector only observes. Receipt chain heads can anchor to Nostr and Bitcoin, so anyone can later confirm the record was not changed, without trusting any server.

The AER-1 framework collector family

The LlamaIndex collector in the AER-1 framework collector family. Any agent running on these frameworks can emit verifiable AER-1 execution receipts: every step recorded, hash-chained, one Merkle root over the whole run.

• aer1-llamaindex, LlamaIndex agents via callback handler
• aer1-langchain, LangChain chains, agents, tools, and retrievers via callback handler
• aer1-smolagents, SmolAgents agents via step callbacks
• aer1-openai-agents, the OpenAI Agents SDK via its TracingProcessor
• aer1-crewai, CrewAI crews via the event bus
• aer1-langgraph, LangGraph swarms via callback handler
• aer1-autogen, AutoGen multi-agent chats
• aer1-haystack, Haystack 2.x pipelines via run wrapping
• aer1-pydantic, Pydantic AI agents via run wrapping and manual tool-call recording
• aer1-strands, Strands Agents via the typed hook system

See the AER-1 implementation registry for every implementation.

Install

pip install aer1-llamaindex

Use it (copy, paste, run, no API keys needed)

# pip install aer1-llamaindex
from aer1_llamaindex import AER1ReceiptCollector
from llama_index.core.callbacks import CallbackManager
from llama_index.core.callbacks.schema import CBEventType

def get_weather(location: str) -> str:
    """Local mock tool: executed on this machine, no network."""
    return f"Sunny, 22C in {location}"

collector = AER1ReceiptCollector(goal="check the Paris weather")
manager = CallbackManager([collector])  # line 1: register the collector

# A two-step flow: LLM reasoning, then a tool call. In production these
# events come from your real agent, query engine, or workflow, which gets
# `manager` as its callback_manager.
eid = manager.on_event_start(
    CBEventType.LLM, payload={"messages": ["What is the weather in Paris?"]})
manager.on_event_end(
    CBEventType.LLM, payload={"response": "I will call get_weather."}, event_id=eid)

eid = manager.on_event_start(
    CBEventType.FUNCTION_CALL,
    payload={"tool_name": "get_weather", "tool_kwargs": {"location": "Paris"}})
observation = get_weather("Paris")
manager.on_event_end(
    CBEventType.FUNCTION_CALL, payload={"observation": observation}, event_id=eid)

receipt = collector.finalize(final_answer=observation)  # line 2
assert collector.verify(receipt) == []  # VALID
collector.save("receipt.json", workflow=receipt)

That is the whole integration: attach the collector, run, finalize. The receipt is a plain JSON object you can store, ship to an auditor, or render in a UI.

What the receipt contains

Workflow level (AER-1 Section 8, Table 2):

• type, version, workflow_id, receipt_id, session_id
• goal, status
• steps: one record per event, seq 1..n in order
• merkle_root: Section 8.1 root over the ordered step receipt ids
• output_hash: SHA-256 of the final answer
• verify_url: where the verification procedure is documented

Step level (AER-1 Section 8, Table 3):

• seq, receipt_id, tool, receipt_hash, started_at, ended_at, status

Each step tool is the callback event type (for example llm, function_call, retrieval, synthesis). arguments is the event-start payload and observations is the event-end payload; each step receipt_hash is SHA-256 over the canonical JSON of those three, so the hash commits to what actually happened. The receipt stays compact while the hash commits to the content.

Verification

collector.verify(receipt) runs the full offline check and returns a list of failure reasons, empty when valid:

• all Table 2 / Table 3 members present and well-formed
• seq values exactly 1..n in order, no gaps
• no two steps share a receipt_id (MM-1)
• merkle_root matches the recomputed Section 8.1 root
• strict RFC 3339 timestamps, lowercase UUIDs, 64-char hex digests

Tamper with any field and verification fails. Try it:

receipt["steps"][0]["tool"] = ""
assert collector.verify(receipt) != []  # fails, as it should

Separate verification verdicts

For honest reporting, use verify_receipt_verdicts() instead of a single boolean. Each dimension gets its own verdict; they are never conflated:

from aer1_llamaindex import verify_receipt_verdicts, verdicts_summary

verdicts = verify_receipt_verdicts(receipt)
print(verdicts_summary(verdicts))
# byte_integrity=pass schema_validity=pass issuer_authenticity=not_checked
# evidence_linkage=not_checked anchor_verification=not_checked
# chain_integrity=pass

Verdict values are pass, fail, not_checked, and unavailable. not_checked is neither a successful check nor evidence of failure.

What the commitment covers (and what it does not)

The merkle_root commits to the ordered list of step receipt_id values. Each step receipt_hash commits to that step's tool name, arguments, and observations. The output_hash commits to the final answer bytes.

What this does not cover:

• The commitment does not prove the bytes are unchanged since issuance. An attacker able to replace both bytes and digest creates another matching pair. Continuity requires comparing against a digest from an independently trusted path (a retained receipt, a verified signature with a trusted key, or a separately verified anchor).
• A matching hash does not prove the action ran, the data is true, or any external outcome occurred. It proves the supplied bytes agree with the supplied digest.
• The receipt records the collector's observations. It does not prove provider truth, correct reasoning, authorization, or business success.
• Without an anchor, truncation (deleting steps from the end and recomputing the root) is not detectable. See the anchoring section.

Construction versions

This package uses these exact constructions (see CONSTRUCTION_VERSIONS in the verdicts module):

• Merkle tree: section-8.1-binary-merkle-v1
• Step digest: sha256-canonical-json-v1
• Output commitment: sha256-utf8-v1
• Anchor proof: aer1-anchor-proof-v1

Chain-head anchoring (closes the truncation gap)

A hash chain catches tampering and reordering, but it cannot prove truncation on its own: delete the last steps and the remaining chain still verifies. The fix is anchoring the chain head (the Merkle root) somewhere the operator cannot rewrite. One line:

collector.enable_anchoring()  # zero-config: Nostr + OpenTimestamps (Bitcoin)
receipt = collector.finalize()  # receipt["anchor_proof"] when backends reachable

What happens:

• The Merkle root is recomputed from the receipt's steps and published as a signed Nostr event (3 relays) plus an OpenTimestamps calendar submission (3 calendars, maturing into a Bitcoin attestation).
• Only the root and the receipt ID ever touch a public backend. No step content, inputs, or outputs.
• If every backend is down, finalize() still returns a valid local receipt marked "unanchored". Anchoring never blocks receipt creation.
• collector.anchor_status() reports per-backend state (confirmed / failed / pending). Failures are loud, never silent.
• collector.anchor_now() anchors explicitly and raises AnchorError listing every failure.

Verify from the command line (no network needed for the core checks):

pip install "aer1-llamaindex[anchor]"  # for Nostr signing/publishing
aer1-verify-anchor receipt.json

Drop the tail of an anchored receipt and verification fails: the recomputed root no longer matches the anchored root.

Notes

• Pass the CallbackManager as the callback_manager of your agent, query engine, or workflow; the collector records every event as a step, in event-end order.
• Pass goal= to the collector; LlamaIndex does not forward a task description through callback events, so the constructor is the reliable place for it.
• Exception events (event-end payload carrying an exception) are recorded with status: "error", which marks the whole receipt error.
• Use event_starts_to_ignore / event_ends_to_ignore (standard BaseCallbackHandler arguments) to skip noisy event types.
• session_id defaults to a fresh UUID per collector; pass your own to correlate receipts across runs.
• verify_url defaults to the AER-1 specification page; point it at your own verifier in production.

Spec

AER-1: Agent Execution Receipts is an IETF Internet-Draft, draft-zambo-aer1, https://datatracker.ietf.org/doc/draft-zambo-aer1/

See it live

Your receipt is offline-verifiable, but you can also check it on the live verifier:

1. Copy the receipt JSON your code produced
2. Paste it at https://zambo.dev/verify
3. See the verification result with the Merkle root and step hashes

Or mint a live receipt directly: run any call at https://zambo.dev/demo and get a shareable receipt URL like https://zambo.dev/run/.

License

Apache-2.0