Skip to content

Agent-Aegis

The governance layer for AI agents. One API, 12 frameworks, every governance primitive.

12Frameworks
10+Primitives
85+Injection Patterns
<1msPer Check
Try in Browser Quick Start GitHub

Aegis Demo

What is Aegis

Every AI agent framework reinvents the same governance primitives — and each one does it slightly differently. Aegis is the abstraction layer that unifies them. Redis is to in-memory data structures what Aegis is to agent governance: one library, every primitive, every framework, one API.

Layer What it does Examples
1. Primitives A universal contract for every tool call Action, ActionClaim, Policy, Result, DelegationChain, AuditEvent
2. Adapters Auto-instrument any framework through its own hooks LangChain callbacks, CrewAI BeforeToolCallHook, OpenAI Agents tracing, Google ADK BasePlugin, MCP transport, DSPy modules, httpx middleware, Playwright context
3. Governance Declarative primitives you compose into policy Injection / PII / leak / toxicity guardrails, RBAC, rate limit, cost budget, drift, anomaly, trust delegation, justification gap, selection audit, Merkle audit
4. Lifecycle One runtime, every stage of agent ops Scan → Instrument → Policy CI/CD → Runtime → Proxy → Audit 
import aegis
aegis.auto_instrument()    # 12 frameworks governed. No other code changes.

You don't write a LangChain guardrail and a CrewAI guardrail and an OpenAI guardrail — you write one Policy and every framework inherits it.

Primitives

The contract every adapter maps into. Framework-agnostic by design.

Primitive Purpose Module
Action Unified representation of any tool / LLM / HTTP / MCP call across all frameworks aegis.core.action
ActionClaim Tripartite structure — Declared (agent-authored) / Assessed (Aegis-computed) / Chain (delegation) aegis.core.action_claim
Policy Declarative YAML rules: match → risk → approval (auto / approve / block) aegis.core.policy
ClaimPolicy Policy layer that evaluates 6-dimensional impact vectors, not just tool names aegis.core.claim_policy
Guardrails Deterministic regex checks for injection, PII, prompt leak, toxicity — 2.65ms cold / <1µs warm aegis.guardrails
DelegationChain Multi-agent hand-off tracking with monotone trust constraint aegis.core.agent_identity
AuditEvent Tamper-evident append-only log, Merkle-chained, SQLite + JSONL + webhook sinks aegis.core.merkle_audit
SelectionAudit Audits what an agent excludes, not just what it picks — detects cosmetic alignment aegis.core.selection_audit
JustificationGap 6D asymmetric scoring: agents declare impact, Aegis independently assesses, gap triggers escalation aegis.core.justification_gap
CryptoAuditChain Ed25519-signed chain for long-term compliance evidence aegis.core.crypto_audit

Every governance feature in Aegis is a composition of these primitives. Read the Concepts guide to see how they fit together.

Frameworks

One API. 12 agent frameworks + 3 protocol-level adapters. auto_instrument() detects what's installed and patches only those — no hard dependencies.

Framework Hook
LangChain BaseChatModel.invoke/ainvoke, BaseTool.invoke/ainvoke
CrewAI Crew.kickoff/kickoff_async, global BeforeToolCallHook
OpenAI Agents SDK Runner.run, Runner.run_sync
OpenAI API Completions.create (chat & completions)
Anthropic API Messages.create
LiteLLM completion, acompletion
Google GenAI Models.generate_content (new + legacy)
Google ADK BasePlugin lifecycle (tool calls, agent routing, sessions)
Pydantic AI Agent.run, Agent.run_sync
LlamaIndex LLM.chat/achat/complete/acomplete, BaseQueryEngine.query/aquery
Instructor Instructor.create, AsyncInstructor.create
DSPy Module.__call__, LM.forward/aforward
MCP Transport-layer proxy for any MCP server (stdio / HTTP)
httpx Middleware for raw HTTP egress (REST agents, webhooks)
Playwright Browser context instrumentation for browsing agents

Default Guardrails

All deterministic regex. No LLM calls. No network. Sub-millisecond.

Guardrail Default Coverage
Prompt injection Block 85+ patterns, 13 categories, 4 languages (EN/KO/ZH/JA)
PII detection Warn 13 categories — email, credit card, SSN, API keys, IBAN
Toxicity Warn Harmful, violent, abusive content
Prompt leak Warn System prompt extraction attempts

Use Cases

The same primitives, four different entry points.

1. Runtime protection

