用 Agent OS 治理 CrewAI 智能体基于角色策略、工具白名单与防篡改审计日志的完整实战【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit本文讲解如何将 AI Agent Governance Toolkit 中的 Agent OS 治理内核插入 CrewAI 多智能体 Crew 与外部世界之间实现按角色per-role的策略下发、工具调用白名单allow-list强制、动作预算action budget限制以及带 SHA-256 输入哈希的审计日志。读完本文你将掌握零 API Key 即可运行的治理演示、policies.yaml 四层策略检查语义以及生产环境中基于 CrewAI 原生 Hooks 的真实接入方式。CrewAI 让搭建自主多智能体 Crew 变得非常简单但这份便利也带来了真实风险一个researcher角色理论上可以调用write_file或execute_command一次成功的提示注入prompt injection可能让智能体执行rm -rf /而当合规审计来临时你却说不出哪个智能体碰过哪个资源。Agent OS 的解决方案是把一个**治理内核governance kernel**插在 Crew 与外部世界之间每一次工具调用都先经过策略检查再执行完全不需要依赖提示词工程prompt engineering。为什么要治理 CrewAI 智能体风险典型场景权限过大的智能体Over-privileged agents一个researcher智能体在调用write_file或execute_command提示注入Prompt injection任务输入诱导智能体执行rm -rf /无审计线索No audit trail无法证明哪个智能体触碰了哪个资源合规缺口Compliance gapsSOC 2 / HIPAA 要求访问控制的可证明证据Agent OS 通过在 Crew 与外部世界之间插入治理内核解决上述问题每一次工具调用在执行前都会经过策略检查——不需要任何提示词工程。快速开始1. 安装pip install agent-os-kernel crewai # crewai 对 demo 来说是可选依赖2. 运行 Demo无需任何 API KeyDemo 代码已经随仓库提供位于 agent-governance-python/agent-os/examples/crewai-governance/cd agent-governance-python/agent-os/examples/crewai-governance python demo.pyDemo 会创建三个模拟智能体——researcher、writer、reviewer——并让它们依次运行所有动作都经过从 policies.yaml 加载的策略引擎校验。从源码结构看demo.py 是完全自包含的它在_load_yaml中优先使用 PyYAML缺失时回退到一个只支持扁平结构的最小 YAML 解析器同时用MockCrewAgent模拟 CrewAI 智能体因此运行 Demo 既不需要 API Key也不需要安装 crewai 包。输出带 ANSI 彩色日志被拦截的动作会以醒目的BLOCKED — POLICY VIOLATION红色方框呈现并最终打印完整审计报告与 ALLOWED / BLOCKED 统计。工作原理用 Agent OS 包裹 CrewAI Crew治理内核的插入位置┌─────────────┐ ┌──────────────────┐ ┌──────────┐ │ CrewAI │────▶│ Agent OS Kernel │────▶│ Tools │ │ Agent │ │ (policy check) │ │ │ └─────────────┘ └──────────────────┘ └──────────┘ │ │ │ ┌──────┴──────┐ │ │ Audit Log │ │ └─────────────┘ ▼ If blocked → PermissionError (action never reaches the tool)在代码层面三个核心组件协作完成治理from agent_os_governance import RolePolicyEngine, GovernedKernel, AuditLog engine RolePolicyEngine(policies.yaml) audit AuditLog() kernel GovernedKernel(engine, audit) # 每一次工具调用都经过内核 result kernel.execute( agent_idagent-researcher, roleresearcher, toolweb_search, paramslatest AI safety papers, )对照 demo.py 的实现GovernedKernel.execute的执行顺序是先调用engine.check(role, tool, params)做策略判定然后无论结果如何都写入审计日志decision取ALLOWED或BLOCKED最后只有当result.allowed为假时才抛出PermissionError——动作永远不会到达真正的工具。这正体现了 Agent OS 的设计哲学治理是内核问题kernel concern而不是提示词问题。策略配置policies.yaml 详解策略以 YAML 声明仓库中实际使用的 policies.yaml 比文档示例更完整包含全局共享的敏感模式shared: blocked_patterns: - rm -rf - sudo - eval( - exec( - __import__ - DROP TABLE - DELETE FROM - chmod 777 - curl | bash - /etc/passwd - api_key - secret_token roles: researcher: description: Can search the web and read files — no writes allowed allowed_tools: - web_search - read_file - list_directory blocked_patterns: - write_file - delete_file - execute_command max_actions: 20 writer: description: Can read and write files — no web, no shell allowed_tools: - read_file - write_file - list_directory blocked_patterns: - web_search - execute_command - delete_file max_actions: 15 reviewer: description: Read-only — can only inspect artefacts allowed_tools: - read_file - list_directory blocked_patterns: - write_file - delete_file - web_search - execute_command max_actions: 10每个角色声明三类约束allowed_tools—— 只允许调用这里列出的工具名blocked_patterns—— 只要动作/参数命中这些字符串即拒绝子串匹配不区分大小写max_actions—— 可选每任务动作预算上限。shared段则对所有智能体无条件生效与角色无关。检查顺序四层强制Enforcement layers对照 demo.py 中RolePolicyEngine.check的实现判定顺序严格如下共享屏蔽模式Shared blocked patterns—— 对每个角色一律拒绝如rm -rf、sudo、api_key。实现中先将tool与params拼接为小写字符串再逐个子串匹配角色专属屏蔽模式Role-specific blocked patterns—— 对特定角色拒绝如 researcher 的write_file、reviewer 的全部写操作工具白名单Tool allow-list—— 只有明确列出的工具才被允许调用动作预算Action budget—— 每个角色每任务的动作总数上限max_actions。另外值得注意如果check收到了一个策略文件中不存在的角色名会直接返回PolicyResult(False, fUnknown role: {role})即未知角色默认拒绝fail-closed这与项目 ADR-0013 fail-closed-on-policy-evaluation-errors 的原则一脉相承。审计日志每次动作都留痕每次动作——无论放行还是拦截——都会被记录。Demo 中的AuditEntry包含以下字段见 demo.py字段说明timestampUTC ISO-8601 时间戳agent_id唯一智能体标识符roleCrewAI 角色名tool被请求的工具input_hash原始输入的 SHA-256 哈希前 16 位十六进制绝不记录原始数据decisionALLOWED或BLOCKEDreason人类可读的解释说明将日志导出为 JSON 供合规管线消费print(audit.to_json())这里有一个值得强调的隐私设计input_hash只落哈希不落原文。Demo 的AuditLog.record对原始输入做hashlib.sha256(raw_input.encode()).hexdigest()[:16]既保留了某条输入是否被处理过的可验证性又避免把可能包含机密的任务内容写进审计文件。从 Demo 到生产可插拔审计后端Demo 中的AuditLog是内存实现面向教学。真实生产环境应使用 audit_logger.py 中的GovernanceAuditLogger 可插拔后端JsonlFileBackend—— 追加写 JSONL 文件内部加锁避免并发行交错并在 POSIX 上强制0o600权限仅属主可读写防止审计日志被其他进程读取InMemoryBackend—— 内存存储适合测试LoggingBackend—— 通过标准 Python logging 输出可对接现有日志管道。from agent_os.audit_logger import GovernanceAuditLogger, JsonlFileBackend, InMemoryBackend audit GovernanceAuditLogger() audit.add_backend(InMemoryBackend()) # 测试用 audit.add_backend(JsonlFileBackend(audit.jsonl)) # 生产用0600 权限 audit.log_decision(agent_idagent-researcher, actionweb_search, decisionallow, reasonpolicy check passed)这种内存 文件/日志组合模式让治理审计既能服务单元测试又能直接接入合规与 SIEM 管线。Before / After改造前后对比❌ 改造前——无治理的 CrewAI Crewfrom crewai import Agent, Task, Crew researcher Agent(roleResearcher, tools[web_search, read_file, write_file]) # ⚠️ researcher 可以写文件——没有任何护栏 # ⚠️ 没有审计线索 # ⚠️ 一次提示注入就可能触发破坏性工具 crew Crew(agents[researcher], tasks[...]) crew.kickoff()✅ 改造后——用 Agent OS 治理from crewai import Agent, Task, Crew # 1. 加载策略 engine RolePolicyEngine(policies.yaml) audit AuditLog() kernel GovernedKernel(engine, audit) # 2. 包装工具让每次调用都经过内核 safe_search kernel.wrap_tool(researcher, web_search) safe_read kernel.wrap_tool(researcher, read_file) researcher Agent(roleResearcher, tools[safe_search, safe_read]) crew Crew(agents[researcher], tasks[...]) crew.kickoff() # 3. 导出审计日志 print(audit.to_json())发生了什么变化researcher 现在只能调用web_search和read_file即使 LLM 试图调用write_file也会在内核层面被拦截每次动作都以 SHA-256 输入哈希的形式记录在案满足合规要求。深入原理真实 CrewAI 集成的四个原生 HooksDemo 用GovernedKernel.execute与wrap_tool演示了治理语义而仓库中面向真实 CrewAI 的集成是 crewai_adapter.py。该适配器支持两种接入路径推荐路径——原生 HooksCrewAI 0.80CrewAIKernel(runtime...).as_hooks(prod-governance)会创建并注册四个全局 Hooksbefore_tool_call、after_tool_call、before_llm_call、after_llm_call对 Crew 中所有智能体的每次工具调用与 LLM 调用实施治理见GovernanceHooks.register兼容路径——legacywrap()在crewai.hooks不可用CrewAI 版本过旧或未安装时回退到代理包装方式项目根 README 中给出了CrewAIKernel().wrap(my_crew)的用法。四个 Hooks 各司其职对照源码 crewai_adapter.pybefore_tool_call工具执行前的治理闸门。检查工具白名单/黑名单、扫描参数中的屏蔽模式、运行策略pre_tool_call评估返回False拦截、返回None放行并递增ctx.call_count计入工具调用预算after_tool_call工具执行后的闸门。扫描工具输出是否包含屏蔽模式运行post_execute漂移检测违规时抛出PolicyViolationErrorbefore_llm_callLLM 调用前的闸门。将 messages 拼接后扫描屏蔽模式并允许策略对最后一条用户消息做内容改写rewriteafter_llm_callLLM 响应后的闸门。扫描响应内容支持策略改写响应违规即抛异常。从架构文档 ARCHITECTURE.md 的策略决策流可以看到这一机制与 Agent OS 的整体设计一致先经allowed_tools判定不在列表即TOOL_CALL_BLOCKED再查blocked_patterns支持 SUBSTRING/REGEX/GLOB 三种模式命中即POLICY_VIOLATION随后检查max_tokens / max_tool_calls等限额全部通过后才执行动作并生成AuditEntry。也就是说CrewAI Demo 里的四层检查是 Agent OS 内核策略判定在 CrewAI 场景下的一个聚焦子集。文件清单文件用途demo.py可运行 Demo——无需 API Key自包含实现策略引擎、内核包装与审计日志policies.yaml按角色的治理策略含共享屏蔽模式与动作预算crewai_adapter.py真实 CrewAI 集成四个原生治理 Hooks 与CrewAIKernel适配器audit_logger.py生产级审计日志JSONL 文件、内存、logging 三种可插拔后端ARCHITECTURE.mdAgent OS 四层内核架构与策略决策流说明小结治理 CrewAI Crew 的核心并不复杂把策略检查从希望 LLM 遵守提示词挪到内核强制拦截每一次工具调用并让每一次放行/拦截都留下可审计的痕迹。本文基于 Agent OS 的 CrewAI 治理示例从零 API Key 的 Demo 入手完整覆盖了policies.yaml的四层检查语义、审计日志字段与 SHA-256 输入哈希设计再深入到真实 CrewAI 集成的四个原生 Hooks 与生产级审计后端。以此为基础你可以将同样的治理模式扩展到 LangChain、AutoGen、OpenAI Agents SDK 等其他框架构建一套统一的、面向合规的智能体治理体系。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考