What each section produced
Investigation Evidence
Datahub context lineage
Pipelines page
Approved Context Source
Refund Resolution Agent Incident
Fresh Risk Context
Command Center page
Incidents page

Project Story

About the Project

Inspiration

AI agents are increasingly able to retrieve sensitive context and invoke tools that create real-world consequences. Data catalogs can show which policies, datasets, and tools an agent depends on—but visibility alone does not prevent an unsafe action when that context changes after deployment.

Aegis was inspired by this last-mile governance gap. A policy can lose approval, a feature pipeline can become stale, or lineage can break while the agent itself still appears healthy. I wanted DataHub metadata to do more than document those risks after the fact. I wanted it to become live evidence in the authorization decision itself.

Aegis is therefore built around one principle:

The model may propose an action, but it never authorizes one.

For a consequential tool call to execute, Aegis requires both an ALLOW decision based on fresh DataHub evidence and a valid capability bound to that exact call:

$$ \text{Execute} \iff (\text{Decision} = \text{ALLOW}) \land \text{ValidCapability}(\text{tool}, \text{arguments}, \text{run}) $$

Anything else—including missing lineage, stale metadata, unavailable DataHub, tampering, replay, REVIEW, or BLOCK—fails safely.

What Aegis Does

Aegis is a DataHub-native safety control plane for agentic systems. It catalogs agents, skills, context sources, and MCP tools in DataHub, then uses lineage and operational metadata as runtime governance evidence.

Immediately before a consequential tool call, Aegis:

Re-reads the relevant DataHub metadata instead of trusting cached context.
Evaluates an inspectable, deterministic safety control.
Produces an ALLOW, REVIEW, or BLOCK decision.
Issues a short-lived, single-use capability only for ALLOW.
Binds that capability to the exact tool, arguments, and agent run.
Records the outcome and writes significant incidents or attestations back to DataHub.

The project includes two executable LangGraph agents:

Refund Resolution proposes refunds and uses ApprovedContextSource to verify that high-value refunds rely on approved policy context.
Account Risk proposes account restrictions and uses FreshRiskContext to verify that risk evidence is within its freshness SLA.

The headline scenario follows an $8,500 refund. A draft, unapproved policy enters the agent’s active retrieval lineage. The model can still propose issue_refund, but Aegis detects the changed provenance, returns BLOCK, and prevents the executor from producing a receipt.

After the approved policy is restored and regression checks pass, the pipeline becomes trusted again without erasing the original incident history.

How I Built It

The backend is built with FastAPI, Pydantic, and SQLite. LangGraph orchestrates the live agents, while the OpenAI Responses API produces strict consequential tool proposals. The frontend uses React, TypeScript, Vite, React Router, and TanStack Query.

DataHub provides the governance graph and evidence layer:

Agent Registry models agents, versions, skills, ownership, and tool dependencies.
Lineage connects policies and features to retrieval systems and agents.
Structured Properties record approval status, hashes, and governance facts.
Operations provide freshness evidence.
Documents represent policies, controls, and successful run attestations.
Incidents capture blocked and review outcomes.
Actions provide authenticated change hints.
DataHub MCP gives agents read-only catalog discovery and context.

DataHub MCP results help the agent reason, but they never authorize execution. At the enforcement boundary, Aegis performs a fresh direct read from DataHub GMS. An Actions event can invalidate trust quickly, but cached events cannot produce an ALLOW.

For allowed actions, Aegis mints an HMAC-signed capability containing the run ID, tool name, canonical argument hash, expiration time, and a unique one-time identifier. Capability consumption and sandbox receipt creation occur atomically, preventing concurrent replay.

External business effects are deliberately sandboxed: the security boundary is real, but no actual refund or account restriction is performed.

I also created a deterministic seeded mode so the complete incident and remediation story can be evaluated without cloud credentials. Seeded facts are visibly labeled and are never permitted to authorize the live agents.

Challenges I Faced

The hardest challenge was maintaining an honest boundary between a compelling demonstration and a real enforcement system. A seeded interface can look operational even when it is not connected to live infrastructure, so Aegis explicitly identifies the provenance of every fact and rejects live execution in fixture mode.

Freshness was another important challenge. DataHub Actions are useful for low-latency notifications, but an event or cached projection may already be stale. The final design treats Actions only as invalidation hints and performs a direct metadata read at the last responsible moment.

Capability security also required careful handling. Model-generated JSON may represent the same number as either 1500 or 1500.0, so arguments must be normalized before hashing without weakening the binding for genuinely different values. Capabilities also needed expiration, signature validation, exact-argument matching, and atomic one-time consumption.

Integrating DataHub presented practical compatibility challenges as well. DataHub Core 1.7 supports the Agent Registry entity schemas used by Aegis, but its open-source frontend does not expose the same native Agent Registry pages available in DataHub Cloud. I designed the project so the underlying agent metadata, relationships, verification, and enforcement remain real while the local interface links to browsable context assets.

Finally, the product needed to explain a distributed security decision clearly. The Command Center and incident workspace were designed to show the complete causal chain:

The upstream context change
The affected lineage
The model’s proposed action
The deterministic control result
The absent executor receipt
The remediation
The regression result
The DataHub write-back

What I Learned

The biggest lesson was that metadata becomes far more valuable when it participates directly in a system’s control loop. Lineage is not only documentation—it can determine whether an action is safe. Operational timestamps are not only observability data—they can become freshness constraints. Catalog incidents and documents can also form an auditable feedback loop around agent execution.

I also learned that probabilistic reasoning and deterministic authorization should remain separate. Language models are excellent at interpreting context and proposing actions, but authorization benefits from small, explicit, testable controls with predictable failure behavior.

Aegis demonstrates a practical architecture for that separation: