Aegize 实战教程：给你的 AI Agent 加上身份、权限和审批工作流

AI Agent 的能力正在从”回答问题”跨越到”执行操作”——调用 Shell 运行命令、发送邮件、操作数据库、甚至调用支付 API。但一个只返回文本的模型很容易管控，一个真正动起来的 Agent 则不同：它需要身份、细粒度的权限、高风险操作的人工审批，以及完整的行为审计日志。

Aegize 正是填补这个空白的运行时基础设施层——一个 Python SDK + CLI 工具，为 AI Agent 提供 Identity（身份）、Policy（策略）、Permissions（权限）、Approval Workflows（审批工作流）和 Audit Logging（审计日志）五大能力。MIT 开源许可，16K 字符的详尽 README 涵盖了从 Quickstart 到架构设计的完整内容。

本文将带你动手部署 Aegize，从安装、编写策略文件到实战运行一个完整的三段式审批流程。

快速安装

pip install aegize

一行命令安装，唯一的运行时依赖是 PyYAML。也可以从源码安装：

git clone https://github.com/gggaswint/aegize.git
cd aegize
pip install -e ".[dev]"

安装后，你会获得 aegize Python 包和 aegize CLI 命令。

核心概念速览

Aegize 围绕四个核心抽象设计：

1. AgentIdentity — 每个 Agent 的持久化身份（ID、拥有者、环境、元数据）
2. PermissionPolicy — YAML 策略引擎，返回 allow/deny/require_approval 三种结果
3. GuardedTool / @guarded_tool — 执行边界点：包裹任何可调用对象，强制经过身份识别、策略检查、门控和审计
4. AuditLog — 追加式 JSONL 审计记录，记录每次尝试和结果，永不覆盖

评估顺序为：deny → require_approval → allow → default-deny。明确配置的 deny 规则有最高优先级，任何未显式允许的操作默认拒绝（default deny）。这条规则确保安全不会因配置遗漏而失效。

编写策略文件

Aegize 的策略以 YAML 格式定义，按 Agent 分组。创建一个 aegize.yaml：

agents:
  research_bot:
    allow:
      - tool: web_search
        operations: ["search"]
        risk_level_max: medium
      - tool: file_reader
        operations: ["read"]
        paths:
          - "./safe_data/**"

    require_approval:
      - tool: email
        operations: ["send"]
      - tool: shell
        operations: ["execute"]

    deny:
      - tool: payments
        operations: ["charge"]
      - tool: shell
        operations: ["rm", "delete"]

这个策略的含义很明确：research_bot 可以搜索网页和读取指定目录的文件，发送邮件和执行 Shell 命令需要人工审批，支付扣款和删除操作则被直接禁止。

每条规则支持 tool（工具名）、operations（操作名列表）、risk_level_max（最高允许风险等级）和 paths（路径通配白名单）等字段。

实战：三种操作三种结果

Aegize 的 README 内置了一个经典的演示：同一个 Agent 调用三个不同的工具，得到三种不同的结果。

from aegize import AgentIdentity, PermissionPolicy, GuardedTool, AuditLog

agent = AgentIdentity(
    agent_id="research_bot",
    name="Research Bot",
    owner="Geoffrey",
    environment="dev",
)

policy = PermissionPolicy.from_yaml("aegize.yaml")
audit = AuditLog("audit.jsonl")

def web_search(query: str) -> str:
    return f"搜索结果：{query}"

def send_email(to: str, body: str) -> str:
    return f"邮件已发送至 {to}"

def execute_shell(cmd: str) -> str:
    return f"执行结果：{cmd}"

safe_search = GuardedTool(
    tool_name="web_search", operation="search", func=web_search,
    agent=agent, policy=policy, audit_log=audit, risk_level="low",
)
safe_email = GuardedTool(
    tool_name="email", operation="send", func=send_email,
    agent=agent, policy=policy, audit_log=audit, risk_level="high",
)
safe_shell = GuardedTool(
    tool_name="shell", operation="execute", func=execute_shell,
    agent=agent, policy=policy, audit_log=audit, risk_level="critical",
)

try:
    result = safe_search("Aegize runtime")
    print(f"[ALLOWED] 搜索成功：{result}")
except Exception as e:
    print(f"[DENIED] {e}")

try:
    safe_email("ceo@example.com", "Q3 数据报告")
except ApprovalRequired as e:
    print(f"[APPROVAL REQUIRED] 邮件发送需要人工审批")
except Exception as e:
    print(f"[DENIED] {e}")

try:
    safe_shell("rm -rf /var/data")
except PolicyDenied as e:
    print(f"[DENIED] Shell 执行被策略禁止")

