DecisionGraph

Operational data agent: governed context in, approved action and durable memory out.

Comment

Open the 60-second judge demo

DecisionGraph is the permanent memory layer for AI agents, allowing them to perceive DataHub context, calculate operational actions, and safely pause at approval gates.

Try it now

Open the 60-second judge demo — then select Replay Live JSON to animate the verified DataHub 1.6 run. No credentials or installation are required.

Watch the 2:57 video · Inspect the public CI · Browse the examples

Inspiration

AI agents can do operational work, but without durable governed memory they can repeat stale actions or lose the evidence that made an action safe. Teams need to know which data shaped an action, what calculation ran, when approval occurred, and what must happen when the evidence changes.

DecisionGraph makes the data agent the hero: it uses DataHub context to calculate a reorder action, pauses at an explicit approval gate, writes the approved decision back as a native DataHub Document, and recalls it when evidence changes.

What it does

DecisionGraph demonstrates a closed operational loop:

The agent reads governed entities, schema fields, and lineage through the official DataHub MCP Server. DataHub's open-source Analytics Agent executes the governed reorder SQL and returns rows, chart output, quality, and conversation provenance. DecisionGraph stores the exact context snapshot, Analytics Agent result, and dataset URN dependencies. The recommendation remains pending until an operator performs the explicit approval action. Approval calls MCP save_document, relates the native DataHub Document to both source datasets, and confirms the returned Document exists by MCP read-back. An upstream evidence change identifies affected decisions and marks the old approval REVALIDATION_REQUIRED. Revalidation retrieves fresh context, reruns Analytics Agent, and creates a replacement linked through supersedes. The original decision and audit history remain intact. A side-by-side view highlights prior data, updated data, and the effect on every downstream routine.

The four-step agent loop

Calculate: DataHub's Analytics Agent executes the governed SQL and returns the operational recommendation with its rows and provenance. Gate: The recommendation pauses until an operator explicitly approves it. Write-back: Approval triggers MCP save_document to write a native DataHub Document related to the governed source datasets. Revalidate: If upstream governed evidence or lineage changes, the agent blocks reuse of the old approval and creates a replacement linked through supersedes.

The Unhappy Path (And Why It Matters)

Watch for this in the video: the approved three-row decision becomes stale after the DataHub evidence changes. DecisionGraph highlights the affected routines, refuses to treat the prior approval as current, recalculates four rows, and requires a newly approved replacement. That is the enterprise guardrail: an agent cannot silently continue acting on evidence that is no longer valid.

The verified run begins with three Northeast reorder candidates. After a controlled evidence update, Analytics Agent returns four rows, including SKU-DG-104. DecisionGraph highlights nine changes across five affected routines, requires new approval, preserves the original as SUPERSEDED, writes the replacement to DataHub, and verifies the Document exists by read-back.

How DataHub powers the agent

Perceive governed reality: MCP get_entities, list_schema_fields, and get_lineage provide entity, schema, and blast-radius context. Calculate an action: DataHub Analytics Agent executes the exact governed SQL and returns the operational rows and provenance. Act with a gate: MCP save_document creates a native DataHub record only after explicit approval. Remember and verify: MCP get_entities confirms the returned Document exists; stored URNs and snapshots preserve its evidence. React to change: lineage and stored dependencies identify affected decisions and force a fresh replacement revision. Share a reusable pattern: the Evidence-Bound Decision Governance DataHub Skill packages the lifecycle for other agents.

This directly fits Agents That Do Real Work: the agent perceives governed reality, calculates an operational reorder, pauses at a controlled action boundary, persists the result, and reacts when its evidence becomes stale.

How we built it

DecisionGraph is a FastAPI application with a responsive operations console and a local SQLite decision ledger.

Its DataHub foundation includes:

DataHub OSS 1.6 as the governed context graph official MCP get_entities, list_schema_fields, get_lineage, and save_document the open-source datahub-project/analytics-agent conversation and SSE APIs native DataHub Documents related to both governed datasets a reusable Evidence-Bound Decision Governance DataHub Skill the DataHub Agent Context Kit dependency and a version-aware Agent Registry compatibility adapter; the verified DataHub 1.6 environment reports sdk_unavailable, and no Agent Registry entities were created

Analytics Agent output is accepted only when the exact governed SQL completes and every row satisfies the expected schema and reorder arithmetic. Projection retries preserve a successfully returned Document URN, and repeated sync of an already synchronized decision does not write again.

Zero-Config Judge Sandbox

The public GitHub Pages experience is a purpose-built, credential-free sandbox so judges can test the complete lifecycle immediately—no API keys, Docker startup, or private DataHub credentials required. Its deterministic fixture makes every run reproducible, while the interface clearly labels sandbox mode and keeps external projection disabled.

The same page includes a clearly labeled recorded integration snapshot. Replay Live JSON refetches the published proof artifact and animates captured MCP retrieval, Analytics Agent SQL, revalidation impact, Document projection, and read-back. It is recorded evidence; it does not make live MCP calls from GitHub Pages.

The FastAPI backend is a trusted, single-user hackathon service. Approval identity is not authenticated, so a credentialed backend must not be exposed directly to the Internet. Production use requires authentication, authorization, signed approval identities, durable storage, and secret management.

Challenges

The hardest design problem was preserving the boundary between recommendation and action. Approval changes external state, so the workflow needed explicit lifecycle state, idempotent projection, and retry semantics.

Revalidation was the second challenge. Replaying an old answer could look successful while using stale evidence, so DecisionGraph retrieves fresh context and creates a replacement instead of rewriting history.

Running DataHub, MCP, Analytics Agent, and a local model together also required careful resource management. The SQL result is authoritative even when a smaller model produces illustrative chart values.

Accomplishments

Completed a real MCP-backed read, calculate, gate, write, and revalidate loop Executed the operational calculation with DataHub Analytics Agent Wrote approved native Documents to DataHub and confirmed read-back Preserved prior and updated evidence with highlighted routine impact Added a one-command Docker Compose judge quickstart Added CI-gated GitHub Pages deployment and 17 public automated tests Published a reusable Decision Governance Skill and Agent Context Kit documentation contribution

Open-source contributions

Decision Governance Skill — ready for review Agent Context Kit documentation — ready for review

Both contributions are open, mergeable, and ready for DataHub maintainer review.

What we learned

Context is most valuable when it remains attached to the action it informed. DataHub's graph and MCP interface let an agent begin with governed knowledge, while a write-back artifact lets the next person or agent inherit the decision rather than reconstruct it.

Revalidation is not merely rerunning code. It requires fresh context, preserved history, highlighted differences, downstream impact analysis, and a new approval boundary.

What's next

Subscribe to real DataHub assertions and incident signals Add policy-as-code approval rules, authentication, and signed identities Expand into quality, access, cost, compliance, and model-risk decisions Support multi-agent review and conflict resolution Generalize Analytics Agent calculations to additional operational decisions

Built With

Share this project:

Updates