Aegis— agent skill

<!-- mcp-name: io.github.Acacian/aegis --> <p align="center"> <h1 align="center">Agent-Aegis</h1> <p align="center"> <strong>The governance layer for AI agents. One API, 12 frameworks, every governance primitive.</strong> </p> <p align="center"> 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.<br/> <code>pip install agent-aegis</code> → <code>aegis.auto_instrument()</code> → 12 frameworks are now governed. </p> </p>

<p align="center"> <a href="https://github.com/Acacian/aegis/actions/workflows/ci.yml"><img src="https://github.com/Acacian/aegis/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://pypi.org/project/agent-aegis/"><img src="https://img.shields.io/pypi/v/agent-aegis?color=blue&cacheSeconds=3600" alt="PyPI"></a> <a href="https://pypi.org/project/langchain-aegis/"><img src="https://img.shields.io/pypi/v/langchain-aegis?label=langchain-aegis&color=blue&cacheSeconds=3600" alt="langchain-aegis"></a> <a href="https://pypi.org/project/agent-aegis/"><img src="https://img.shields.io/pypi/pyversions/agent-aegis?cacheSeconds=3600" alt="Python"></a> <a href="https://github.com/Acacian/aegis/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a> <a href="https://acacian.github.io/aegis/"><img src="https://img.shields.io/badge/docs-acacian.github.io%2Faegis-blue" alt="Docs"></a> <br/> <a href="https://github.com/Acacian/aegis/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-6300%2B_passed-brightgreen" alt="Tests"></a> <a href="https://github.com/Acacian/aegis/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="Coverage"></a> <a href="https://acacian.github.io/aegis/playground/"><img src="https://img.shields.io/badge/playground-Try_it_Live-ff6b6b" alt="Playground"></a> <a href="https://acacian.github.io/aegis/playground/scan-report.html"><img src="https://img.shields.io/badge/scan_report-39_Repos%2C_92%25_F-red" alt="Scan Report"></a> <a href="https://www.bestpractices.dev/projects/12253"><img src="https://www.bestpractices.dev/projects/12253/badge" alt="OpenSSF Best Practices"></a> </p>

<p align="center"> <a href="#what-is-aegis"><strong>What is Aegis</strong></a> &bull; <a href="#primitives">Primitives</a> &bull; <a href="#frameworks">Frameworks</a> &bull; <a href="#use-cases">Use Cases</a> &bull; <a href="#30-second-start"><strong>30-Second Start</strong></a> &bull; <a href="#research">Research</a> &bull; <a href="https://acacian.github.io/aegis/">Docs</a> &bull; <a href="https://acacian.github.io/aegis/playground/"><strong>Playground</strong></a> </p>

<p align="center"> <b>English</b> &bull; <a href="./README.ko.md">한국어</a> </p>

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

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.

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.

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

Default Guardrails

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/[email protected]
  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:

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?

What Only Aegis Does

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

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](https://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 &bull; Good First Issues &bull;

License

MIT -- see LICENSE for details.

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

<p align="center"> _{The governance layer for AI agents. One API, 12 frameworks, every governance primitive.}<br/> _{If Aegis helps you, consider giving it a star -- it helps others find it too.} </p>