RFC: Audit receipts for ADK agent tool execution

[tomjwxf]

Problem

Google ADK agents execute tool calls in production environments, but there is no built-in mechanism to produce cryptographic evidence that a specific tool call occurred, what policy governed it, and that the audit record hasn't been tampered with. As ADK agents move into enterprise deployments, compliance and security teams need verifiable proof of agent behavior.

Proposal

Add an optional receipt-signing middleware to ADK's tool execution pipeline. When enabled, every tool call would emit an Ed25519-signed receipt:

from google.adk import Agent
from protect_mcp import ReceiptMiddleware

agent = Agent(
    model="gemini-2.0-flash",
    tools=[search_tool, database_tool],
    middleware=[ReceiptMiddleware(key_path="./keys/agent.json")]
)

Each receipt captures: tool name, decision (allow/deny), input/output digests, policy hash, timestamp, and an Ed25519 signature. Receipts can be verified offline without access to the agent runtime.

Reference

This pattern is standardized in an IETF Internet-Draft and implemented in protect-mcp (MIT, npm v0.5.3). Active integrations exist with Mission Control, Cedar for Agents, Microsoft AGT, and LlamaIndex.

Happy to discuss integration architecture and contribute.

[jagmarques]

We built something similar for the Python side. The core idea is the same - Ed25519 signed receipts per tool call - but we also chain them (each receipt includes the hash of the previous one) so you get tamper-evidence across the full session, not just per-call integrity.

The tricky part is deciding what goes into the canonical form before signing. We settled on: tool name, input/output content hashes, policy ID, timestamp, and the previous receipt hash. Keeping raw I/O out of the signed blob avoids accidentally signing PII into an immutable record.

Already works as ADK middleware via pip install asqav. The receipt chain is exportable as JSONL for offline verification.

[tomjwxf]

@jagmarques interesting that you arrived at the same pattern independently. Chaining via previous receipt hash is exactly what the IETF draft specifies, and keeping raw I/O out of the signed blob is the right privacy call (we use tool_input_hash for the same reason, SHA-256 of the raw input bytes).

Good point on Ed25519 and NIST deprecation. The IETF draft's signature envelope uses a signature.alg field specifically to support algorithm negotiation. Today it is "EdDSA" (Ed25519), but the same envelope works with ML-DSA-65 or any other algorithm. The verifier already dispatches on that field. Supporting both with negotiation (as you did in asqav) is the right approach for enterprise customers with post-quantum requirements.

Would be worth comparing the canonical form choices. We use JCS (RFC 8785) for deterministic serialization before signing. If asqav uses the same canonicalization, the two systems produce interoperable receipts. We just verified this with another implementation (Agent Passport System) - three independent receipts all verified against the same IETF draft verifier at exit code 0.

What does the asqav middleware hook look like for ADK? If it follows the same pattern as protect-mcp (PreToolUse/PostToolUse hooks), there might be a common middleware interface worth proposing to the ADK team.

[tomjwxf]

Built it. protect-mcp-adk is a working ADK plugin for Ed25519 receipt signing.

Install

```bash
pip install protect-mcp-adk
```

Usage

```python
from google.adk import Agent
from google.adk.tools import FunctionTool
from protect_mcp_adk import ReceiptPlugin, ReceiptSigner

signer = ReceiptSigner.generate()

agent = Agent(
model="gemini-2.0-flash",
tools=[FunctionTool(my_tool)],
plugins=[ReceiptPlugin(signer, auto_export_path="receipts.jsonl")],
)
```

Every tool call produces a signed receipt in the IETF draft envelope format:

```json
{
"payload": {
"type": "protectmcp:decision",
"spec": "draft-farley-acta-signed-receipts-01",
"tool_name": "search",
"tool_input_hash": "sha256:ff7e27...",
"decision": "allow",
"output_hash": "sha256:a3f8c9...",
"session_id": "sess_a1b2c3d4e5f6",
"sequence": 1,
"previousReceiptHash": null,
"agent_name": "research_agent"
},
"signature": { "alg": "EdDSA", "kid": "sb:adk:320d7372f83c", "sig": "f4bf13..." }
}
```

How it works

• Hooks into ADK's `after_tool_callback` via the BasePlugin interface
• Signs `JCS(payload)` with Ed25519 (RFC 8032 + RFC 8785)
• Chain-links receipts via `previousReceiptHash` (tamper-evident ordering)
• Privacy-preserving: tool inputs/outputs are SHA-256 hashed, not stored raw
• Errors signed via `on_tool_error_callback`
• Auto-exports to JSONL as receipts are produced

Cross-verified

