Aegis — AI Agent Governance

Agent-Aegis

AI Agent 的治理层。一个 API，12 个框架，涵盖所有治理原语。

Aegis 之于 Agent 治理，正如 Redis 之于数据结构——一个运行时，统一了提示词注入拦截、PII 遮蔽、策略执行、信任委派和防篡改审计，适用于所有 Agent 框架。无需修改代码。
pip install agent-aegis → aegis.auto_instrument() → 现在，12 个框架均已纳入治理。

Aegis 是什么 • 原语 • 框架 • 用例 • 30 秒快速开始 • 研究 • 文档 • 在线演练场

英语 • 한국어

---

---

Aegis 是什么

每个 AI Agent 框架都在重复实现相同的治理原语，而且实现方式各不相同。Aegis 是统一这些原语的抽象层。

层	功能	示例
1. 原语	为每次工具调用提供通用约定	Action、ActionClaim、Policy、Result、DelegationChain、AuditEvent
2. 适配器	通过各框架自身的钩子实现自动检测	LangChain 回调、CrewAI BeforeToolCallHook、OpenAI Agents 追踪、Google ADK BasePlugin、MCP 传输、DSPy 模块、httpx 中间件、Playwright 上下文
3. 治理	可组合成策略的声明式原语	提示词注入／PII／信息泄露／毒性防护、RBAC、速率限制、成本预算、漂移检测、异常评分、信任委派、合理性缺口、选择审计、Merkle 审计链
4. 生命周期	一个运行时，涵盖 Agent 运维的每个阶段	扫描 → 检测 → 策略 CI/CD → 运行时 → 代理 → 审计

import aegis
aegis.auto_instrument()    # 12 frameworks governed. No other code changes.

你无需分别为 LangChain、CrewAI 和 OpenAI 编写防护规则，只需编写一个 Policy，所有框架都会继承它。

与护栏库的区别

它们解决的是不同的问题，而且大多围绕文本展开。Guardrails AI 根据一系列验证器校验模型输出；NeMo Guardrails 使用 Colang DSL 编写对话和工具策略；Snyk Agent Scan——也就是 Snyk 收购后 Invariant Labs 的 mcp-scan——会扫描 MCP 服务和 Agent 技能，以查找已知风险模式，并可在运行时代理它们；LLM Guard 会串联输入／输出扫描器，直到它于 2026 年 7 月归档。每个库都需要你自行接入，并由你选择调用位置。Aegis 则从另一端入手：auto_instrument() 会查找已安装的框架并就地插桩，因此一个 Policy 就能覆盖所有框架，无需改动任何 Agent 代码。它实施的是针对 Agent 而非提示词的约束——在单调信任约束下追踪委派链，审计 Agent 排除了什么，而不只是它选择了什么，衡量 Agent 声明意图与实际影响之间的差距，以及维护防篡改审计链。所有操作都是确定性的，因此请求路径中不会有第二个模型。这些选择并不互斥：语义检测器或基于模型的检测器可以通过 GuardrailEngine.add() 与内置检测器一同使用。

---

基础组件

每个适配器都会映射到的契约。设计上与框架无关。

基础组件	用途	模块
Action	跨所有框架统一表示任意工具／LLM／HTTP／MCP 调用	aegis.core.action
ActionClaim	三方结构——声明（由 Agent 编写）／评估（由 Aegis 计算）／链（委派）	aegis.core.action_claim
Policy	声明式 YAML 规则：匹配 → 风险 → 审批（auto／approve／block）	aegis.core.policy
ClaimPolicy	评估 6 维影响向量的策略层，而不只是工具名称	aegis.core.claim_policy
Guardrails	用于检测注入、PII、提示词泄露、有害内容的确定性正则表达式检查——冷启动 2.65ms／热启动 <1µs	aegis.guardrails
DelegationChain	多 Agent 移交追踪，并带有单调信任约束（信任不可增加）	aegis.core.agent_identity
AuditEvent	防篡改的仅追加日志，采用 Merkle 链，并支持 SQLite + JSONL + webhook 接收端	aegis.core.merkle_audit
SelectionAudit	审计 Agent 排除了什么，而不只是它选择了什么——检测表面上的对齐	aegis.core.selection_audit
JustificationGap	6D 非对称评分：Agent 声明影响，Aegis 独立评估，差距会触发升级处理	aegis.core.justification_gap
CryptoAuditChain	用于长期合规证据的 Ed25519 签名链	aegis.core.crypto_audit

