Agent OS 5 分钟上手：用内核级策略强制为自主 AI Agent 构建安全治理环境

Agent OS 5 分钟上手用内核级策略强制为自主 AI Agent 构建安全治理环境【免费下载链接】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导读Agent OSagent-os是 agent-governance-toolkit 中一个以安全为先的 Agent 内核实现它把传统的框架建议、Agent 自觉扭转成内核强制执行所有 Agent 动作都必须以系统调用syscall的方式穿过内核空间由策略引擎在动作真正执行前完成判定违规动作将被不可捕获的SIGKILL信号直接终止。本文以官方 5 分钟快速入门getting-started.md为主线完整带你完成安装、创建第一个受治理 Agent、触发策略违规、接入 LLM 的实战流程并深入内核源码解释用户态/内核态分离、策略引擎、信号分发、飞行记录器背后的工作原理。读完本文你将掌握 Agent OS 的核心用法、策略模式的配置方式以及如何在生产环境中利用无状态内核扩展治理能力。前置要求按官方文档的要求开始之前需要准备Python 3.10pip需要说明的是当前仓库中agent-os的 pyproject.toml 声明requires-python 3.11因此建议直接使用 Python 3.11 及以上版本运行以获得完整兼容性。Step 1安装 Agent OS约 30 秒在终端中执行pip install agent-os-kernel如果希望一次性安装全部可选组件可以参考官方 Quick Reference 中的安装选项# 仅核心 pip install agent-os-kernel # 带特定功能 pip install agent-os-kernel[cmvk] # Verification pip install agent-os-kernel[observability] # Prometheus/OpenTelemetry pip install agent-os-kernel[full] # Everything关于包状态的说明根据当前仓库 src/agent_os/init.py 与 pyproject.toml 中的注释agent-os-kernel已被标记为弃用deprecated5.0.0 版本发布的是一个仅含依赖重定向的存根包会转向agent-governance-toolkit-core同时导入agent_os时会抛出DeprecationWarning。上述安装命令与官方教程保持一致但面向新项目时建议直接安装agent-governance-toolkit-core以规避弃用警告。仓库内的agent_os源码树位于 agent-governance-python/agent-os/src/agent_os仍通过可编辑安装方式在 CI 中持续测试本文后续示例均可在该源码基础上对照验证。Step 2创建你的第一个 Agent约 2 分钟新建文件my_agent.pyfrom agent_os import KernelSpace # Create the kernel (enforces safety policies) kernel KernelSpace(policystrict) kernel.register async def my_agent(task: str) - str: A simple agent that processes tasks safely. # This could be any LLM call return fProcessed: {task} # Run it if __name__ __main__: import asyncio result asyncio.run(kernel.execute(my_agent, Hello, Agent OS!)) print(result)这段代码做了三件关键的事创建内核KernelSpace(policystrict)实例化一个启用strict策略的内核。从源码看KernelSpace位于 kernel_space.py它把策略引擎、飞行记录器、信号分发器、VFS 挂载管理器和 IPC 路由整合在受保护的内核态中。注册 Agentkernel.register装饰器把用户函数注册进内核此后该函数的一切动作都接受策略检查。受治理执行kernel.execute(my_agent, ...)不是直接调用函数而是让调用穿过内核的系统调用路径。Step 3运行它约 30 秒python my_agent.py输出Processed: Hello, Agent OS!Step 4尝试一次策略违规约 1 分钟编辑my_agent.py让 Agent 尝试做一件危险的事kernel.register async def my_agent(task: str) - str: # Try to delete a file - this will be blocked! import os os.remove(/etc/passwd) # SIGKILL! return Done再次运行python my_agent.py输出⚠️ POLICY VIOLATION DETECTED ⚠️ Signal: SIGKILL ⚠️ Action: file_write ⚠️ Policy: strict ⚠️ Status: TERMINATED内核在危险动作真正执行之前就把它拦截了。这正是 Agent OS 与普通 Agent 框架的本质区别不是事后建议而是事前强制。从 kernel-internals.md 的请求生命周期看策略判定发生在动作执行之前Agent code makes syscall (SYS_EXEC, SYS_WRITE, etc.) │ ▼ Kernel receives ExecutionRequest │ ▼ Policy Engine evaluates each policy - Check blocked_actions - Check blocked_patterns - Check constraints If ANY check fails → SIGKILL │ ┌────┴────┐ │ DENIED │───▶ ExecutionResult(signalSIGKILL) └─────────┘为什么是 SIGKILL信号signal是内核向 Agent 下达控制指令的机制设计上借鉴了 POSIX 信号但专门面向 Agent 生命周期控制。在 signals.py 中定义了完整的信号枚举信号值含义是否可屏蔽SIGSTOP1暂停执行进入检查模式是SIGCONT2恢复执行是SIGINT3优雅中断是SIGKILL4立即终止策略违规触发否SIGTERM5请求优雅关闭是SIGUSR16进入诊断模式是SIGUSR27触发检查点/快照是SIGPOLICY8检测到策略违规否SIGTRUST9越过信任边界否SIGBUDGET10资源预算超限是SIGLOOP11检测到无限循环是SIGDRIFT12检测到目标漂移是其中SIGKILL与SIGPOLICY被SignalMask标记为UNMASKABLE不可屏蔽——这是内核权威kernel authority的体现Agent 无法通过自定义 handler 或信号掩码绕过终止指令。SignalMask.block()在面对这两个信号时会直接拒绝并记录警告见 signals.py。Step 5接入 LLM约 1 分钟受治理的内核并不限制你使用大模型它限制的是动作。把上一步的 Agent 升级为调用 LLM 的智能体from agent_os import KernelSpace from openai import OpenAI # or any LLM kernel KernelSpace(policystrict) client OpenAI() kernel.register async def smart_agent(task: str) - str: response client.chat.completions.create( modelgpt-4, messages[{role: user, content: task}] ) return response.choices[0].message.content if __name__ __main__: import asyncio result asyncio.run(kernel.execute(smart_agent, Explain quantum computing)) print(result)这里演示了一个核心设计LLM 负责思考与生成内核负责动作与边界。LLM 生成的任何工具调用、文件操作、网络请求最终都要回到内核接受策略判定从而把幻觉、越权、危险操作都关进笼子里。原理用户态与内核态分离官方文档用一个直观的架构图说明了执行模型┌─────────────────────────────────────────────────────────┐ │ USER SPACE (Your Agent) │ │ my_agent() runs here. Can crash, hallucinate, etc. │ ├─────────────────────────────────────────────────────────┤ │ KERNEL SPACE (Agent OS) │ │ Policy Engine checks every action before execution │ │ If policy violated → SIGKILL (non-catchable) │ └─────────────────────────────────────────────────────────┘你的 Agent 代码运行在用户态——它可以崩溃、可以幻觉但所有动作都被内核截获并对照策略检查。如果违反策略内核发送 Agent 无法捕获或忽略的信号如SIGKILL。从 kernel_space.py 可以看到保护环Protection Ring的设计Ring 0 内核最特权负责策略、审计、信号不可被 Agent 触碰Ring 1 驱动VFS 后端、工具执行器等驱动层Ring 2 服务监控、健康检查等系统服务Ring 3 用户态Agent 代码权限最低用户态与内核态的交互全部通过系统调用完成SyscallType枚举覆盖了进程控制SYS_FORK/SYS_EXIT/SYS_EXEC、文件操作SYS_READ/SYS_WRITE、内存操作、IPC、信号操作与策略查询SYS_GETPOLICY/SYS_CHECKPOLICY等类型。所有 Agent 动作必须走 syscall这保证了无旁路No Bypass这一核心不变量。内核空间由哪些组件构成在 kernel_space.py 的模块文档中内核态与用户态被明确划分内核态受保护Agent 崩溃也能存活Policy Engine —— 策略执行Flight Recorder —— 审计日志防篡改Signal Dispatcher —— 信号控制VFS Mount Manager —— 内存管理IPC Router —— 通信路由用户态LLM 生成工具执行Agent 逻辑自定义 handler对照 kernel-internals.md 中的四大核心不变量无旁路No Bypass所有 Agent I/O 都走 syscall失败关闭Fail Closed未知动作一律拒绝全量审计Audit Everything飞行记录器记录所有决策崩溃隔离Crash Isolation用户态崩溃不影响内核。策略模式详解官方 Quick Reference 提供了三种策略模式对应KernelSpace的构造参数# Strict - blocks writes, PII, shell commands kernel KernelSpace(policystrict) # Permissive - logs only, no blocking kernel KernelSpace(policypermissive) # Custom - your own rules kernel KernelSpace(policy_filemy-policies.yaml)strict默认拦截写操作、PII个人身份信息、shell 命令等高风险动作——这也是本文 Step 4 中os.remove(/etc/passwd)被归类为file_write并触发SIGKILL的原因permissive只记录、不拦截适合灰度观察阶段自定义模式通过policy_file指向 YAML 策略文件。YAML 策略文件示例参考 first-governed-agent.md一个典型的.agents/security.md策略文件长这样kernel: version: 1.0 mode: strict signals: enabled: - SIGSTOP # Pause for human review - SIGKILL # Terminate on violation - SIGCONT # Resume after review policies: # Only allow reading from /data directory - name: sandboxed_reads allow: - action: file_read paths: - ./data/** deny: - action: file_read paths: - /** # Deny all other reads # Block all writes - name: read_only deny: - action: file_write - action: file_delete # Block network except allowed APIs - name: network_restricted allow: - action: http_request domains: - api.openai.com - api.anthropic.com deny: - action: http_request # Block dangerous patterns in output - name: no_sensitive_data deny: - action: output patterns: - \\b\\d{3}-\\d{2}-\\d{4}\\b # SSN - \\b\\d{16}\\b # Credit card - password\\s*[:] # Passwords audit: enabled: true log_path: ./logs/audit.log include: - all_actions - policy_checks - signals策略引擎的底层判定逻辑在无状态内核 stateless.py 中可以看到内置策略的声明式定义DEFAULT_POLICIES { read_only: { blocked_actions: [file_write, database_write, send_email], constraints: {database_query: {mode: read}} }, no_pii: { blocked_patterns: [ssn, social_security, credit_card, password] }, strict: { require_approval: [send_email, file_write, code_execution] } }判定流程_check_policies依次执行三类检查blocked_actions动作名是否命中禁用列表命中即拒绝blocked_patterns把请求参数序列化后做关键词/正则匹配拦截 PII 与危险 SQL 模式如drop table、delete from、; or 11并额外通过CredentialRedactor对参数中的每个字符串值做真实的 PII 格式检测SSN、信用卡号、邮箱、手机号等require_approval高风险动作要求受信任审批——调用方自行携带的approved标志会被剥离并忽略只有通过可信 IntentManager 提供的已审批intent_id才能放行且内核在构造时会计算所有策略的审批动作并集即使调用方传空策略列表也无法绕过见 stateless.py。更细粒度的策略能力若需要超越严格/宽松两级可参考 policy-schema.md 中PolicyEngine的编程式 APIAllow-list 约束最安全engine.add_constraint(data-analyst, [file_read, database_query, api_call])只允许显式授权的工具ABAC 条件权限如仅对已验证用户、金额 ≤ 1000 的退款放行通过ConditionalPermissionCondition实现资源配额ResourceQuota支持每分钟/每小时请求数、单次执行时长、最大并发数等限流参数风险策略RiskPolicy支持风险评分阈值如max_risk_score0.8、require_approval_above0.5、deny_above0.9、高风险正则模式以及域名白/黑名单。内置保护始终生效包括路径穿越防护拦截..、/etc/、C:\Windows\System32等、危险代码模式拦截rm -rf、DROP TABLE、无 WHERE 的DELETE FROM、SQL 注入清洗去注释、检测多语句。CLI 命令速查官方 Quick Reference 提供了四个常用命令agentos init my-project # Create new project agentos run # Run with kernel agentos check src/ # Check for violations agentos audit # Audit policiesCLI 的实现位于 cli 目录cmd_init.py、cmd_policy.py、cmd_audit.py、cmd_validate.py等。其中agentos init会生成标准项目骨架.agents/配置目录、agent.py、沙箱数据目录等agentos audit可查询飞行记录器的审计日志监控与审计类命令均支持--json标志便于对接 CI/CD 流水线。生产化进阶无状态内核如果你需要把治理能力部署到多实例环境Lambda、Cloud Run、K8s官方文档推荐使用无状态内核StatelessKernel。它的设计要点见 stateless.py 模块文档包括无会话状态每次请求自包含ExecutionContextagent_id、策略列表、历史、state_ref内核不保存进程内会话可插拔状态后端StateBackend协议通过结构化子类型structural subtyping定义get/set/delete内置MemoryBackend开发/测试用支持 TTL与RedisBackend生产用支持连接池、超时配置、键前缀命名空间水平扩展任何内核副本都能处理任何请求负载均衡后无需粘性会话弹性与可观测后端调用包在熔断器CircuitBreaker内后端故障时防止级联失败安装 OpenTelemetry 后每次execute()与后端操作都会输出 trace span。from agent_os import StatelessKernel, ExecutionContext kernel StatelessKernel() # Each call is independent result1 await kernel.execute( actiondatabase_query, params{query: SELECT * FROM users}, contextExecutionContext( agent_idagent-1, policies[read_only], history[] # Empty history ) ) # Pass updated context back for next call result2 await kernel.execute( actionapi_call, params{url: https://api.example.com}, contextresult1.updated_context # Contains history )每次调用返回的updated_context需要由调用方传递回下一次请求以维持对话连续性——这是无状态架构下状态显式化的代价与收益。进一步学习官方文档为你规划了清晰的进阶路线教程预计时间说明构建你的第一个受治理 Agent10 分钟完整实战文档分析 Agent 沙箱策略 可观测性使用消息总线适配器10 分钟通过 Redis/Kafka 连接多个 Agent创建自定义工具15 分钟构建安全工具多 Agent 治理案例研究15 分钟碳审计多 Agent 演示同时仓库内还有更深入的参考文档可供查阅内核原理Kernel Internalssyscall、信号、VFS、状态外置的完整设计策略 Schema 参考策略 JSON Schema、PolicyEngine API、条件操作符与内置防护安全规格说明Security Spec.agents/security.md的 YAML 格式规范快速开始Quickstart基于KernelSpace/AgentKernel的另一种上手路径含 ABAC 条件权限示例。小结通过本文的 5 分钟流程你已经完成了从安装到验证策略强制的完整闭环KernelSpace构建内核、kernel.register注册 Agent、kernel.execute走受治理执行路径一次os.remove(/etc/passwd)触发file_write违规并被SIGKILL终止——整个过程无需 Agent 自觉配合拦截发生在动作执行之前。这套用户态执行、内核态判定、信号强制终止、飞行记录器全量审计的模型正是 Agent OS 把 AI Agent 治理从建议升级为强制的根基。【免费下载链接】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），仅供参考