import aegis
aegis.auto_instrument()

One line. Any framework. Or zero code changes: AEGIS_INSTRUMENT=1 python my_agent.py.

2. Pre-production scanning

pip install agent-aegis
aegis scan .

Found 5 ungoverned tool call(s):
  agent.py:12   OpenAI      function call with tools= — no governance wrapper  [ASI02]
  tools.py:8    LangChain   @tool "search_db" — no policy check               [ASI02]
  run.py:5      subprocess  subprocess.run — direct shell execution            [ASI08]

Governance Score: D

Maps to OWASP Agentic Top 10. Supports --format json|sarif, --threshold A-F, --fix.

3. Policy CI/CD

# aegis.yaml
guardrails:
  injection: { enabled: true, action: block }
  pii: { enabled: true, action: mask }

policy:
  version: "1"
  rules:
    - name: allow_reads
      match: { type: "read*" }
      approval: auto
    - name: block_deletes
      match: { type: "delete*" }
      approval: block

aegis plan current.yaml proposed.yaml    # Preview impact
aegis test policy.yaml tests.yaml        # Regression testing

4. Audit & compliance

aegis audit

  ID  Action        Target   Risk      Decision    Result
  1   read          crm      LOW       auto        success
  2   bulk_update   crm      HIGH      approved    success
  3   delete        crm      CRITICAL  block       blocked

Tamper-evident Merkle chain. SQLite + JSONL + webhooks. EU AI Act / NIST AI RMF / SOC2 mappings built in.

Why Aegis

Writing your own Platform guardrails Enterprise platforms Aegis
Abstraction level Per-framework if/else Single-vendor SDK Proprietary gateway Universal primitives across 12 frameworks
Setup Days of if/else Vendor-specific Procurement + infra pip install + 1 line
Code changes Wrap every call SDK-specific Months Zero
Policy portability Per-framework Locked to ecosystem Single-vendor One YAML, every framework
Governance primitives Build from scratch Subset, vendor-defined Proprietary 10+ composable primitives
Policy testing None None None aegis plan + aegis test
Cost per check $0 $0-$$$ $$$$ $0 (deterministic)
License -- Varies Enterprise MIT

What Only Aegis Does

Other tools check inputs and outputs. Aegis governs the decision itself — with primitives no other governance runtime exposes.

Capability What it means Based on
Tripartite ActionClaim Every tool call splits into Declared (agent-authored, untrusted), Assessed (Aegis-computed), Chain (delegation). Structural separation makes cosmetic alignment detectable. Justification Gap measurement on 14,285 tau-bench calls
Justification Gap 6D asymmetric scoring: agents declare impact, Aegis independently assesses, gap triggers escalation or block. Name from COA-MAS (Carvalho); 6D metric original
Selection Governance Audits what agents exclude, not just what they choose. Detects cosmetic alignment. Santander et al., arXiv:2602.14606
Monotone Trust Constraint Delegated agents cannot escalate their own authority. Trust must be non-increasing along the chain. Lattice-based access control
Full Lifecycle Scan → Instrument → Policy CI/CD → Runtime → Proxy → Audit. One pip install. —

Install

pip install agent-aegis                   # Core
pip install 'agent-aegis[mcp]'            # MCP server + proxy
pip install 'agent-aegis[server]'         # REST API + dashboard
pip install 'agent-aegis[all]'            # Everything

Solutions by Use Case

Framework and problem-specific guides. Each page is a drop-in recipe for one concrete task.

By Framework

By Problem

Compare Aegis

Side-by-side comparisons with the closest alternatives. Use these to decide between tools or combine them.

Framework Cookbook

End-to-end recipes for every supported framework:

Research

Original measurements on public agent trace datasets. Stdlib-only, reproducible in 30 seconds.

  • The Justification Gap in 14,285 Tau-Bench Tool Calls — Formal definition of the Tripartite ActionClaim with a silent-baseline empirical study. 90.3% approve / 9.7% escalate / 0% block across four model:domain groups. Airline domain exposes ~2× the mean gap of retail. Includes soundness sketches for three structural invariants and an honest note on the max-only override limitation discovered during the study.
  • Tool Distribution Drift in 1,960 Tau-Bench Trajectories — Shannon entropy on tool name sequences across GPT-4o and Sonnet 3.5 New. 39.8% of scored trajectories collapse onto one or two tools by the end. Bimodal distribution, 1.7× cross-model gap. All scripts and raw data included.