Aegis 中的每项治理功能——异常检测、成本预算、漂移、级联防护、终止开关——都是这些基础组件的组合。阅读概念指南，了解它们如何协同工作。

---

框架

一个 API。12 个 Agent 框架 + 3 个协议级适配器。

框架	钩子	集成方式
Google ADK	BasePlugin 生命周期（工具调用、Agent 路由、会话）	原生 — 补丁只负责安装插件
CrewAI	全局 BeforeToolCallHook、Crew.kickoff/kickoff_async	混合 — 工具调用使用原生钩子，crew 入口使用补丁
Pydantic AI	AbstractCapability · Agent.run/run_sync	原生（可选）· 补丁（自动）
OpenAI Agents SDK	tool_input_guardrail/tool_output_guardrail · Runner.run/run_sync	原生（可选）· 补丁（自动）
LangChain	BaseChatModel.invoke/ainvoke、BaseTool.invoke/ainvoke	补丁
OpenAI API	Completions.create（聊天和补全）	补丁
Anthropic API	Messages.create	补丁
LiteLLM	completion、acompletion	补丁
Google GenAI	Models.generate_content（新旧版本）	补丁
LlamaIndex	每个具体子类上的 LLM.chat/achat/complete/acomplete、BaseQueryEngine.query/aquery	补丁
Instructor	Instructor.create、AsyncInstructor.create	补丁
DSPy	Module.__call__、LM.forward/aforward	补丁
MCP	适用于任何 MCP 服务的传输层代理（stdio / HTTP）	代理 — 无需打补丁
httpx	用于原始 HTTP 出站流量（REST Agent、webhook）的 HttpxExecutor	包装器 — 无需打补丁
Playwright	用于浏览 Agent 的 PlaywrightExecutor	包装器 — 无需打补丁

auto_instrument() 会检测已安装的内容，并且只对这些内容打补丁 — 无硬依赖。自定义适配器使用相同的 BaseAdapter 接口。上方的每个适配器都会由集成工作流每天针对当前上游版本进行测试：该工作流会调用每个框架的真实入口，并断言防护规则确实触发 — 单元测试会模拟这些框架，因此无法自行发现上游变化。

集成策略。 只要存在能够实际阻止操作的原生扩展点，就优先使用它 — Google ADK 的 BasePlugin 和 CrewAI 的 BeforeToolCallHook 都能做到，因此在这两种情况下，auto_instrument() 只会打足够的补丁来安装原生对象。Pydantic AI 和 OpenAI Agents SDK 提供了可选择启用的原生实现（AbstractCapability、tool_input_guardrail），同时也提供基于补丁的路径，适用于零代码场景。其余所有集成都使用补丁，因为它们没有可阻止操作的钩子：原始 OpenAI/Anthropic SDK 和 DSPy 都未提供此类钩子；而 LlamaIndex 的插桩分发器会发出事件，但会吞掉处理程序异常，因此只能观察，无法强制执行。

Pydantic AI 集成正是写明这一策略的原因。在核心维护者 DouweM 审查之前，它一直通过猴子补丁实现 — “这些功能似乎并未作为 Pydantic AI 能力公开？” — 随后便根据原生扩展 API 重新构建（src/aegis/contrib/pydantic_ai.py；审查记录见 pydantic-ai#4888）。

打补丁是后备方案，而非首选 — 它最容易受到上游变更影响，这也是集成工作流存在的原因。

默认防护机制

防护机制	默认设置	检测内容
提示词注入	拦截	13 类攻击、109 种模式、9 种语言（EN/KO/ZH/JA/ES/DE/FR/TH/VI）
PII 检测	警告	13 个类别（电子邮件、信用卡、SSN、IBAN、API 密钥等）
提示词泄露	警告	系统提示词提取尝试
有害内容	警告	有害、暴力或辱骂性内容
MCP STDIO 注入	拦截	JSON-RPC 注入、帧拼接、Unicode 转义绕过（OX Security 安全公告）

