Agent-Aegis

AI 代理的治理层。一个 API，12 个框架，包含所有治理原语。

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

什么是 Aegis • 原语 • 框架 • 使用场景 • 30 秒上手 • 研究 • 文档 • 演练场

English • 한국어

## 什么是 Aegis 每个 AI 代理框架都在重复构建相同的治理原语——而且每个框架的做法都略有不同。Aegis 就是统一这些原语的抽象层。 | 层级 | 功能 | 示例 | |-------|-------------|----------| | **1. 原语** | 每次工具调用的通用契约 | `Action`, `ActionClaim`, `Policy`, `Result`, `DelegationChain`, `AuditEvent` | | **2. 适配器** | 通过各框架自身的钩子进行自动埋点 | LangChain callbacks, CrewAI `BeforeToolCallHook`, OpenAI Agents tracing, Google ADK `BasePlugin`, MCP transport, DSPy modules, httpx middleware, Playwright context | | **3. 治理** | 可组合为策略的声明式原语 | 提示注入 / PII / 泄露 / 毒性防护栏，RBAC，速率限制，成本预算，漂移检测，异常评分，信任委托，合理性缺口，选择审计，Merkle 审计链 | | **4. 生命周期** | 一个运行时，覆盖代理运维的每个阶段 | 扫描 → 埋点 → 策略 CI/CD → 运行时 → 代理 → 审计 | ``` import aegis aegis.auto_instrument() # 12 frameworks governed. No other code changes. ``` Redis 之于内存数据结构，就像 Aegis 之于代理治理：**一个库，包含所有原语，支持所有框架，提供统一 API**。你不需要分别去写 LangChain 的防护栏、CrewAI 的防护栏和 OpenAI 的防护栏——你只需编写一个 `Policy`，所有框架都会继承它。 ## 原语 每个适配器映射的契约。设计上与框架无关。 | 原语 | 目的 | 模块 | |-----------|---------|--------| | **`Action`** | 跨所有框架的任何 tool / LLM / HTTP / MCP 调用的统一表示 | `aegis.core.action` | | **`ActionClaim`** | 三方结构——声明（由代理编写）/ 评估（由 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`** | 具有单调信任约束（非递增）的多代理交接跟踪 | `aegis.core.agent_identity` | | **`AuditEvent`** | 防篡改的仅追加日志，Merkle 链式结构，支持 SQLite + JSONL + webhook 接收端 | `aegis.core.merkle_audit` | | **`SelectionAudit`** | 审计代理*排除了*什么，而不仅仅是它选择了什么——检测表面迎合行为 | `aegis.core.selection_audit` | | **`JustificationGap`** | 6 维不对称评分：代理声明影响，Aegis 独立评估，缺口触发升级 | `aegis.core.justification_gap` | | **`CryptoAuditChain`** | 用于长期合规证据的 Ed25519 签名链 | `aegis.core.crypto_audit` | Aegis 中的每一个治理功能——异常检测、成本预算、漂移、级联防护、终止开关——都是这些原语的**组合**。阅读[概念指南](https://acacian.github.io/aegis/getting-started/concepts/)以了解它们是如何协同工作的。 ## 框架 一个 API。12 个代理框架 + 3 个协议级适配器。 | 框架 | 钩子 | 状态 | |-----------|------|--------| | **LangChain** | `BaseChatModel.invoke/ainvoke`, `BaseTool.invoke/ainvoke` | 稳定 | | **CrewAI** | `Crew.kickoff/kickoff_async`, 全局 `BeforeToolCallHook` | 稳定 | | **OpenAI Agents SDK** | `Runner.run`, `Runner.run_sync` | 稳定 | | **OpenAI API** | `Completions.create` (chat & completions) | 稳定 | | **Anthropic API** | `Messages.create` | 稳定 | | **LiteLLM** | `completion`, `acompletion` | 稳定 | | **Google GenAI** | `Models.generate_content` (新版 + 旧版) | 稳定 | | **Google ADK** | `BasePlugin` 生命周期 (工具调用、代理路由、会话) | 稳定 | | **Pydantic AI** | `Agent.run`, `Agent.run_sync` | 稳定 | | **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 代理，webhooks) | 稳定 | | **Playwright** | 用于浏览代理的浏览器上下文埋点 | 稳定 | `auto_instrument()` 会检测已安装的组件，并仅对它们进行修补——没有硬依赖。[自定义适配器](https://acacian.github.io/aegis/guides/custom-adapters/)使用相同的 `BaseAdapter` 接口。 ### 默认防护栏 | 防护栏 | 默认行为 | 拦截内容 | |-----------|---------|-----------------| | **提示注入** | 拦截 | 10 种攻击类别，85+ 种模式，支持多语言 (EN/KO/ZH/JA) | | **PII 检测** | 警告 | 13 个类别 (电子邮件、信用卡、SSN、IBAN、API 密钥等) | | **提示泄露** | 警告 | 系统提示提取尝试 | | **毒性** | 警告 | 有害、暴力或辱骂性内容 | | **MCP STDIO 注入** | 拦截 | JSON-RPC 注入、帧拼接、unicode 转义绕过 ([OX Security 公告](https://www.oxsecurity.io/blog/mcp-security-research)) | 确定性正则表达式——无 LLM 调用，无网络请求。每次检查**冷启动 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 原生能力**——无需猴子补丁，提供针对每个代理的显式控制： ``` 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?") ``` [完整的 Pydantic AI 集成指南 →](https://acacian.github.io/aegis/cookbook/pydantic-ai-governance/) ### 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 # 策略影响分析 # 规则：新增 2 条，移除 1 条，修改 3 条 # 影响（重放了 1,247 个操作）： # 23 个操作将从 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/aegis@v0.9.5 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 签名用于长期证据。请参阅[合规指南](https://acacian.github.io/aegis/api/compliance/)。 ### 5. 治理服务器（多代理） 针对多代理的集中式治理。每个代理通过 SDK 连接，服务器处理策略、防护栏、审计和合规。 ``` pip install 'agent-aegis[server]' aegis-server ``` 37 个 REST 端点 + WebSocket 审计流 + Web 仪表板。代理自动注册、发送心跳并通过 HTTP 查询策略。请参阅[治理框架服务器](#governance-framework-server)。 ## 30 秒上手 ``` pip install agent-aegis ``` ``` import aegis aegis.auto_instrument() # 目前所有 12 个框架均受默认 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 | 策略评估 + 执行流水线 | | **代理** | register, heartbeat, list, status | 代理生命周期管理 | | **防护栏** | check, list | 内容安全检查 | | **策略版本管理** | commit, diff, rollback, tag | 类 Git 的策略变更管理 | | **加密审计** | verify, entries, evidence | 防篡改审计链验证 | | **信任与漂移** | trust score, drift detection | 每代理的行为分析 | | **成本** | budget check, reports | LLM 成本治理 | | **合规性** | reports, regulatory gaps | 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` 配置驱动——防护栏、webhooks (Slack/PagerDuty)、速率限制、成本预算和身份验证均为声明式。请参阅 [`aegis-server.example.yaml`](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 + webhooks + Merkle 链** | | **合规性** | 手动文档 | 无 | 企业销售周期 | **内置 EU AI Act, NIST, SOC2** | | **成本** | 工程时间 | 免费-到-$$$ | $$$$ + 基础设施 | **免费 (MIT)。永久。** | ### 只有 Aegis 做到的功能 其他工具检查输入和输出。Aegis 治理的是*决策本身*——带有其他治理运行时未暴露的原语。 | 能力 | 含义 | 基于 | |---|---|---| | **三方 ActionClaim** | 每次工具调用都分为声明（由代理编写，不可信）、评估（由 Aegis 计算）和链（委托）字段。这种结构上的分离使得表面迎合行为能被检测出来。 | [在 14,285 次 tau-bench 调用上进行的合理性缺口测量](https://acacian.github.io/aegis/research/tripartite-action-claim/) | | **合理性缺口** | 6 维不对称评分：代理声明影响，Aegis 独立评估，计算公式为 `per_dim = max(0, assessed − declared)`。报告不足会触发升级 (>0.15) 或阻断 (>0.40)。 | "ActionClaim" 名称来自 [COA-MAS (Carvalho)](https://arxiv.org/abs/2401.05064)；6 维指标 + 运行时形式为原创 | | **选择治理** | 审计代理*排除了*什么，而不仅仅是选择了什么。一个“好心”地省略了风险选项的模型正在施加选择权力——Aegis 能检测到这一点。 | [Santandar 等人, arXiv:2602.14606](https://arxiv.org/abs/2602.14606) | | **单调信任约束** | 被委托的代理不能提升自身的权限。信任级别沿链必须是非递增的——违规行为将被自动阻断。 | 基于格的访问控制 | | **完整生命周期** | 扫描（检测） → 埋点（保护） → 策略 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 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 ``` ## 研究 基于公开代理追踪数据集的原始测量。仅使用标准库，可在 30 秒内复现。 - [**14,285 次 Tau-Bench 工具调用中的合理性缺口**](https://acacian.github.io/aegis/research/tripartite-action-claim/) — 三方 ActionClaim 的正式定义以及静默基线实证研究。在四个模型:领域组中，90.3% 批准 / 9.7% 升级 / 0% 阻断。航空领域暴露的平均缺口大约是零售领域的 ~2 倍。包括针对三个结构不变量的可靠性草图，以及在研究期间发现的关于 `max`-only 覆盖限制的诚实说明。 - [**1,960 次 Tau-Bench 轨迹中的工具分布漂移**](https://acacian.github.io/aegis/research/tau-bench-tool-distribution-drift/) — 针对 GPT-4o 和 Sonnet 3.5 New 的工具名称序列上的 Shannon 熵。39.8% 的已评分轨迹在最后坍缩到一两个工具上。双峰分布，1.7 倍的跨模型差异。包含所有脚本和原始数据。 在你自己的追踪上运行相同的信号： ``` aegis check drift --trace path/to/trace.jsonl ``` CLI 仅读取 `tool_name` 字段——从不读取参数、CoT 或提示——因此企业用户可以对生产环境追踪进行评分而不会泄露 PII。 ## 文档 完整文档请访问 **[acacian.github.io/aegis](https://acacian.github.io/aegis/)**： - [集成指南](https://acacian.github.io/aegis/) — LangChain, CrewAI, OpenAI, MCP 等 - [策略参考](https://acacian.github.io/aegis/) — 条件、模板、最佳实践 - [安全功能](https://acacian.github.io/aegis/) — 防护栏、异常检测、合规 - [架构](ARCHITECTURE.md) — 代码库的结构方式 - [交互式演练场](https://acacian.github.io/aegis/playground/) — 在浏览器中尝试，无需安装 ## 许可证 MIT -- 详见 [LICENSE](LICENSE)。 Copyright (c) 2026 구동하 (Dongha Koo, [@Acacian](https://github.com/Acacian))。创建于 2026 年 3 月 21 日。

_{AI 代理的治理层。一个 API，12 个框架，包含所有治理原语。
如果 Aegis 帮助了你，请考虑给它加个星标——这也能帮助其他人找到它。}

标签：AI基础设施, AI安全, AI治理, AI防护栏, API网关, Chat Copilot, CISA项目, CrewAI, DLL 劫持, LangChain, LiteLLM, LLM, LLM Guardrails, LLM安全防护, MCP, OpenAI, PII脱敏, Python, Unmanaged PE, 人工智能, 人工智能安全, 信任委托, 内存规避, 合规性, 大语言模型, 提示词注入检测, 提示词防御, 敏感信息屏蔽, 无后门, 特征检测, 用户模式Hook绕过, 知识图谱, 策略CI/CD, 网络安全, 自动插桩, 轻量级, 运行时操纵, 逆向工具, 防篡改审计, 隐私保护, 零代码, 零日漏洞检测