运行这段代码，你会看到：

[ALLOWED] 搜索成功：搜索结果：Aegize runtime
[APPROVAL REQUIRED] 邮件发送需要人工审批
[DENIED] Shell 执行被策略禁止

三个调用全部被审计日志记录。审计文件 audit.jsonl 的内容形如：

{"timestamp": "2026-06-27T18:00:00+00:00", "event": "allowed", "agent_id": "research_bot", "tool_name": "web_search", "operation": "search", "risk_level": "low", "input_summary": "'Aegize runtime'", "reason": "allowed by rule for tool 'web_search'"}
{"timestamp": "2026-06-27T18:00:00+00:00", "event": "approval_required", "agent_id": "research_bot", "tool_name": "email", "operation": "send", "risk_level": "high", "input_summary": "'ceo@example.com', 'Q3...'", "reason": "approval required for tool 'email'"}
{"timestamp": "2026-06-27T18:00:00+00:00", "event": "denied", "agent_id": "research_bot", "tool_name": "shell", "operation": "execute", "risk_level": "critical", "input_summary": "'rm -rf /var/data'", "reason": "denied by rule for tool 'shell'"}

注意每条审计记录在函数执行之前就写入（先记录决策，再记录结果），确保即使进程崩溃也不会丢失授权记录。

使用装饰器简化代码（v0.2+）

如果你不想手动包裹每个函数，Aegize v0.2 提供了 @guarded_tool 装饰器+GuardContext 的简化写法：

from aegize import (
    AgentIdentity, PermissionPolicy, AuditLog,
    GuardContext, guarded_tool, guard, ApprovalRequired,
)

@guarded_tool(tool_name="email", operation="send", risk_level="high")
def send_email(to: str, body: str) -> str:
    return f"发送至 {to}：{body}"

ctx = GuardContext(
    agent=AgentIdentity(agent_id="research_bot", name="Research Bot", owner="Geoffrey"),
    policy=PermissionPolicy.from_yaml("aegize.yaml"),
    audit_log=AuditLog("audit.jsonl"),
)

guarded_send = guard(send_email, context=ctx)

try:
    guarded_send("ceo@example.com", "季度数据")
except ApprovalRequired:
    print("需人工审批")

guard() 返回的可调用对象保留原始的 __name__、docstring 和函数签名，因此可以直接注册到 MCP 服务器或其他工具注册中心，无需额外适配。

策略测试：可 CI 集成的预检查

Aegize 的 CLI 提供了一个很有价值的工具——在策略文件上线前用 aegize policy test 验证决策是否符合预期：

aegize policy test aegize.yaml policy_tests.yaml

测试用例也以 YAML 定义：

tests:
  - name: 网页搜索应被允许
    agent: research_bot
    tool: web_search
    operation: search
    expect: allow

  - name: 支付扣款应被拒绝
    agent: research_bot
    tool: payments
    operation: charge
    expect: deny

  - name: 读取白名单外路径应被拒绝
    agent: research_bot
    tool: file_reader
    operation: read
    metadata: { path: "/etc/passwd" }
    expect: deny

测试只评估策略逻辑，不会执行实际工具函数。退出码为 0（全通过）/1（决策不匹配）/2（文件格式错误），可以直接集成到 CI pipeline 作为策略回归门禁。

与 Claude Code / Cursor 等编码 Agent 的集成

Aegize 虽然是一个 Python 库，但它的 GuardedTool 返回的是签名的可调用对象，可以直接嵌入到 MCP 服务器的工具注册流程中。目前 roadmap 上规划了针对流行 Agent 框架的一级适配器。

对于当前的 Claude Code、Cursor 或 Codex 使用场景，你可以：

1. 用 @guarded_tool 装饰你的工具函数
2. 在 MCP server 中注册 guard() 返回的可调用对象
3. 所有 Agent 调用这些工具时，自动经过权限策略和审计

这意味着即使 Agent 模型本身没有安全意识，Aegize 作为运行时拦截层仍然能防止它执行越权操作。

小结

Aegize 解决的是 AI Agent 从实验到生产的关键一步：动起来之后谁负责、谁能做什么、违规了怎么办。它没有试图改写 Agent 的行为，而是在工具调用层加入了身份验证、权限策略、审批门控和审计日志四道防线。

对于正在把 AI 编码 Agent 引入实际项目的团队来说，Aegize 提供了一个轻量但完整的治理框架——既可以作为 PoC 快速体验，也可以作为生产环境的策略-as-代码基础设施持续演进。

相关链接：

• Aegize GitHub
• Aegize 官网
• Aegize 架构文档
• Aegize Roadmap