确定性正则表达式——不调用大模型，不访问网络。每次检查冷启动耗时 2.65ms / 热启动耗时 <1µs。

---

使用场景

相同的基础功能，五种不同的接入方式。选择最适合你工作流的方式。

1. 运行时防护（最常见）

一行代码。适用于任何框架。

import aegis
aegis.auto_instrument()

也可以完全不改代码——AEGIS_INSTRUMENT=1 python my_agent.py。注入拦截、PII 屏蔽、提示词泄露警告、审计跟踪和策略执行将对每个 LangChain / CrewAI / OpenAI / Anthropic / LiteLLM / ADK / DSPy / LlamaIndex / Pydantic AI 调用生效。

Pydantic AI 原生功能——无需猴子补丁，可显式控制每个 Agent：

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?")

Pydantic AI 完整集成指南 →

2. 生产前扫描

在未经治理的 AI 调用上线前将其找出。

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

支持 --format json|sarif|suggest、--threshold A-F、.aegisscanignore 和内联 # aegis: ignore 指令。使用 aegis scan --fix 自动修复。

3. 策略 CI/CD

安全工具提供运行时防护。Aegis 还负责管理策略生命周期——就像测试和发布代码一样。

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

或者在 PR 阶段拦截未经治理的调用：

- uses: Acacian/[email protected]
  with:
    command: scan
    fail-on-ungoverned: true

4. 审计与合规

每次调用都会记录到具有防篡改功能的 Merkle 链，并内置 EU AI Act / NIST AI RMF / SOC2 映射。

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 接收端。使用 Ed25519 签名保存长期证据。请参阅合规指南。

5. 治理服务（多 Agent）

为多个 Agent 提供集中式治理。每个 Agent 通过 SDK 连接，由服务端处理策略、防护机制、审计和合规。

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

提供 37 个 REST 端点 + WebSocket 审计流 + Web 仪表板。Agent 会自动注册、发送心跳，并通过 HTTP 查询策略。请参阅治理框架服务。

---

30 秒快速开始

pip install agent-aegis

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

也可以使用 YAML 策略进行全面控制：

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

---

安装选项

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 代理 — 无需改动代码即可治理任何 MCP 服务

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

适用于 Claude Desktop、Cursor、VS Code、Windsurf。提供 STDIO 注入防护、工具投毒检测、rug-pull 检测、参数清理、策略评估和完整审计跟踪。

治理框架服务

将 Aegis 作为专用治理服务运行，提供 REST API、WebSocket 流式传输和 Web 仪表板。

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

37 个 REST 端点，覆盖完整的治理生命周期：

API 分组	端点	用途
核心	evaluate、execute、audit、policy	策略评估和执行流程
Agent	register、heartbeat、list、status	Agent 生命周期管理
护栏	check、list	内容安全检查
策略版本控制	commit、diff、rollback、tag	类 Git 的策略变更管理
加密审计	verify、entries、evidence	防篡改审计链验证
信任与漂移	信任评分、漂移检测	针对每个 Agent 的行为分析
成本	预算检查、报告	大模型成本治理
合规	报告、法规差距	SOC2 / GDPR / EU AI Act 报告
会话	list、replay	会话记录和取证回放

通过 Python SDK（同步或异步）连接：

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")

通过 aegis-server.yaml 驱动配置——护栏、Webhook（Slack/PagerDuty）、速率限制、成本预算和身份验证均采用声明式配置。请参阅 aegis-server.example.yaml。

---

为什么选择 Aegis？

	自行编写	平台护栏	企业级平台	Aegis