Python-signed receipts verify with the same Node.js verifier used by three other independent implementations (protect-mcp TypeScript, Agent Passport System, asqav):

```bash
npx @veritasacta/verify@0.2.5 receipts.jsonl --key

Exit 0 = valid, 1 = invalid (tampered), 2 = error (malformed)

```

On post-quantum (@jagmarques)

The receipt envelope's `signature.alg` field supports algorithm negotiation. Today it is `"EdDSA"` (Ed25519). The same envelope works with ML-DSA-65 by changing the alg field. The plugin accepts a signer interface, so swapping the crypto backend is a configuration change, not a rewrite. Planning ML-DSA-65 as an opt-in option once `@noble/post-quantum` or the Python equivalent is audited.

Source: packages/protect-mcp-adk

[aeoess]

@tomjwxf @jagmarques — the three-implementation convergence on Ed25519 + JCS + hash-linked chains is now a pattern, not a coincidence. APS, protect-mcp, and asqav arrived at the same canonical form independently. That's the strongest validation a receipt format can get.

APS has an ADK governance hook that adds the layer above tool-level receipts: the delegation chain that proves authorization, not just execution.

# pip install agent-passport-system
from agent_passport_system import (
    generate_key_pair, create_passport, create_delegation,
    sign_action_receipt
)

# The receipt proves the tool was called.
# The delegation proves the agent was authorized to call it.
# The passport traces authority to a human principal.
receipt = sign_action_receipt(
    agent_id=agent.passport.agent_id,
    delegation_id=delegation.delegation_id,
    private_key=keys.private_key,
    action_type="search",
    scope="tools:search",
    status="success",
    summary="Tool executed successfully"
)
# receipt.signature: Ed25519 over JCS-canonicalized payload
# receipt.previousReceiptHash: chain-linked
# receipt.delegationId: traces to delegation -> passport -> principal

The composition with protect-mcp-adk:

Layer	What it proves	Who signs
protect-mcp-adk	Tool C was called with input hash X, output hash Y	Agent's Ed25519 key
APS delegation	Agent B was authorized scope tools:search with $500 spend limit	Principal's Ed25519 key
APS gateway	The evaluation was permit/deny at timestamp T with policy hash P	Gateway's Ed25519 key

Three signatures, three parties, one audit trail. A verifier consuming ADK execution logs gets: tool-level proof (protect-mcp), authorization proof (APS delegation), and enforcement proof (APS gateway). Each independently verifiable.

On the gateway-reporter pipeline we just shipped: every adapter (including ADK) can optionally send receipts to the hosted gateway for dashboards and audit trails. Fire-and-forget, never blocks on gateway failure:

from agent_passport_system import GatewayReporterConfig

config = GatewayReporterConfig(
    gateway_url="https://gateway.aeoess.com",
    api_key="aps_live_..."
)
# Receipts flow to gateway for real-time dashboards, audit trail, session persistence

The canonical form alignment means a unified verifier can validate receipts from all three systems without switching parsers. If someone builds a verify-receipt CLI that accepts any Ed25519+JCS+chain-linked receipt, all three implementations should pass at exit code 0.

SDK: pip install agent-passport-system (v0.9.0, Python) or npm install agent-passport-system (v1.36.2, TypeScript, 2,497 tests). ADK governance hook at src/adapters/governance-hook.ts.

[tomjwxf]

@aeoess the three-layer composition is clean: protect-mcp-adk (tool execution proof), APS delegation (authorization proof), APS gateway (enforcement proof). Three signatures, three parties, one envelope format.

The key property: each layer is independently verifiable. An auditor consuming ADK execution logs can verify just the tool receipt (protect-mcp), or the full chain (tool + delegation + gateway). The envelope is the same either way. The extensions block handles the layer-specific semantics without breaking the common verifier.

Cross-system verification is now confirmed with 4 independent implementations across Python and TypeScript, all verified at exit 0 by the same tool. That is the interop proof the IETF draft needed.

For ADK specifically: protect-mcp-adk handles the tool boundary. APS handles the authorization boundary. Both are pip-installable, both are ADK BasePlugin compatible. A user who needs both layers installs both packages and registers both plugins. No coordination required between them at runtime - the receipts compose at verification time.

[klateefa]

@tomjwxf Thanks for the update. The request is currently being reviewed by our team, and I will let you know if anything further is needed. Thank you for understanding.

[tomjwxf]

Quick update: the source repository for protect-mcp-adk is now public:

Source: github.com/ScopeBlind/protect-mcp-adk
PyPI: pypi.org/project/protect-mcp-adk/
Discussion: #5180 (Show-and-Tell)

Addresses the feedback from the docs PR about having a public source repository. Happy to support the review in any way that's helpful.