Skip to content

Architecture

This page is a high-level map of Agent-Aegis for contributors and third-party auditors. It describes the four-layer package structure, the governance pipeline, and the design decisions that shape the codebase. The canonical source of truth for file-level detail is always src/aegis/ in the repository.

Four Layers

Aegis is organized into four concentric layers. Each layer depends only on the layers above it.

Layer Package Role
1. Primitives aegis.core Framework-agnostic governance primitives: Action, ActionClaim, Policy, ClaimPolicy, ImpactVector, DelegationChain, AuditEvent, MerkleAudit, JustificationGap, SelectionAudit, and domain-specific scorers. No framework imports. No network I/O.
2. Guardrails aegis.guardrails Deterministic regex-based checks that run on prompts, tool outputs, and agent responses — injection, PII, toxicity, prompt leak, output schema, tool output, RAG. Sub-millisecond on warm path.
3. Runtime aegis.runtime Execution engine — plan → approve → execute → verify → log. Built-in approval handlers (CLI, Slack, Discord, Telegram, email, webhook, callback) and audit backends (SQLite, JSONL, webhook, Postgres, Redis, batch).
4. Adapters aegis.adapters, aegis.instrument, aegis.integrations Framework-specific instrumentation that maps each supported framework's hooks into Action / Policy / Runtime. Opt-in via aegis.auto_instrument() or explicit wiring.

Around these layers sit the operational surfaces:

  • aegis.cli — aegis scan / check / plan / test / audit / diff / score / compliance / monitor
  • aegis.packs — YAML rule-pack loader for reusable policy fragments
  • aegis.export — audit export formatters (AGEF, Splunk HEC, Elasticsearch)
  • aegis.server — optional Starlette ASGI server for /api/v1/...
  • aegis.proxy, aegis.mcp_proxy, aegis.mcp_server — MCP transport-level governance proxy
  • aegis.config, aegis.init — unified config loader + aegis.init() / aegis.auto_instrument() entry points

Primitives at a glance

The primitives in aegis.core are the contract every other layer maps into. A full list is generated by browsing src/aegis/core/; the headline items:

Primitive File Purpose
Action action.py Unified representation of any tool / LLM / HTTP / MCP call across frameworks
ActionClaim + ImpactVector action_claim.py Tripartite structure (Declared / Assessed / Chain) with 6-dimensional impact
Policy, PolicyRule, PolicyDecision policy.py YAML-defined rules, first-match-wins, glob patterns pre-compiled to regex
ClaimPolicy claim_policy.py Policy layer that operates on 6D impact vectors, not just action types
JustificationGap, ClaimAssessor, RuleBasedImpactScorer justification_gap.py 6D asymmetric scoring, independent assessment, threshold-based verdict
SelectionAudit selection_audit.py Audits what an agent excludes, not just what it picks
DelegationChain, AgentIdentity agent_identity.py Multi-agent trust chain with monotone constraint
AuditEvent, MerkleAudit merkle_audit.py Tamper-evident Merkle-chained audit log with O(log n) inclusion proofs
CryptoAuditChain crypto_audit.py Ed25519-signed chain for long-term compliance evidence
AgentConstitution constitution.py Per-agent ontology + obligations + constraints, inheritable through delegation
PlanRules plan_rules.py Plan-level governance (sequence patterns, cumulative risk)
A2AGovernor, GovernanceEnvelope a2a_governance.py Agent-to-agent handshake, content filter, rate limit, signed envelope
MCPSecurityGate mcp_security.py MCP-specific: tool poisoning, rug-pull, argument sanitization, trust L0-L4
LeakageDetector leakage_detector.py Cross-session/tenant data leakage detection

All primitives are plain Python dataclasses with validators. The only runtime dependency is pyyaml.

Governance Pipeline Flow

Action (with optional agent_id + constitution)
  -> AgentConstitution.check_constraints()   -> constitutional violations
  -> Policy.evaluate()                       -> PolicyDecision (risk, approval, matched_rule)
  -> ClaimPolicy.evaluate(ActionClaim)       -> impact-vector-based verdict
  -> PlanRules.evaluate(plan)                -> sequence / cumulative risk violations
    -> if BLOCK:     Result(BLOCKED),  audit log
    -> if APPROVE:   ApprovalHandler.request_approval()
      -> if denied:  Result(DENIED),   audit log
    -> if AUTO or approved:
      -> Executor.execute()  (with optional RetryPolicy)
      -> Executor.verify()
      -> Result(SUCCESS / FAILED),     audit log (with agent context)
  -> AnomalyDetector.check()                 -> flag anomalies
  -> MerkleAudit.append()                    -> tamper-evident hash-linked log
  -> WebhookManager.notify()                 -> alert on block / anomaly

