Agent-Aegis

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

Aegis is to agent governance what Redis is to data structures — one runtime that unifies prompt-injection blocking, PII masking, policy enforcement, trust delegation, and tamper-evident audit across every agent framework. No code changes.
pip install agent-aegis → aegis.auto_instrument() → 12 frameworks are now governed.

What is Aegis • Primitives • Frameworks • Use Cases • 30-Second Start • Research • Docs • Playground

English • 한국어

---

---

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.

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	Prompt injection / PII / leak / toxicity guardrails, RBAC, rate limit, cost budget, drift detection, anomaly scoring, trust delegation, justification gap, selection audit, Merkle audit chain
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.

Redis is to in-memory data structures what Aegis is to agent governance: one library, every primitive, every framework, one API. 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 (non-increasing)	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 — anomaly detection, cost budgets, drift, cascade guards, kill switches — 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.

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

auto_instrument() detects what's installed and patches only those — no hard dependencies. Custom adapters use the same BaseAdapter interface.

Default Guardrails

Guardrail	Default	What it catches
Prompt injection	Block	10 attack categories, 85+ patterns, multi-language (EN/KO/ZH/JA)
PII detection	Warn	13 categories (email, credit card, SSN, IBAN, API keys, etc.)
Prompt leak	Warn	System prompt extraction attempts
Toxicity	Warn	Harmful, violent, or abusive content
MCP STDIO injection	Block	JSON-RPC injection, frame concatenation, unicode escape bypass (OX Security advisory)

Deterministic regex — no LLM calls, no network. 2.65ms cold / <1µs warm per check.

---

Use Cases

The same primitives, five different entry points. Pick whichever matches your workflow.

1. Runtime protection (most common)

One line. Any framework.

import aegis
aegis.auto_instrument()

Or zero code changes — AEGIS_INSTRUMENT=1 python my_agent.py. Injection blocking, PII masking, prompt-leak warnings, audit trail, and policy enforcement become active for every LangChain / CrewAI / OpenAI / Anthropic / LiteLLM / ADK / DSPy / LlamaIndex / Pydantic AI call.

Pydantic AI native capability — no monkey-patching, explicit per-agent control:

from pydantic_ai import Agent
from aegis.contrib.pydantic_ai import AegisCapability
from aegis.guardrails import GuardrailEngine, InjectionGuardrail

engine = GuardrailEngine()
engine.add(InjectionGuardrail())

agent = Agent(
    "openai:gpt-4o-mini",
    capabilities=[AegisCapability(engine)],
)
result = await agent.run("What is AI governance?")

Full Pydantic AI integration guide →

2. Pre-production scanning

Find ungoverned AI calls before they ship.

pip install agent-aegis
aegis scan .

Aegis Governance Scan
=====================
Scanned: 47 files in ./src

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]
  llm.py:21     LiteLLM       litellm.completion() — no governance wrapper  [ASI02]
  run.py:5      subprocess    subprocess.run — direct shell execution  [ASI08]
  api.py:14     HTTP          requests.post — raw HTTP in agent code  [ASI07]

Governance Score: D (5 ungoverned call(s))

Supports --format json|sarif|suggest, --threshold A-F, .aegisscanignore, and inline # aegis: ignore pragmas. Auto-fix with aegis scan --fix.

3. Policy CI/CD

Security tools protect at runtime. Aegis also manages the policy lifecycle — the same way you test and ship code.

aegis plan current.yaml proposed.yaml --audit-db aegis_audit.db

# Policy Impact Analysis
#   Rules: 2 added, 1 removed, 3 modified
#   Impact (replayed 1,247 actions):
#     23 actions would change from AUTO → BLOCK

aegis test policy.yaml tests.yaml                      # Run in CI
aegis test policy.yaml --generate                      # Auto-generate test suite
aegis test new.yaml tests.yaml --regression old.yaml   # Regression check

# .github/workflows/policy-check.yml
- uses: Acacian/aegis@main
  with:
    policy: aegis.yaml
    tests: tests.yaml
    fail-on-regression: true

Or block ungoverned calls at PR time:

- uses: Acacian/aegis@v0.9.5
  with:
    command: scan
    fail-on-ungoverned: true

4. Audit & compliance

Every call is logged to a tamper-evident Merkle chain, with mappings to EU AI Act / NIST AI RMF / SOC2 built in.

aegis audit

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

SQLite + JSONL + webhook sinks. Ed25519 signing for long-term evidence. See the Compliance guide.

5. Governance server (multi-agent)

Centralized governance for multiple agents. Each agent connects via SDK, server handles policy, guardrails, audit, and compliance.

pip install 'agent-aegis[server]'
aegis-server

37 REST endpoints + WebSocket audit streaming + web dashboard. Agents auto-register, send heartbeats, and query policy over HTTP. See Governance Framework Server.

---

30-Second Start

pip install agent-aegis

import aegis
aegis.auto_instrument()
# All 12 frameworks now governed with default guardrails.

Or use a YAML policy for full control:

aegis init  # Creates aegis.yaml

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

policy:
  version: "1"
  defaults:
    risk_level: medium
    approval: approve
  rules:
    - name: read_safe
      match: { type: "read*" }
      risk_level: low
      approval: auto
    - name: no_deletes
      match: { type: "delete*" }
      risk_level: critical
      approval: block

---

Install Options

pip install agent-aegis                   # Core (includes auto_instrument for all frameworks)
pip install langchain-aegis               # LangChain standalone integration
pip install 'agent-aegis[mcp]'            # MCP server + proxy
pip install 'agent-aegis[server]'         # REST API + dashboard
pip install 'agent-aegis[all]'            # Everything

