Agent Evidence Graph

Verify agent releases from runtime evidence, not declarations.

Comment

This agent claims to be read-only and canonical-only. Its real v1.3 run writes metadata and queries a deprecated revenue table.

Agent Evidence Graph verifies agent releases from runtime evidence, not declarations. It compares what a specific agent version promised with what it actually did, uses DataHub to explain why the difference matters, and routes risky releases through a human-approved governance action.

Release decision

  • Status: NEEDS_REVIEW
  • Detected drift: 2 deterministic HIGH findings
  • Governed impact: 1 active production reporting path implicated
  • Governance action: 2 of 2 DataHub writebacks verified by read-after-write

The primary user is an AI platform governance lead or agent release approver. Their job is to decide whether a new version still respects its approved tools, permissions, and data boundaries without manually reading every runtime log.

Inspiration

Across academic work on trustworthy AI and industrial work with data systems, we kept seeing the same gap: teams document what an agent is intended to do, but production decisions depend on what that exact version actually did.

An agent registry can say “read-only” or “canonical data only.” It cannot prove that a run followed those promises. Ordinary traces show calls, but they do not know that a dataset is deprecated, which asset replaces it, who owns it, or what production report depends on it.

Our core idea is therefore larger than a single checker: make declared-versus-observed conformance a first-class, testable, governed release object. Runtime traces prove what happened; DataHub explains why it matters.

What it does

  1. Loads the governed claim for one exact agent version.
  2. Captures successful and failed tool calls as hash-linked runtime evidence.
  3. Resolves dataset status, replacement metadata, ownership, and lineage through DataHub.
  4. Compares declared and observed tool and dataset sets with deterministic rules.
  5. Returns NEEDS_REVIEW, VERIFIED, or UNVERIFIED with evidence references.
  6. After explicit human approval, writes remediation metadata to DataHub and verifies it by readback.

Missing current-version runtime evidence becomes UNVERIFIED, never SAFE.

Live demo

The demo follows one Revenue Analyst Agent across two versions.

v1.2 baseline

  • Uses the governed DataHub context and canonical_revenue.
  • Produces an 8-event real trace.
  • Emits no HIGH finding.

v1.3 regression

  • Still declares read-only, canonical-only behavior.
  • Executes the undeclared datahub.add_tags capability.
  • Reads deprecated legacy_revenue instead of the governed replacement.
  • Produces a 10-event real trace and exactly two HIGH findings.

Deprecation alone remains MEDIUM. It escalates to HIGH because canonical_revenue is the governed replacement and actively feeds weekly_revenue_report. This is a governed production-path deviation, not a generic “blast radius” claim.

The reviewer then approves one release-bound immutable approval object. The service adds NeedsReview to the v1.3 compatibility identity and creates a linked audit Document. Both operations are immediately re-read before the approval becomes APPLIED. The approval ID is a lookup key; payload binding, allowlists, and human authorization are the controls.

Why DataHub is essential

DataHub is the context graph and governed action surface, not a decorative catalog page.

  • 5 live DataHub dataset entities with schema, descriptions, ownership, tags, native deprecation, and replacement metadata.
  • 3 live lineage edges connecting orders and refunds to canonical revenue and the weekly report.
  • Official Agent Context Kit 1.6.0.17 calls inside both real runs: search, get_entities, and get_lineage.
  • A separately labeled SDK entities.update call for the approved runtime mutation.
  • Human-approved SDK writeback of a tag and native audit Document, followed by read-after-write verification.

The current OSS/SDK combination does not expose the gated native Agent Registry helpers. We therefore use clearly labeled versioned DataFlow entities as a compatibility identity mapping and do not claim native Agent Registry support.

Safety by design

  • Tool selection is scripted in this release; risk adjudication is deterministic.
  • An LLM may later select read tools or explain normalized evidence, but it must not assign severity or approve its own remediation.
  • Runtime mutation and governance writeback use two independent approval gates.
  • Mutations are disabled by default, and Judge Replay contains no mutation controls.
  • Missing or unavailable evidence stays unknown instead of silently becoming safe.
  • Trace hashes protect recorded-event integrity; side-channel completeness is not claimed.

Evidence and validation

  • v1.2 run: run-revenue-analyst-1.2-65883e4d49fe
  • v1.3 run: run-revenue-analyst-1.3-74cc49489dc3
  • Governed writeback: approval-f57398669ba9bcf5
  • 49 tests passed; Ruff and strict mypy passed across 46 source files.
  • 81.57% branch-aware core coverage.
  • Zero unsupported public claims in the fixed evaluation suite.

In eight deterministic prototype cases, a claim-only baseline matches the expected status in 1/8 cases, while the evidence-aware rules match 8/8. Three cases intentionally return UNVERIFIED. This is a regression suite, not a production benchmark.

The full release gate is reproducible with:

uv run agent-evidence verify --require-real --require-eligible-integration

How we built it

Python and Pydantic normalize claims, runtime events, DataHub evidence, findings, answers, and approvals. A shared tool proxy writes hash-linked JSONL events. The resolver joins those events to DataHub metadata and lineage. Deterministic detectors create findings, and Streamlit renders the same tested service layer in a mutation-disabled judge replay.

Technologies include Python 3.11, DataHub Core/SDK/CLI, Agent Context Kit, DuckDB, Streamlit, Pydantic, Typer, pytest, Ruff, mypy, uv, and Docker.

Challenges and lessons

The hardest part was keeping proof boundaries honest. Connection is not use. A trace URN is not governance context. A UI checkbox is not an authorization boundary. An old-version trace cannot certify a new release.

We learned that trustworthy agent governance is not about adding autonomy everywhere. Probabilistic intelligence can help choose tools and explain results; severity, approval, and release decisions need explicit, auditable controls.

Team

Tianyi designed and implemented the verification workflow, real DataHub and Agent Context Kit integrations, deterministic detectors, lineage-aware escalation, approval/writeback verification, tests, report, Judge Replay, and demo.

Claudia shaped the product vision and reviewer journey, narrowed broad “agent trust” into version-level release decisions, and translated governance principles into trust states, approval boundaries, detector requirements, UI states, and acceptance criteria.

Links

Data disclosure

Finance rows and the eight evaluation cases are deterministic synthetic demo data. The listed DataHub reads, writes, lineage, runtime traces, and governance readbacks are real local DataHub operations. The narration is disclosed AI-generated neural speech; no music is used.

What’s next

The durable direction is a continuous conformance gate for every agent version: assign findings to owners, define remediation contracts, re-run after fixes or approved exceptions, and eventually support evidence-based agent selection and routing. Near-term engineering work includes signed trace transport, provider-backed read-tool selection with the deterministic policy layer retained, additional high-value detectors, and a native Agent Registry adapter where supported.

Built With

  • agent-context-kit
  • data-governance
  • data-lineage
  • datahub
  • docker
  • duckdb
  • langchain
  • pydantic
  • pytest
  • python
  • streamlit
Share this project:

Updates