[Proposal] Execution provenance exporter for compliance-grade audit trails

[Ratnaditya-J]

Problem

ADK's telemetry module (telemetry/tracing.py) emits OpenTelemetry spans covering agent execution, tool calls, and LLM interactions. This is excellent for debugging and observability.

However, enterprises deploying ADK agents in regulated environments (financial services, healthcare, legal, government) need more than observability -- they need provenance: tamper-evident, queryable records that prove what an agent did, with what data, under what authorization, and why. Current OTel spans are mutable, lack cryptographic integrity, and don't capture data lineage or authorization context.

Regulations driving this:

• EU AI Act (Article 6, high-risk provisions effective August 2, 2026): requires documentation of AI decision-making processes and data lineage
• FINRA 2026 Regulatory Oversight Report: mandates audit trails for AI agent actions in financial services
• HIPAA Security Rule update (January 2025): requires automated audit logs for AI systems handling PHI
• CMMC/DFARS: traceability requirements for defense contractor AI deployments

Without a provenance-grade audit trail, ADK agents can't be deployed in these environments regardless of how good the agent logic is.

What's missing vs. what exists

Execution traces -- ADK today: OTel spans via tracing.py. What's needed: tamper-evident execution records with cryptographic integrity.

Data lineage -- ADK today: not tracked. What's needed: which data sources were accessed, transformed, or output by each agent action.

Authorization context -- ADK today: not captured in spans. What's needed: who/what authorized each action, pulled from session state.

Integrity verification -- ADK today: none. What's needed: cryptographic hash chains linking spans so records can't be retroactively modified.

Audit export -- ADK today: sqlite_span_exporter.py (debug-oriented). What's needed: compliance-ready formats (JSON Lines, SIEM-compatible) that enterprise security teams can ingest.

Retention guarantees -- ADK today: in-memory or SQLite debug store. What's needed: append-only, immutable storage suitable for regulatory retention requirements.

Proposed approach

A ProvenanceExporter that extends ADK's existing telemetry infrastructure rather than replacing it. This hooks into the same OTel pipeline that tracing.py and sqlite_span_exporter.py already use.

from google.adk.telemetry import ProvenanceExporter
from google.adk.runners import Runner

# Provenance exporter sits alongside existing telemetry
exporter = ProvenanceExporter(
    sink="jsonl",                     # or "otlp", "bigquery", "custom"
    hash_chain=True,                  # cryptographic linking between events
    capture_data_lineage=True,        # track data source access/transform/output
    authorization_context_key="auth", # pull auth context from session state
)

runner = Runner(
    agent=root_agent,
    app_name="regulated_app",
    telemetry_exporters=[exporter],   # uses existing telemetry pipeline
)

What it captures (per agent action)

{
  "trace_id": "abc123",
  "span_id": "def456",
  "parent_span_id": "ghi789",
  "timestamp": "2026-03-31T12:00:00Z",
  "agent_id": "claims_processor",
  "action": "tool_call",
  "tool_name": "postgres-execute-sql",
  "tool_args_hash": "sha256:...",
  "data_sources_accessed": ["patient_records.claims"],
  "data_sources_modified": [],
  "authorization": {"user": "agent_service_account", "scope": "read:claims"},
  "result_hash": "sha256:...",
  "previous_hash": "sha256:...",
  "signature": "ed25519:..."
}

Integration points in ADK's architecture

This is achievable through ADK's existing extension points:

1. BasePlugin.before_tool_callback / after_tool_callback: Capture tool invocation provenance (what was called, with what args, what returned)
2. BasePlugin.before_agent_callback / after_agent_callback: Capture delegation chains (which agent delegated to which sub-agent)
3. telemetry/tracing.py: Existing OTel span pipeline -- provenance records attach as span attributes or export via a parallel exporter
4. events/: Event system already structures agent lifecycle -- provenance enriches these events with integrity metadata
5. sessions/: Session state provides authorization context that provenance records reference

The key design decision: this should be a telemetry exporter (like sqlite_span_exporter.py), not a plugin. Plugins have short-circuit semantics where one plugin returning non-None bypasses subsequent plugins. Provenance recording must never be bypassed -- it should be in the telemetry pipeline, which always runs.

This was actually identified as an open problem in the governance callback discussions (#4764): "the short-circuit semantics mean governance callbacks can be bypassed by earlier plugins." Moving audit to the telemetry layer avoids this entirely.

Why this is different from previous governance proposals

To be direct: I've read #4543, #4764, #4517, and #4910. Those proposals bundled policy enforcement + threat detection + access control + audit trails into monolithic governance plugins. This proposal is deliberately narrow:

• Not policy enforcement (that's a separate concern, and ADK's safety-plugins and Model Armor handle content safety)
• Not threat detection (separate concern)
• Not access control (separate concern)
• Only provenance: tamper-evident records of what agents actually did

This is the audit trail layer that sits underneath any governance framework. Whether you use Google's Model Armor, Microsoft's agent-governance-toolkit, or custom policies -- you still need provenance records of what happened. This is infrastructure, not a framework.

Prior work in this repo

I have an open PR fixing MCP session disconnect handling (#4906) and have been working with the genai-toolbox team on a security audit of database tool permissions (googleapis/genai-toolbox#2716, assigned to @averikitsch). This proposal comes from the same perspective: making ADK safer for production deployments in regulated environments.

What I'm proposing to build

I'm happy to submit a reference implementation as a PR. Specifically:

1. A ProvenanceExporter class in telemetry/ that extends the existing OTel exporter pattern
2. Hash-chain linking between provenance records for tamper evidence
3. Data lineage capture for tool calls (which data sources accessed/modified)
4. JSON Lines export format (SIEM-compatible, matches what enterprise security teams already ingest)
5. Unit tests covering the provenance chain integrity guarantees

This is open-source work. I maintain SpineFrame, a provenance runtime for AI agents, and would build the ADK exporter to be compatible with SpineFrame's format while being fully standalone -- no external dependencies required.

Open questions for the ADK team

1. Is telemetry/ the right home for this, or would a dedicated provenance/ module be preferred?
2. Should provenance records use the existing _experimental_semconv.py semantic conventions, or define new ones?
3. Is there interest in a BigQuery provenance sink (given Vertex AI integration)?
4. How does this relate to the AgentRegistry work (feat: Support AgentRegistry association landed 4 days ago)?

Happy to discuss and iterate. This is meant as a starting point, not a finished design.