抽象层级	按框架编写 if/else	单一供应商 SDK	专有网关	适用于 12 个框架的通用基元
设置	花数天编写 if/else	供应商专属配置	Kubernetes + 采购流程	pip install + 一行代码
代码变更	封装每次调用	SDK 专属	数月集成工作	零改动——自动插桩
策略可移植性	每个框架都要重写	受限于生态系统	通常仅支持单一供应商	一份 YAML 策略，适用于所有框架
治理基元	从头构建	子集，由供应商定义	专有	10+ 个可组合基元
策略 CI/CD	无	无	无	aegis plan + aegis test
审计跟踪	printf 调试	仅平台日志	云仪表板	SQLite + JSONL + Webhook + Merkle 链
合规	手动编写文档	无	企业销售周期	内置 EU AI Act、NIST、SOC2 支持
成本	工程师工时	免费至 $$$	$$$$ + 基础设施	免费（MIT）。永久免费。

只有 Aegis 能做到的事

其他工具会检查输入和输出。Aegis 治理的是决策本身——提供其他治理运行时都不具备的基元。

功能	含义	依据
三方 ActionClaim	每次工具调用都拆分为 Declared（由 Agent 编写，不可信）、Assessed（由 Aegis 计算）和 Chain（委派）字段。正是这种结构性分离，让检测表面上的一致性成为可能。	基于 14,285 次 tau-bench 调用测量 Justification Gap
Justification Gap	6 维非对称评分：Agent 声明影响，Aegis 独立评估影响，且 per_dim = max(0, assessed − declared)。少报会触发升级处理（>0.15）或阻止（>0.40）。	名称“ActionClaim”源自 COA-MAS（Carvalho）；6D 指标和运行时形式为原创
选择治理	审计 Agent 排除了什么，而不仅是它们选择了什么。模型“贴心地”省略有风险的选项，就是在行使选择权——Aegis 会检测到这一点。	Santander 等人，arXiv:2602.14606
单调信任约束	被委派的 Agent 无法提升自身权限。信任级别沿委派链必须保持非递增——违反时会自动阻止。	基于格的访问控制
完整生命周期	扫描（检测）→ 插桩（保护）→ 策略 CI/CD（测试）→ 运行时（治理）→ 代理（网关）→ 审计（跟踪）。一个库，一条 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 check policy policy.yaml read:crm # Policy decision per action (CI gate)
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

研究

对公开 Agent 轨迹数据集进行的原始测量。仅使用标准库，可在 30 秒内复现。

• 14,285 次 Tau-Bench 工具调用中的理由差距 — 对三方 ActionClaim 的正式定义及静默基线实证研究。在四个模型与领域组合中，90.3% 通过、9.7% 升级处理、0% 阻止。航空领域的平均差距约为零售业的 2 倍。包含三项结构不变量的可靠性概述，以及研究期间发现的仅支持 max 覆盖的限制说明。
• 1,960 条 Tau-Bench 轨迹中的工具分布漂移 — 对 GPT-4o 和 Sonnet 3.5 New 的工具名称序列计算香农熵。39.8% 的已评分轨迹在结束时收敛到一两个工具。分布呈双峰，模型间差距为 1.7 倍。所有脚本和原始数据均已提供。

在自己的轨迹上运行同一信号：

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

CLI 只读取 tool_name 字段，不读取参数、思维链或提示词，因此企业用户无需外传个人身份信息，就能对生产环境轨迹进行评分。

我们还在 39 个公开 Agent 仓库中运行了 aegis scan，并评估其治理状况：92% 得分为 F。这是对整个生态系统的发现，并非针对某个项目——大多数 Agent 代码完全没有工具调用策略。

文档

完整文档请访问 acacian.github.io/aegis：

• 集成指南 — LangChain、CrewAI、OpenAI、MCP 等
• 策略参考 — 条件、模板、最佳实践
• 安全功能 — 防护机制、异常检测、合规性
• API 稳定性 — 1.x 版本的保证，以及哪些情况算作破坏性变更
• 架构 — 代码库的组织结构
• 交互式 Playground — 在浏览器中试用，无需安装

贡献

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

贡献指南 • 适合新手的议题 •

许可证

MIT -- 详情请参阅 LICENSE。

Copyright (c) 2026 구동하 (Dongha Koo, @Acacian)。创建于 2026 年 3 月 21 日。

---

_{AI Agent 的治理层。一个 API，12 个框架，涵盖所有治理原语。
如果 Aegis 对你有帮助，请考虑为它点个星标——这也能帮助其他人发现它。}