MCP Proxy — govern any MCP server with zero code changes

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["--from", "agent-aegis[mcp]", "aegis-mcp-proxy",
               "--wrap", "npx", "-y",
               "@modelcontextprotocol/server-filesystem", "/home"]
    }
  }
}

Works with Claude Desktop, Cursor, VS Code, Windsurf. STDIO injection protection, tool poisoning detection, rug-pull detection, argument sanitization, policy evaluation, full audit trail.

Governance Framework Server

Run Aegis as a dedicated governance server with REST API, WebSocket streaming, and web dashboard.

pip install 'agent-aegis[server]'
aegis-server --init          # Generate aegis-server.yaml
aegis-server                 # Start server on :8000

37 REST endpoints covering the full governance lifecycle:

API Group	Endpoints	Purpose
Core	evaluate, execute, audit, policy	Policy evaluation + execution pipeline
Agents	register, heartbeat, list, status	Agent lifecycle management
Guardrails	check, list	Content safety checks
Policy Versioning	commit, diff, rollback, tag	Git-like policy change management
Crypto Audit	verify, entries, evidence	Tamper-proof audit chain verification
Trust & Drift	trust score, drift detection	Per-agent behavioral analysis
Cost	budget check, reports	LLM cost governance
Compliance	reports, regulatory gaps	SOC2 / GDPR / EU AI Act reports
Sessions	list, replay	Session recording + forensic replay

Connect with the Python SDK (sync or async):

from aegis import AegisClient

with AegisClient("http://localhost:8000", agent_id="my-agent") as client:
    result = client.evaluate("delete", "user_data")
    # result["risk_level"] == "CRITICAL", result["is_allowed"] == False

from aegis import AsyncAegisClient

async with AsyncAegisClient("http://localhost:8000", agent_id="my-agent") as client:
    result = await client.evaluate("read", "reports")

Config-driven via aegis-server.yaml — guardrails, webhooks (Slack/PagerDuty), rate limiting, cost budgets, and auth all declarative. See aegis-server.example.yaml.

---

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 config	Kubernetes + procurement	pip install + one line
Code changes	Wrap every call	SDK-specific	Months of integration	Zero — auto-instruments
Policy portability	Rewrite per framework	Locked to ecosystem	Usually single-vendor	One YAML policy, every framework
Governance primitives	Build from scratch	Subset, vendor-defined	Proprietary	10+ composable primitives
Policy CI/CD	None	None	None	aegis plan + aegis test
Audit trail	printf debugging	Platform logs only	Cloud dashboard	SQLite + JSONL + webhooks + Merkle chain
Compliance	Manual docs	None	Enterprise sales cycle	EU AI Act, NIST, SOC2 built-in
Cost	Engineering time	Free-to-$$$	$$$$ + infra	Free (MIT). Forever.

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), and Chain (delegation) fields. The structural separation is what makes cosmetic alignment detectable.	Justification Gap measurement on 14,285 tau-bench calls
Justification Gap	6-dimensional asymmetric scoring: agents declare impact, Aegis independently assesses it, and per_dim = max(0, assessed − declared). Under-reporting triggers escalate (>0.15) or block (>0.40).	Name "ActionClaim" from COA-MAS (Carvalho); 6D metric + runtime form original
Selection Governance	Audits what agents exclude, not just what they choose. A model that "helpfully" omits risky options is exerting selection power — Aegis detects this.	Santander et al., arXiv:2602.14606
Monotone Trust Constraint	Delegated agents cannot escalate their own authority. Trust levels must be non-increasing along the chain — violations auto-block.	Lattice-based access control
Full Lifecycle	Scan (detect) → Instrument (protect) → Policy CI/CD (test) → Runtime (govern) → Proxy (gateway) → Audit (trace). One library, one pip install.	—

---

CLI

aegis scan ./src/                       # Detect ungoverned AI calls
aegis score ./src/ --policy policy.yaml # Governance score (0-100)
aegis init                              # Generate starter policy
aegis validate policy.yaml              # Validate syntax
aegis plan current.yaml proposed.yaml   # Preview policy changes
aegis test policy.yaml tests.yaml       # Policy regression testing
aegis audit                             # View audit log
aegis serve policy.yaml                 # REST API + dashboard
aegis probe policy.yaml                 # Adversarial policy testing
aegis autopolicy "block deletes"        # Natural language → YAML

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 the 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.

Run the same signal on your own trace:

aegis check drift --trace path/to/trace.jsonl

The CLI reads only the tool_name field — never args, CoT, or prompts — so enterprise users can score prod traces without exfiltrating PII.

Documentation

Full documentation at acacian.github.io/aegis:

• Integration guides — LangChain, CrewAI, OpenAI, MCP, and more
• Policy reference — conditions, templates, best practices
• Security features — guardrails, anomaly detection, compliance
• Architecture — how the codebase is structured
• Interactive playground — try in browser, no install

Contributing

git clone https://github.com/Acacian/aegis.git && cd aegis
make dev      # Install deps + hooks
make test     # Run tests
make lint     # Lint + format check

Contributing Guide • Good First Issues •

License

MIT -- see LICENSE for details.

Copyright (c) 2026 구동하 (Dongha Koo, @Acacian). Created March 21, 2026.

---

_{The governance layer for AI agents. One API, 12 frameworks, every governance primitive.
If Aegis helps you, consider giving it a star -- it helps others find it too.}