Agent OS Quickstart 实战：用 Agent OS 内核构建你的第一个受治理 AI Agent

Agent OS Quickstart 实战用 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本指南以 Agent OS 官方 Quickstart 示例为主线带你从零运行第一个受内核级安全策略保护的 AI Agent并深入剖析其背后的StatelessKernel执行内核、内置策略体系read_only/no_pii/strict与可插拔状态后端。读完你将掌握如何创建带策略约束的执行上下文、如何区分被允许的安全动作与被内核阻断的危险动作、以及如何从当前仓库的其他示例与教程继续进阶。快速开始运行 Quickstart 示例Quickstart 示例位于 agent-governance-python/agent-os/examples/quickstart/其中my_first_agent.py是一个完整的、可独立运行的最小受治理 Agent。从仓库根目录执行python agent-governance-python/agent-os/examples/quickstart/my_first_agent.py脚本顶部注释明确写明了运行前提pip install agent-os-kernel python my_first_agent.py即先安装agent-os-kernel包。示例本身不依赖任何外部服务或配置文件安装依赖后即可直接运行它会依次演示三类执行结果Safe action: successTrue Blocked (write): successFalse signalSIGKILL Blocked (PII): successFalse signalSIGKILL这三行输出浓缩了 Agent OS 的核心价值合法动作放行、越权动作拦截、敏感内容拦截全部发生在内核层面无需在 Agent 业务代码里手写任何 if-else 安全检查。理解示例代码两种 API 风格官方 Quickstart 文档给出了一个高度凝练的 API 骨架用KernelSpace配合kernel.register装饰器注册异步 Agent 函数from agent_os import KernelSpace # Create kernel with strict policy kernel KernelSpace(policystrict) kernel.register async def my_first_agent(task: str): A simple agent that processes tasks safely. result fProcessed: {task} return result # Execute with kernel-level safety result asyncio.run(kernel.execute(my_first_agent, Hello Agent OS!))需要说明的是KernelSpace属于 Agent OS 的可选 Control Plane 组件由agent_control_plane包提供参见 agent_os/init.py 中条件导入部分当该包未安装时内核会自动降级。而当前仓库中examples/quickstart/my_first_agent.py实际采用的主流写法是StatelessKernel无状态内核——这也是 Agent OS 5.x 推荐、面向 MCPModel Context Protocol演进方向的执行内核import asyncio from agent_os.stateless import StatelessKernel, ExecutionContext async def main(): # Create kernel with default safety policies kernel StatelessKernel() ctx ExecutionContext(agent_idmy-first-agent, policies[read_only, no_pii]) # Safe action - kernel allows it result await kernel.execute(respond, {message: Hello Agent OS!}, ctx) print(fSafe action: success{result.success}) # Dangerous action - kernel blocks file_write under read_only policy result await kernel.execute(file_write, {path: /tmp/data}, ctx) print(fBlocked (write): success{result.success} signal{result.signal}) # PII violation - kernel blocks content containing password result await kernel.execute(respond, {message: passwordabc123}, ctx) print(fBlocked (PII): success{result.success} signal{result.signal}) if __name__ __main__: asyncio.run(main())两种风格共享同一设计理念Agent 只声明想做什么action和以什么身份、受哪些策略约束ExecutionContext是否允许执行完全由内核裁决。下面的章节将以StatelessKernel为主线做源码级展开。内核级安全的三道关卡StatelessKernel的核心入口是execute(action, params, context)其完整实现位于 agent_os/stateless.py。从_execute_inner的执行顺序可以看到一次请求要依次通过三道检查策略检查_check_policies按ExecutionContext.policies列表中声明的策略名逐一比对全局审批门禁_enforce_global_approval对任何已加载策略标记为require_approval的动作强制生效——即使调用方传了空的policies[]也无法绕过这一设计在源码注释中被明确称为empty-policies-bypass 防御可选意图授权intent check仅当上下文携带intent_id且内核配置了intent_manager时启用用于基于意图的授权intent-based authorization。任一关卡失败都会返回ExecutionResult(successFalse, signalSIGKILL)动作执行器抛出异常则返回signalSIGTERM。信号语义与 examples/chat-agent/policies.yaml 中signals声明SIGSTOP暂停待人工审核、SIGKILL违规终止、SIGCONT审核后恢复一脉相承。内置策略详解read_only、no_pii 与 strictStatelessKernel自带三套开箱即用的默认策略DEFAULT_POLICIES见 agent_os/stateless.pyQuickstart 示例正是利用它们演示了安全/危险两种截然不同的结果策略名核心规则Quickstart 中的效果read_only阻止file_write、database_write、send_email约束database_query只能以只读模式执行file_write被拦截返回SIGKILLno_pii在请求参数中匹配ssn、social_security、credit_card、password等敏感模式含passwordabc123的响应请求被拦截strictsend_email、file_write、code_execution必须经过审批approval高危动作默认不放行其中no_pii的检测并非简单的子串匹配源码中_check_policies在关键词命中之外还会调用CredentialRedactor.find_pii_matches来自 agent_os/credential_redactor.py对参数中每个字符串值做正则级 PII 识别——真实格式的 SSN、信用卡号、邮箱、电话号码都会被拦截而不仅是命中 password 这样的关键词。这一关键词 格式识别双层设计是为了防止lesson包含sson之类的子串误伤源码注释对此有专门说明。策略是可扩展的StatelessKernel(policies{...})会与默认策略做字典合并{**DEFAULT_POLICIES, **(policies or {})}因此你可以按相同结构新增自定义策略名或覆盖默认策略的规则。更复杂的声明式策略YAML 形式支持内容过滤正则、限流、审计配置可参考 examples/chat-agent/policies.yaml。ExecutionContext一次请求携带全部状态ExecutionContext是无状态设计的关键数据结构字段定义见 agent_os/stateless.pyagent_id请求方 Agent 的唯一标识必填policies本次执行要强制生效的策略名列表如[read_only, no_pii]history本次会话此前动作的时序列表每条含action、timestamp、success由内核在成功执行后自动追加state_ref可选的外部化状态引用键。存在时内核先加载该状态再执行动作返回state_update后写回metadata透传的任意元数据intent_id可选的意图标识用于启用基于意图的授权。内核不维护任何会话状态因此调用方必须把上一次ExecutionResult.updated_context传入下一次请求以维持对话连续性——这既是约束也是特性它让任意内核实例都能处理任意请求。状态后端与水平扩展无状态内核的状态外置通过StateBackend协议实现结构化子类型任何实现get/set/delete三个异步方法的对象都满足契约内置两种实现MemoryBackend进程内字典 单调时钟 TTL仅供开发与测试重启即丢、多副本不共享RedisBackend生产级后端支持连接池默认pool_size10、连接/读超时默认 5s / 10s、失败重试并通过RedisConfig配置。所有 key 以可配置命名空间前缀默认agent-os:隔离值统一 JSON 序列化。值得注意的安全细节RedisConfig.to_url()刻意不把密码拼进 URL而是通过客户端password关键字单独传入避免异常日志、连接层日志泄露凭据。所有后端调用都经CircuitBreaker熔断器包装见 agent_os/circuit_breaker.py后端连续失败时熔断器打开内核直接返回CircuitBreakerOpen而不继续击穿后端防止级联故障。接入方式from agent_os.stateless import StatelessKernel, RedisBackend kernel StatelessKernel(backendRedisBackend(urlredis://localhost:6379))正因内核不保存任何进程内状态你可以随意横向扩展N 个内核副本挂在负载均衡器后面无需粘性会话sticky session任何实例都能处理任何请求。这是 agent_os/stateless.py 模块文档明确给出的架构目标。一分钟上手stateless_execute 便捷函数对于简单脚本和测试无需手动组装内核与上下文可直接使用顶层便捷函数stateless_execute同样导出在 agent_os/stateless.pyfrom agent_os.stateless import stateless_execute result await stateless_execute( actiondatabase_query, params{query: SELECT * FROM users}, agent_idanalyst-001, policies[read_only], ) print(result.success) # True该函数内部会创建一个临时的StatelessKernel与ExecutionContext适合一次性执行场景。更多调用与信号语义的断言可参考内核测试用例例如 tests/test_stateless.py、tests/test_kernel_critical.py。下一步官方推荐的学习路线Quickstart 只是起点仓库按渐进难度提供了完整的示例矩阵与教程最小可运行示例先看 examples/hello-world/agent.py——它演示了同样的StatelessKernelread_only策略下安全动作放行 / 写/etc/passwd被拦的最小闭环自定义策略参考 examples/chat-agent/——policies.yaml给出了内容过滤、PII 拦截、LLM 调用限流与审计日志的完整声明式配置完整应用查看 examples/demo-app/了解一个带内核治理的完整 Agent 应用如何组装Jupyter 教程进入 notebooks/跟随交互式笔记本逐章实践策略执行、MCP 安全代理与多 Agent 治理。小结通过 Quickstart 示例你可以用不到 20 行代码让 Agent 获得内核级安全护栏策略声明与业务逻辑完全解耦危险动作与敏感内容在进入业务代码之前就被SIGKILL拦截同时无状态架构保证了多副本水平扩展的可行性。无论是想快速验证 Agent OS 的安全模型还是以此为起点构建生产级受治理 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），仅供参考