<p align="center"> <img src="docs/assets/demo.gif?v=2" alt="Aegis Demo" width="880"> </p>
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
agent = Agent(
"openai:gpt-4o-mini",
capabilities=[AegisCapability.default()], # injection, PII, toxicity, prompt-leak, hallucination
)
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.
<p align="center"> <sub>The governance layer for AI agents. One API, 12 frameworks, every governance primitive.</sub><br/> <sub>If Aegis helps you, consider giving it a star -- it helps others find it too.</sub> </p>