尧图网页设计 
Agent OS 入门指南用 StatelessKernel 与 read_only 策略构建你的第一个受治理 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-toolkitAgent OS 是 agent-governance-python 仓库中一套面向自治 AI Agent 的运行时治理内核核心思想是让所有 Agent 动作都必须流经内核在内核中完成策略检查后再决定放行或阻断。本文以仓库中的demo-app示例README 与 agent.py为骨架完整讲解一个 Agent、一个策略、一个任务的最小可运行范例并深入StatelessKernel源码讲清策略在底层究竟是如何被检查与执行的。读完本文你将掌握 Agent OS 内核的标准调用模式构造内核 → 创建执行上下文 → 通过execute提交动作并能在自己的 Python 3.10 环境中复现一次完整的治理执行过程。示例概览Agent OS 的最小治理闭环demo-app是整个 Agent OS 示例集中最简单、最完整的入门样例。它的设计目标是零外部依赖只使用一个StatelessKernel无状态内核定义一个简单的 Agent 函数让任务在read_only只读策略约束下经过内核处理并打印结果。这个示例完整展示了 Agent OS 的核心模式内核拦截process_task动作 → 对照声明的策略进行检查 → 决定放行或阻断执行。正如 examples/README.md 中All Examples表格所标注的demo-app被归类为Full demo application与quickstart单文件入门、hello-world15 行最小示例同属Getting Started级别适合作为理解整个治理模型的第一站。从仓库结构看demo-app目录下只有两个文件README.md—— 运行说明文档agent.py—— 完整的可运行示例代码。整个示例不需要配置文件、不需要 Docker、不需要外部消息总线启动成本几乎为零。前置条件与安装运行demo-app需要满足以下条件Python 3.10内核源码中大量使用X | None联合类型语法如ExecutionContext的state_ref: str | None None因此必须使用 Python 3.10 及以上版本。安装 Agent OS 包需要从仓库源码以开发模式editable安装推荐命令pip install -e agent-os[dev][dev]扩展会同时安装开发/测试依赖。如果你只需要运行示例而不做二次开发也可以只安装核心包但官方 README 推荐了带dev的完整安装方式。安装时请确保在包含agent-os包目录的工作区环境下执行。如何运行进入示例目录并直接运行脚本即可cd agent-governance-python/agent-os/examples/demo-app python agent.py整个执行过程是异步的asyncio.run(main())驱动无需任何网络连接或外部服务。预期输出解读正常执行后终端会输出如下内容[Agent OS] Demo [OK] Result: Processed: HELLO, AGENT OS! Success! Your agent ran safely under kernel governance! The kernel checked the read_only policy before execution.这五行输出对应main()中的三段打印逻辑前两行是 banner[Agent OS] Demo与 40 个分隔符[OK] Result: ...是 Agent 函数的返回值——注意原始输入Hello, Agent OS!被转成了大写这正是内核放行后动作处理器实际执行的结果最后两行是引导性提示说明整个流程经历了策略检查 → 放行 → 执行三个环节。这里的Result成功打印本身就证明了read_only策略检查通过动作process_task不在被阻断列表里且参数中不含敏感模式因此内核返回successTrue。代码逐行解析一个受治理 Agent 的完整写法agent.py全文约 40 行是理解 Agent OS 编程模型的最佳范本。核心结构如下import asyncio from agent_os import StatelessKernel, ExecutionContext # 创建无状态内核零外部依赖 kernel StatelessKernel() async def my_agent(task: str) - str: 通过内核安全地处理任务。 # 创建执行上下文 ctx ExecutionContext( agent_iddemo-agent, policies[read_only] # 应用安全策略 ) # 通过内核执行 result await kernel.execute( actionprocess_task, params{task: task, output: fProcessed: {task.upper()}}, contextctx ) return result.data if result.success else fError: {result.error} async def main(): print([Agent OS] Demo) print( * 40) result await my_agent(Hello, Agent OS!) print(f[OK] Result: {result}) print() print(Success! Your agent ran safely under kernel governance!) print() print(The kernel checked the read_only policy before execution.) if __name__ __main__: asyncio.run(main())这段代码包含三个关键环节1. 构造内核第 8 行StatelessKernel()不传任何参数。从 stateless.py 的构造函数可以看出此时内核会使用默认的MemoryBackend()作为状态后端self.backend backend or MemoryBackend()将内置默认策略合并进self.policiesself.policies {**self.DEFAULT_POLICIES, **(policies or {})}根据是否传入enable_tracing决定是否启用 OpenTelemetry 追踪示例中未启用构建一个全局的需审批动作集合_globally_protected_actions用于防御性地兜底审批门禁。2. 创建执行上下文第 14-17 行ExecutionContext携带了agent_id请求方唯一标识和policies要执行的策略名列表。从 ExecutionContext 定义 可以看到它还可以携带history会话历史、state_ref外部化状态的引用键、metadata透传元数据和intent_id基于意图的授权可选开启。内核本身不保存任何会话状态所有必要信息都通过这个上下文对象随请求传入——这正是无状态设计的体现。3. 通过内核执行动作第 20-24 行kernel.execute()是内核的唯一主入口接收动作名action、参数params和上下文context。返回值是ExecutionResult成功时successTrue且data为动作结果策略违规时successFalse且error携带原因、signalSIGKILL执行出错时signalSIGTERM。示例中的my_agent对这两种失败路径都做了处理返回Error: ...。源码原理策略到底是怎么被检查的demo-app演示的策略是read_only它的定义就在内核的默认策略表里。查看 stateless.py 的 DEFAULT_POLICIESDEFAULT_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] } }可见read_only策略的定义包含两类规则blocked_actions禁止的动作列表。file_write写文件、database_write写数据库、send_email发邮件都属于写类动作符合只读语义constraints约束条件例如对database_query强制mode: read。此外内核还内置了no_pii禁止 PII 敏感模式与strict高危动作需审批两个默认策略demo-app只启用了其中一个。从 execute 方法 的主流程看一次动作执行会经过以下步骤若上下文中存在state_ref先从后端加载外部状态调用_check_policies对action、params和策略列表做逐项检查检查未通过则直接返回successFalse, signalSIGKILL的ExecutionResult检查通过后再经过全局审批门禁_enforce_global_approval与可选的意图校验intent_id剥离调用方传入的任何approved类标记防绕过最后执行动作并返回结果。其中策略检查的核心在 _check_policies它的检查逻辑按顺序分三层阻断动作检查如果action出现在策略的blocked_actions中立即拒绝并给出可操作建议如尝试只读动作或向管理员申请策略豁免敏感内容检查将params序列化为字符串后检查是否命中blocked_patterns如ssn、password还会通过CredentialRedactor做第二遍正则级 PII 识别真实的 SSN、信用卡形状数字、邮箱、手机号等也就是说关键词 格式识别双重防御审批门禁检查如果动作在策略的require_approval列表中则必须依赖可信的IntentManager返回was_plannedTrue的已审批intent_id才能放行——调用方自己伪造的approved标记一律被忽略并记录告警日志。以demo-app为例动作是process_task它不在read_only的blocked_actions中参数{task: ..., output: ...}不含敏感模式也不触发 PII 检测且read_only没有require_approval规则。因此三层检查全部通过动作被放行内核继而调用_execute_action生成结果最终result.data返回Processed: HELLO, AGENT OS!示例成功收尾。关键数据模型ExecutionContext 与 ExecutionResultdemo-app只用到了ExecutionContext与ExecutionResult的少量字段但理解完整模型有助于后续扩展。这两者都是纯 Pythondataclassstateless.py 注释 明确说明刻意不用 Pydantic以保持核心内核零依赖。ExecutionContext的关键字段字段类型说明agent_idstr请求方 Agent 的唯一标识必填policieslist[str]要执行的策略名列表从内核的policies字典解析historylist[dict]会话内历史动作action/timestamp/successstate_refstr \| None外部化状态的引用键存在时内核执行前加载、执行后持久化metadatadict透传到结果的任意元数据intent_idstr \| None基于意图的授权标识可选ExecutionResult的关键字段字段类型说明successbool是否成功无策略违规且无执行错误dataAny动作返回值失败时为Noneerrorstr \| None失败原因的可读描述signalstr \| None失败信号策略违规为SIGKILL执行错误为SIGTERMupdated_contextExecutionContext \| None更新后的上下文含最新 history 与状态引用值得注意的是updated_context的设计无状态内核不维护会话调用方需要把上一次返回的updated_context传递到下一次请求中才能维持多轮对话的连续性。这是从demo-app单次任务走向多轮 Agent 时必须掌握的关键约定。另外每次execute调用内部会自动生成request_id对agent_id action 时间戳做 SHA-256 并截取前 16 位用于日志关联调用方无需手工指定。从 demo-app 出发下一步该看什么demo-app是整个 Agent OS 示例体系的入口。运行成功后官方 README 给出了三条进阶路径结合仓库实际情况整理如下尝试更多策略组合内核内置了read_only、no_pii、strict三个默认策略见 DEFAULT_POLICIES可以在ExecutionContext的policies列表中组合使用例如policies[read_only, no_pii]也可以参考 examples/agent_config.yaml 以及examples/policies相关目录中的策略样例体验更丰富的治理规则self-evaluating 示例对应examples/self-evaluating/展示 Agent 对自身输出质量进行评估的自改进模式governed-chatbot 示例对应examples/governed-chatbot/是带完整策略执行的多轮对话 Agent能进一步体会updated_context的上下文接力用法quickstart 与 hello-worldexamples/quickstart/my_first_agent.py与examples/hello-world/提供了更短小的变体适合对照加深理解。如果想深入验证内核的治理行为还可以阅读 tests 目录下的测试用例例如test_policy_enforcement.py其中覆盖了阻断动作、敏感内容检测、审批门禁等路径是理解StatelessKernel各分支行为的可靠参考。小结demo-app用 40 行代码完成了 Agent OS 治理模型的最小闭环构造无状态内核、声明read_only策略、让任务经内核执行。它的价值不在于功能丰富而在于把所有 Agent 动作必须流经内核、所有策略在内核中先于执行被检查这一核心范式以最直白的方式呈现出来。掌握这个模式后无论是切换策略、接入外部状态后端还是组合意图审批、可观测性追踪都可以在同一个execute主入口上平滑扩展。【免费下载链接】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），仅供参考 Agent OS 入门指南：用 StatelessKernel 与 read_only 策略构建你的第一个受治理 Agent
Agent OS 入门指南用 StatelessKernel 与 read_only 策略构建你的第一个受治理 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-toolkitAgent OS 是 agent-governance-python 仓库中一套面向自治 AI Agent 的运行时治理内核核心思想是让所有 Agent 动作都必须流经内核在内核中完成策略检查后再决定放行或阻断。本文以仓库中的demo-app示例README 与 agent.py为骨架完整讲解一个 Agent、一个策略、一个任务的最小可运行范例并深入StatelessKernel源码讲清策略在底层究竟是如何被检查与执行的。读完本文你将掌握 Agent OS 内核的标准调用模式构造内核 → 创建执行上下文 → 通过execute提交动作并能在自己的 Python 3.10 环境中复现一次完整的治理执行过程。示例概览Agent OS 的最小治理闭环demo-app是整个 Agent OS 示例集中最简单、最完整的入门样例。它的设计目标是零外部依赖只使用一个StatelessKernel无状态内核定义一个简单的 Agent 函数让任务在read_only只读策略约束下经过内核处理并打印结果。这个示例完整展示了 Agent OS 的核心模式内核拦截process_task动作 → 对照声明的策略进行检查 → 决定放行或阻断执行。正如 examples/README.md 中All Examples表格所标注的demo-app被归类为Full demo application与quickstart单文件入门、hello-world15 行最小示例同属Getting Started级别适合作为理解整个治理模型的第一站。从仓库结构看demo-app目录下只有两个文件README.md—— 运行说明文档agent.py—— 完整的可运行示例代码。整个示例不需要配置文件、不需要 Docker、不需要外部消息总线启动成本几乎为零。前置条件与安装运行demo-app需要满足以下条件Python 3.10内核源码中大量使用X | None联合类型语法如ExecutionContext的state_ref: str | None None因此必须使用 Python 3.10 及以上版本。安装 Agent OS 包需要从仓库源码以开发模式editable安装推荐命令pip install -e agent-os[dev][dev]扩展会同时安装开发/测试依赖。如果你只需要运行示例而不做二次开发也可以只安装核心包但官方 README 推荐了带dev的完整安装方式。安装时请确保在包含agent-os包目录的工作区环境下执行。如何运行进入示例目录并直接运行脚本即可cd agent-governance-python/agent-os/examples/demo-app python agent.py整个执行过程是异步的asyncio.run(main())驱动无需任何网络连接或外部服务。预期输出解读正常执行后终端会输出如下内容[Agent OS] Demo [OK] Result: Processed: HELLO, AGENT OS! Success! Your agent ran safely under kernel governance! The kernel checked the read_only policy before execution.这五行输出对应main()中的三段打印逻辑前两行是 banner[Agent OS] Demo与 40 个分隔符[OK] Result: ...是 Agent 函数的返回值——注意原始输入Hello, Agent OS!被转成了大写这正是内核放行后动作处理器实际执行的结果最后两行是引导性提示说明整个流程经历了策略检查 → 放行 → 执行三个环节。这里的Result成功打印本身就证明了read_only策略检查通过动作process_task不在被阻断列表里且参数中不含敏感模式因此内核返回successTrue。代码逐行解析一个受治理 Agent 的完整写法agent.py全文约 40 行是理解 Agent OS 编程模型的最佳范本。核心结构如下import asyncio from agent_os import StatelessKernel, ExecutionContext # 创建无状态内核零外部依赖 kernel StatelessKernel() async def my_agent(task: str) - str: 通过内核安全地处理任务。 # 创建执行上下文 ctx ExecutionContext( agent_iddemo-agent, policies[read_only] # 应用安全策略 ) # 通过内核执行 result await kernel.execute( actionprocess_task, params{task: task, output: fProcessed: {task.upper()}}, contextctx ) return result.data if result.success else fError: {result.error} async def main(): print([Agent OS] Demo) print( * 40) result await my_agent(Hello, Agent OS!) print(f[OK] Result: {result}) print() print(Success! Your agent ran safely under kernel governance!) print() print(The kernel checked the read_only policy before execution.) if __name__ __main__: asyncio.run(main())这段代码包含三个关键环节1. 构造内核第 8 行StatelessKernel()不传任何参数。从 stateless.py 的构造函数可以看出此时内核会使用默认的MemoryBackend()作为状态后端self.backend backend or MemoryBackend()将内置默认策略合并进self.policiesself.policies {**self.DEFAULT_POLICIES, **(policies or {})}根据是否传入enable_tracing决定是否启用 OpenTelemetry 追踪示例中未启用构建一个全局的需审批动作集合_globally_protected_actions用于防御性地兜底审批门禁。2. 创建执行上下文第 14-17 行ExecutionContext携带了agent_id请求方唯一标识和policies要执行的策略名列表。从 ExecutionContext 定义 可以看到它还可以携带history会话历史、state_ref外部化状态的引用键、metadata透传元数据和intent_id基于意图的授权可选开启。内核本身不保存任何会话状态所有必要信息都通过这个上下文对象随请求传入——这正是无状态设计的体现。3. 通过内核执行动作第 20-24 行kernel.execute()是内核的唯一主入口接收动作名action、参数params和上下文context。返回值是ExecutionResult成功时successTrue且data为动作结果策略违规时successFalse且error携带原因、signalSIGKILL执行出错时signalSIGTERM。示例中的my_agent对这两种失败路径都做了处理返回Error: ...。源码原理策略到底是怎么被检查的demo-app演示的策略是read_only它的定义就在内核的默认策略表里。查看 stateless.py 的 DEFAULT_POLICIESDEFAULT_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] } }可见read_only策略的定义包含两类规则blocked_actions禁止的动作列表。file_write写文件、database_write写数据库、send_email发邮件都属于写类动作符合只读语义constraints约束条件例如对database_query强制mode: read。此外内核还内置了no_pii禁止 PII 敏感模式与strict高危动作需审批两个默认策略demo-app只启用了其中一个。从 execute 方法 的主流程看一次动作执行会经过以下步骤若上下文中存在state_ref先从后端加载外部状态调用_check_policies对action、params和策略列表做逐项检查检查未通过则直接返回successFalse, signalSIGKILL的ExecutionResult检查通过后再经过全局审批门禁_enforce_global_approval与可选的意图校验intent_id剥离调用方传入的任何approved类标记防绕过最后执行动作并返回结果。其中策略检查的核心在 _check_policies它的检查逻辑按顺序分三层阻断动作检查如果action出现在策略的blocked_actions中立即拒绝并给出可操作建议如尝试只读动作或向管理员申请策略豁免敏感内容检查将params序列化为字符串后检查是否命中blocked_patterns如ssn、password还会通过CredentialRedactor做第二遍正则级 PII 识别真实的 SSN、信用卡形状数字、邮箱、手机号等也就是说关键词 格式识别双重防御审批门禁检查如果动作在策略的require_approval列表中则必须依赖可信的IntentManager返回was_plannedTrue的已审批intent_id才能放行——调用方自己伪造的approved标记一律被忽略并记录告警日志。以demo-app为例动作是process_task它不在read_only的blocked_actions中参数{task: ..., output: ...}不含敏感模式也不触发 PII 检测且read_only没有require_approval规则。因此三层检查全部通过动作被放行内核继而调用_execute_action生成结果最终result.data返回Processed: HELLO, AGENT OS!示例成功收尾。关键数据模型ExecutionContext 与 ExecutionResultdemo-app只用到了ExecutionContext与ExecutionResult的少量字段但理解完整模型有助于后续扩展。这两者都是纯 Pythondataclassstateless.py 注释 明确说明刻意不用 Pydantic以保持核心内核零依赖。ExecutionContext的关键字段字段类型说明agent_idstr请求方 Agent 的唯一标识必填policieslist[str]要执行的策略名列表从内核的policies字典解析historylist[dict]会话内历史动作action/timestamp/successstate_refstr \| None外部化状态的引用键存在时内核执行前加载、执行后持久化metadatadict透传到结果的任意元数据intent_idstr \| None基于意图的授权标识可选ExecutionResult的关键字段字段类型说明successbool是否成功无策略违规且无执行错误dataAny动作返回值失败时为Noneerrorstr \| None失败原因的可读描述signalstr \| None失败信号策略违规为SIGKILL执行错误为SIGTERMupdated_contextExecutionContext \| None更新后的上下文含最新 history 与状态引用值得注意的是updated_context的设计无状态内核不维护会话调用方需要把上一次返回的updated_context传递到下一次请求中才能维持多轮对话的连续性。这是从demo-app单次任务走向多轮 Agent 时必须掌握的关键约定。另外每次execute调用内部会自动生成request_id对agent_id action 时间戳做 SHA-256 并截取前 16 位用于日志关联调用方无需手工指定。从 demo-app 出发下一步该看什么demo-app是整个 Agent OS 示例体系的入口。运行成功后官方 README 给出了三条进阶路径结合仓库实际情况整理如下尝试更多策略组合内核内置了read_only、no_pii、strict三个默认策略见 DEFAULT_POLICIES可以在ExecutionContext的policies列表中组合使用例如policies[read_only, no_pii]也可以参考 examples/agent_config.yaml 以及examples/policies相关目录中的策略样例体验更丰富的治理规则self-evaluating 示例对应examples/self-evaluating/展示 Agent 对自身输出质量进行评估的自改进模式governed-chatbot 示例对应examples/governed-chatbot/是带完整策略执行的多轮对话 Agent能进一步体会updated_context的上下文接力用法quickstart 与 hello-worldexamples/quickstart/my_first_agent.py与examples/hello-world/提供了更短小的变体适合对照加深理解。如果想深入验证内核的治理行为还可以阅读 tests 目录下的测试用例例如test_policy_enforcement.py其中覆盖了阻断动作、敏感内容检测、审批门禁等路径是理解StatelessKernel各分支行为的可靠参考。小结demo-app用 40 行代码完成了 Agent OS 治理模型的最小闭环构造无状态内核、声明read_only策略、让任务经内核执行。它的价值不在于功能丰富而在于把所有 Agent 动作必须流经内核、所有策略在内核中先于执行被检查这一核心范式以最直白的方式呈现出来。掌握这个模式后无论是切换策略、接入外部状态后端还是组合意图审批、可观测性追踪都可以在同一个execute主入口上平滑扩展。【免费下载链接】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），仅供参考