基于 Agent Governance Toolkit 的 AI Agent 治理工作坊：Facilitator 主持全攻略

基于 Agent Governance Toolkit 的 AI Agent 治理工作坊Facilitator 主持全攻略【免费下载链接】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导读本文是面向工作坊主持人Facilitator的完整主持指南以 docs/workshop/facilitator-notes.md 为核心骨架结合仓库内全部工作坊配套材料讲义、实验脚本、Manifest、Rego 策略与 AgentMesh 源码展开。你将掌握 90 分钟AI Agent 治理入门工作坊的时间编排、课前准备清单、两大动手实验原生 ACS 策略评估、多 Agent 信任握手的讲授要点与常见问题排查以及如何引导学员理解策略评估与身份信任两条独立控制平面的本质区别。一、工作坊总体设计90 分钟、两个实验、一条主线本工作坊的目标不是堆砌概念而是让参与者亲手完成一次策略拦截和一次信任握手从而建立对 AI Agent 治理的最小心智模型。整体结构参见 docs/workshop/README.md时长 90 分钟难度 Beginner–Intermediate形式为幻灯片讲解 动手实验。1.1 时间编排核心骨架来自 facilitator-notes.md 的官方时间表时段内容时长开场治理概念与原生 ACS 讲解20 分钟Lab 1原生策略评估native policy25 分钟中场身份与信任概念讲解15 分钟Lab 2多 Agent 信任multi-agent trust25 分钟收尾总结与讨论Wrap-up5 分钟对应到 docs/workshop/slides.md 的幻灯片节奏前 20 分钟讲为什么需要治理Agent 动作会产生外部副作用、提示词指令不是授权边界、策略/身份/隔离/审计/可靠性解决的是不同问题中间 15 分钟切换到 AgentMesh 身份与信任收尾 5 分钟讲Fail closed与生产清单。1.2 工作坊材料清单主持人需提前熟悉文件仓库根相对路径用途docs/workshop/slides.md覆盖原生策略与信任概念的幻灯片docs/workshop/lab-guide.md参与者实验指南2 个动手练习docs/workshop/facilitator-notes.md主持人指南讲授要点、时间与常见问题docs/workshop/prerequisites.md参与者准备清单提前 48 小时发送docs/workshop/labs/lab1_first_policy.pyLab 1 原生 ACS 策略实验脚本docs/workshop/labs/lab1-manifest.yamlLab 1 Manifest策略绑定声明docs/workshop/labs/lab1-policy.regoLab 1 Rego 策略三条 deny 条件docs/workshop/labs/lab2_multi_agent_trust.pyLab 2 多 Agent 信任实验模板二、课前准备Before the Session主持人核对清单facilitator-notes.md 明确要求主持人在课前完成四件事任何一项缺失都会直接影响实验环节在实验环境里把两个实验脚本各跑一遍即lab1_first_policy.py与lab2_multi_agent_trust.py确认输出与预期一致。这是主持人最有价值的一次预演——自己踩过的坑才能预判参与者的坑。确认 OPA 与原生 ACS Python SDK 可用Lab 1 的 Rego 策略依赖 OPAOpen Policy Agent进程执行agent_control_specification包提供 Manifest 解析与运行时。两个组件缺一不可。至少提前 48 小时把 docs/workshop/prerequisites.md 发给参与者。把 docs/workshop/lab-guide.md 放在幻灯片旁边随时查阅方便现场快速定位下一步做什么。2.1 参与者的 48 小时准备清单prerequisites.md 是发给参与者的完整安装手册主持人应在课前逐项确认硬件可联网笔记本macOS / Linux / Windows 10/11Windows 强烈建议 WSL2至少 2 GB 可用磁盘空间。Python 3.10python --version校验Windows 用户安装时勾选 Add Python to PATH。虚拟环境与依赖python -m venv agt-workshop source agt-workshop/bin/activate # macOS / Linux # agt-workshop\Scripts\activate # Windows PowerShell pip install agent-governance-toolkit[full]安装验证三连三条都应打印 ✅python -c from agent_control_specification import validate_manifest; print(✅ native policy API OK) python -c from agentmesh import AgentIdentity; print(✅ agentmesh-platform OK) python -c import agent_governance; print(✅ agent-governance-toolkit OK)自测脚本prerequisites 还附带一个综合自检片段同时验证parse_manifest、AgentIdentity.create可生成did:mesh:...格式的 DID与AuditLog三个核心 API主持人可建议参与者在到场前完成。2.2 主持人专属环境预检命令结合 lab1_first_policy.py 的启动逻辑AgentControl.from_path(str(manifest))主持人可在课前执行python docs/workshop/labs/lab1_first_policy.py预期输出为 5 行verdict 工具名 token 数 reason的结果。若脚本报错99% 是以下三类问题也是现场最常见的求助OPA 不在PATH中原生 ACS 包未安装pip install agent-governance-toolkit[full]未完成Manifest 的 bundle 路径被改动但 Rego 文件没有一起移动见下文 Lab 1 常见问题。三、开场 20 分钟治理概念与原生 ACS 讲解要点开场幻灯片要讲清一个核心立场提示词指令不是授权边界Prompt instructions are not an authorization boundary。Agent 的动作会产生真实的外部副作用因此必须由策略、身份、隔离、审计、可靠性各司其职。3.1 原生 ACS 的声明式模型讲解 ACSAgent Control SpecificationManifest 时主持人应强调它声明了六类内容策略引擎与 bundlepolicy engines and bundles干预点绑定intervention-point bindings工具目录tool catalogs转换与证据transforms and evidence审批approval限制limits。3.2 运行时模型与工具中介Tool Mediation幻灯片给出了最小运行时模型主持人应现场演示这段代码与 Lab 1 脚本同源from agent_control_specification import AgentControl, HostSession runtime AgentControl.from_path(policies/manifest.yaml) session HostSession( runtime, agent_idagent-1, session_idsession-1, )以及工具调用如何被中介evaluation session.pre_tool_call( tool_namedelete_file, args{path: report.txt}, )这里必须强调一个安全原则在干预点评估完成之前不会发生任何副作用。这正是 lab1_first_policy.py 中session.input(...)的设计意图——所有工具调用都以输入形式进入干预点先裁决、后执行。3.3 结果契约Result ContractPolicyEvaluation返回对象携带的关键字段主持人应逐一指出裁决结果与原因码verdict and reason code转换与证据transform and evidence输入与强制身份input and enforced identities审批元数据approval metadata受限的审计负载restricted audit payload。可以延伸说明这部分与仓库的 Fail-closed 设计一致——运行时错误、审批错误、动作与身份不匹配都会直接 deny且对外错误信息保持脱敏详见 slides.md 的 Fail closed 页。四、Lab 125 分钟原生 ACS 策略评估的主持要点4.1 核心讲解点四层分离与输入即干预点facilitator-notes.md 为 Lab 1 指定的核心讲授重点是强调 Manifest、Rego 策略、运行时、会话session之间的分离。主持人要引导参与者思考一个关键问题为什么工具调用被表示为干预点的输入而不是一个内联的规则对象inline rule object答案指向架构意图策略与执行解耦。Manifest 只声明哪个干预点绑定了哪份策略Rego 只负责裁决运行时AgentControl负责加载与调度HostSession负责承载一次会话的计数与状态。任何一方都可以独立替换或审计——这正是 lab1-manifest.yaml 的呈现方式agent_control_specification_version: 0.4.0-alpha.1 metadata: name: workshop-lab1 version: 1.0 extends: [] policies: workshop: type: rego bundle: . query: data.agt.workshop.lab1.result intervention_points: input: policy_target: $.input.body policy: id: workshop可以看到策略绑定intervention_points.input.policy指向id: workshop策略目标policy_target指向输入体的$.input.body而裁决入口是 Rego 查询data.agt.workshop.lab1.result。Manifest 是策略绑定的唯一所有者——Lab 讨论题为什么 Manifest 拥有策略绑定的答案就在这里。4.2 三条 deny 条件的源码级拆解lab1-policy.rego 定义了三个 deny 条件与一个兜底 allow主持人应引导参与者逐个识别package agt.workshop.lab1 import rego.v1 result : { decision: deny, reason: code_execution_blocked, } if { input.policy_target.value.tool_name execute_code } else : { decision: deny, reason: write_operation_blocked, } if { startswith(input.policy_target.value.tool_name, write_) } else : { decision: deny, reason: token_budget_exceeded, } if { input.policy_target.value.token_count 2000 } else : { decision: allow, reason: safe, }三条 deny 条件分别是code_execution_blocked工具名恰为execute_code精确匹配write_operation_blocked工具名以write_开头前缀匹配覆盖写类操作token_budget_exceededtoken_count 2000预算控制基于数值比较。注意 Rego 的else :链式结构按顺序短路求值命中第一条即返回对应 reason。input.policy_target.value正是 Manifest 中policy_target: $.input.body映射后的值这也是 Lab 1 第 5 步新增一条 deny 条件时参与者需要理解的输入字段路径。4.3 运行实验与预期输出实验脚本 lab1_first_policy.py 内置了 5 个场景工具名 token 数SCENARIOS ( (read_customer_data, 100), # 预期 allow (execute_code, 50), # 预期 deny: code_execution_blocked (write_database, 200), # 预期 deny: write_operation_blocked (read_reports, 3000), # 预期 deny: token_budget_exceeded (read_inventory, 150), # 预期 allow )运行方式python docs/workshop/labs/lab1_first_policy.py执行流程为AgentControl.from_path加载 Manifest → 构造HostSession(agent_idworkshop-agent, session_idlab1)→ 对每个场景调用session.input(body{tool_name: ..., token_count: ...})→ 打印verdict / tool_name / tokens / reason。主持人应让参与者确认execute_code、write_database、超预算的读取read_reports3000 2000三者都被 deny。随后布置开放任务在lab1-policy.rego中新增一条 deny 条件重跑脚本并解释策略读取的是输入中的哪个字段——这能检验参与者是否真正理解了input.policy_target.value的映射关系。4.4 Lab 1 常见问题与排查主持人口袋清单来自 facilitator-notes.md现场最高频的三个问题症状原因处理脚本报错找不到 OPAOPA 不在PATH安装 OPA 并确认opa --version可用将 OPA 可执行文件所在目录加入PATH导入agent_control_specification失败原生 ACS 包未安装在虚拟环境中执行pip install agent-governance-toolkit[full]并激活正确的 venv运行时找不到 Rego 策略Manifest 的 bundle 路径被改动但 Rego 文件未同步移动恢复bundle: .指向的目录与lab1-policy.rego的相对位置或同步移动两者4.5 讨论题主持人引导方向为什么 Manifest 拥有策略绑定因为策略的加载入口、查询路径与干预点映射都由 Manifest 声明运行时只负责执行声明保证谁声明、谁负责。为什么HostSession拥有计数器因为 token 预算这类跨调用状态属于会话生命周期session_id维度而非单次策略裁决将计数上收到会话层才能实现token_count 2000这类跨调用约束。策略分发器或 OPA 进程失败会怎样仓库的设计立场是 Fail closed——评估失败即拒绝详见 docs/adr/0013-fail-closed-on-policy-evaluation-errors.md。五、中场 15 分钟身份与信任概念讲解要点5.1 必须讲清的第一性原理信任 ≠ 策略facilitator-notes.md 为 Lab 2 指定了最重要的概念区分AgentMesh 信任不是策略评估。信任决定对端是谁、存在什么关系ACS 决定当前动作在绑定策略下是否被允许。这是全工作坊最重要的一句话。主持人应反复强调身份层回答who你是谁、可信度多少、有什么能力授权策略层回答what这个动作允不允许。两者独立演进、独立验证缺一不可——Lab 2 的讨论题为什么策略评估与身份验证必须分离正源于此。5.2 AgentMesh 的职责边界AgentMesh 拥有来自 slides.md密码学身份cryptographic identity信任与声誉trust and reputation能力授权capability grants跨 Agent 传输cross-agent transport。5.3 信任握手的底层实现源码佐证主持人可向进阶参与者展示 handshake.py 的实现细节印证幻灯片内容握手采用Ed25519 挑战/响应challenge/response挑战包含随机 nonce支持RFC 9334 freshness noncerequire_freshnessTrue时生成用于 Evidence 活性证明挑战默认30 秒过期expires_in_seconds: int 30过期即失效响应体携带agent_did、capabilities、trust_score0–1000 整数、signature、public_key等字段响应方需用自己的私钥签名。风险评分侧risk.py 定义了RiskScore0–1000越高越安全与RiskSignalseverity 分 critical/high/medium/low/info 五档对应不同权重并支持每 ≤30 秒基于行为更新一次的连续评分模型——这正是 Lab 2 中RiskScorer.record_event与get_score的实现依据。六、Lab 225 分钟多 Agent 信任的主持要点6.1 实验目标与任务拆解lab2_multi_agent_trust.py 的目标是创建两个 AgentMesh 身份 → 评估信任 → 通过正面行为构建声誉 → 验证吊销revocation后的拒绝。参与者需要补全四处 TODOcreate_agents()用AgentIdentity.create创建 orchestrator能力[orchestrate:agents, read:data]sponsoraliceexample.com与 worker能力[read:data, write:reports]sponsorbobexample.comattempt_handshake()用TrustHandshake(initiator..., responder_did..., required_capabilities[read:data], min_trust_score...)执行握手打印[OK]/[FAIL]并返回result.trustedbuild_trust()用RiskScorer记录 10 次policy_compliant_action事件打印更新后的分数revoke_and_verify()吊销发起方凭证后再次握手确认以credentials revoked原因失败。主流程run_lab()预设了完整的故事线初始握手以min_trust_score700尝试——预期失败默认信任分 500 700见 handshake.py 中TRUST_SCORE_DEFAULT常量记录 10 次正面事件后将阈值降到 540 重试——预期成功成功后执行吊销并验证后续握手被阻断。参考实现片段补全 TODO 后的样子orchestrator AgentIdentity.create( nameorchestrator, sponsoraliceexample.com, capabilities[orchestrate:agents, read:data], ) worker AgentIdentity.create( nameworker, sponsorbobexample.com, capabilities[read:data, write:reports], ) result TrustHandshake( initiatororchestrator, responder_didstr(worker.did), required_capabilities[read:data], min_trust_scoremin_trust_score, ).execute() return result.trusted6.2 Lab 2 常见问题与排查主持人口袋清单来自 facilitator-notes.md症状原因处理握手一直失败参与者忘记记录声誉事件build_trust未实现或未调用检查RiskScorer.record_event是否被循环调用 10 次提分后握手仍失败信任阈值仍高于更新后的分数确认min_trust_score与get_score返回值的数值关系例如 500 → 540 阈值可通过700 阈值不可吊销后握手仍成功未在成功握手后测试吊销在revoke_and_verify中先initiator.revoke()再执行握手确认返回credentials revoked主持人还应提醒声誉事件必须先记录、后查分否则get_score读到的还是旧分数这正是Participants forget to record reputation events这个常见问题的根源。6.3 讨论题主持人引导方向哪些控制属于 AgentMesh 而非 ACS身份 DID、信任分数、能力授权、吊销状态——这些决定对端是谁属于身份层。为什么策略评估与身份验证必须分离因为策略关注动作是否被允许当前时刻、绑定策略身份关注对端是否可信持续状态、跨会话混在一起会让审计和故障定位失去边界。重建一次跨 Agent 决策需要哪些审计字段至少应包含双方 DID、时间戳、信任分数与阈值、请求的能力集合、策略裁决结果、吊销状态等才能事后完整还原谁、何时、凭什么、做了什么。七、收尾 5 分钟Wrap-up 与四个追问facilitator-notes.md 的收尾部分给出四个开放追问主持人可逐一抛给参与者作为理解深度的检验哪些控制属于SandboxConfig指向资源与网络隔离resource and network isolation——沙箱类控制。哪些状态属于HostSession指向会话级计数器session counters如 token 预算等跨调用状态。哪些失败必须拒绝而非降级deny rather than fall back指向 Fail-closed 清单未知工具、运行时/审批错误、动作与身份不匹配都应拒绝而非放行。哪些审计数据可以公开展示指向审计脱敏公开错误保持 sanitized敏感审计负载受限访问。7.1 控制平面职责总表lab-guide.md 的 Wrap-up 环节给出两张表主持人应结合两个实验现场总结谁管什么控制归属策略定义与干预点原生 ACS Manifest会话计数器HostSessionAgent 身份与信任AgentMesh框架生命周期排序Agent OS 适配器资源与网络隔离SandboxConfig概念问题对应的治理工具未知工具被拒Manifest 契约Fail closed运行时/审批错误被拒Fail-closed 评估路径动作与身份不匹配被拒强制身份校验对外错误保持脱敏审计与错误 sanitization7.2 生产化清单供进阶参与者课后实践幻灯片 Production checklist 页给出了从工作坊走向生产的检查项主持人可预告给学员Lint 并重放replayManifest测试每一条被中介的框架路径测试沙箱隔离测试审批与运行时失败路径限制审计访问监控 SLO 与事件信号。八、课后延伸路径参与者完成两个实验后主持人可引导进入以下仓库文档继续深入docs/quickstart.md完整快速上手docs/tutorials/55-agent-control-specification.mdACS 规范深度教程docs/tutorials/02-trust-and-identity.md信任与身份docs/tutorials/03-framework-integrations.md框架集成docs/tutorials/04-audit-and-compliance.md审计与合规。小结一次成功的工作坊主持人只需要守住三条主线课前两件事跑通实验、确认 OPA 与 ACS SDK、Lab 1 讲透Manifest / Rego / 运行时 / 会话四层分离、Lab 2 讲透信任决定对端是谁策略决定动作是否允许。配合本文给出的常见问题排查表与源码级讲解素材handshake.py、risk.py、lab1-policy.rego即使是没有治理经验的开发者也能在两小时内建立策略 身份双控制平面的完整心智模型。【免费下载链接】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），仅供参考