A2A Communication:
  -> GovernanceHandshake.negotiate()         -> constitutional compatibility check
  -> A2AGovernor.evaluate()                  -> capability + trust + content + rate limit
  -> GovernanceEnvelope attached             -> SHA-256 signed payload

MCP Governance:
  -> MCPSecurityGate.evaluate()              -> poisoning + rug-pull + argument sanitization
  -> LeakageDetector.analyze()               -> cross-session data leakage signals

Key Design Decisions

These are the decisions that shape most of the codebase. They are stable — changes to any of them require a migration note in CHANGELOG.md.

  1. Minimal core dependencies. Only pyyaml is required at import time. Everything else (LangChain, CrewAI, OpenAI, Anthropic, MCP, Playwright, httpx, DSPy, LlamaIndex, Pydantic AI, LiteLLM, Instructor, Google GenAI, Google ADK) is an optional extra. pip install 'agent-aegis[langchain]' etc.

  2. First-match-wins policy. Policy.evaluate() returns on the first matching rule. This keeps policy files predictable, debuggable, and cheap — no rule ordering surprises, no hidden aggregation.

  3. Glob patterns pre-compiled at init. Rule match: patterns use glob syntax (read_*, {update,create}, prod_*) and are compiled to regex once when the policy loads. Evaluation is then pure regex match — sub-microsecond on warm path.

  4. Async-first execution. The runtime engine is async. Sync handlers are wrapped at the adapter boundary.

  5. SQLite for audit by default. Zero config, works everywhere. Postgres, Redis, JSONL, webhook, batch, and Python logging backends are available as opt-in alternatives in aegis.runtime.audit_*.

  6. Deterministic guardrails. Injection detection, PII masking, toxicity, prompt leak, and tool-output guards are all regex-based. No LLM in the hot path. This makes them cheap (<1ms), auditable (every pattern is readable), and test-friendly (deterministic inputs produce deterministic verdicts).

  7. Cryptographic audit chain. CryptoAuditChain produces SHA-256 / SHA3-256 hash-linked entries for EU AI Act Art.12 and SOC2. MerkleAudit goes one step further with a Merkle tree that produces O(log n) inclusion proofs a third party can verify statelessly.

  8. Open-core tiers. Community, Pro, and Enterprise features are gated via a single FeatureGate class so tier logic is centralized rather than scattered.

  9. Constitutional Protocol. Agents carry a Constitution (ontology + obligations + constraints) that propagates through delegation. A2A communication starts with a GovernanceHandshake that verifies constitutional compatibility before any message is exchanged.

  10. Governance Envelope for A2A. Agent-to-agent messages carry the sender's governance credentials in a signed envelope — conceptually similar to TLS certificates — so the receiver can make an informed trust decision instead of blindly accepting a message.

  11. Cross-session leakage detection. Shared MCP servers are a common source of tenant boundary violations. LeakageDetector implements multiple detection methods that flag when a single MCP server starts correlating requests across what should be isolated sessions.

  12. Lazy imports at package root. aegis/__init__.py and aegis/core/__init__.py use __getattr__ + TYPE_CHECKING so only Aegis, init, shutdown, get, and auto_instrument are imported eagerly. Everything else loads on first access. This keeps import time short on agents that only touch a handful of primitives.

  13. MCP Proxy Server. aegis.mcp_proxy is a transparent governance proxy for any MCP server. It sits between an MCP client (Claude Desktop, Cursor) and the target server, passes tool schemas through dynamically, and applies the full MCPSecurityGate -> Policy -> Guardrails -> forward -> audit pipeline. Supports both single-server --wrap mode and multi-server YAML config mode.

  14. Tripartite ActionClaim. Every ActionClaim splits structurally into DeclaredFields (agent-authored, immutable), AssessedFields (system-computed, mutable under an invariant that only ClaimAssessor may write), and ChainFields (delegation infrastructure, immutable). This structural separation is what makes cosmetic alignment (agent claims low impact, actual impact is high) detectable at runtime. See the research paper for the formal definition and an empirical study on 14,285 tau-bench tool calls.

Test Structure

tests/
  conformance/           AGEF / AGP conformance test suite
  core/                  Primitive unit tests
  guardrails/            Deterministic guardrail test matrix
  runtime/               Engine + audit backend tests
  adapters/              Per-framework integration tests
  cli/                   CLI contract tests
  bench_paper_modules.py Microbenchmarks backing the performance claims

5,200+ tests as of v0.9.4. Every primitive ships with a direct unit test file and the conformance suite verifies cross-package invariants (e.g., audit entries produced by any backend must satisfy the AGEF event schema).

Source of Truth

This document is intentionally high-level. When it disagrees with the code, the code wins.