企业官网建设流程全解析

Agent Control Specification（ACS）深度指南：AGT 5.0 统一策略决策层的设计、部署与接入实战

【免费下载链接】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

ACS（Agent Control Specification）是 Agent Governance Toolkit（AGT）5.0 的统一策略层：一个无状态、确定性、fail closed 的 Agent 安全策略决策运行时，以一份清单（manifest）声明输入、模型、工具、输出全生命周期的策略绑定，由宿主在既定干预点提交完整 JSON 快照换取归一化裁决。本文以policy-engine/下的 README 与 规范文档 为骨架，结合仓库源码与示例，讲解 ACS 的核心模型、清单字段、八个干预点、裁决语义、注释器、信息流控制、可观测性与 SDK 接入方法，读完即可把一个 Agent 循环完整纳入 ACS 治理。

为什么需要一个统一策略层

Agent 不再只生成文本——它会检索数据、调用工具、跨系统执行动作。治理问题因此变成"谁来决定 Agent 被允许做什么"。当前治理是碎片化的：策略散落在提示词、框架钩子与应用代码里，各系统执行不一致，安全团队缺乏集中可见性。ACS 给 AGT 一个可移植的决策契约，让策略不再散布于整个技术栈。

ACS 是什么：一个契约覆盖整个 Agent 循环

ACS 是便携、生命周期感知的 Agent 策略契约。单一清单声明在输入、模型、工具、输出上校验什么、每个策略在何时评估、决策如何结构化与组合、为审计捕获哪些证据。AGT 宿主解析清单，在每个干预点构建快照，并执行返回的裁决。

核心思想是一个策略工件覆盖完整 Agent 循环：

Input -> Model -> Tool Call -> Tool Result -> Output

示例清单与字段精讲

一个最小可用的清单绑定一个 Rego 策略并守护一个干预点：

agent_control_specification_version: "0.4.0-alpha.1" metadata: name: email-agent policies: email_policy: type: rego bundle: ./policy query: data.email_agent.verdict intervention_points: pre_tool_call: policy_target: "$.tool_call.args" policy_target_kind: tool_args tool_name_from: "$.tool_call.name" policy: id: email_policy tools: send_email: type: Tool id: send_email clearance: internal

字段语义（完整契约见 spec/SPECIFICATION.md）：

• policy_target：快照中待评估值的路径，必须使用快照根（$snap、$、$.name）。
• policy_target_kind：可选的描述性标签，会被复制进策略输入。
• tool_name_from：仅在pre_tool_call/post_tool_call两个工具点合法，指定承载当前工具名的快照路径；解析结果必须是字符串，工具名不在tools目录中会以runtime_error:tool_unknownfail closed。
• tools：投影工具元数据目录，条目可携带任意字段，包括clearance、security_labels。

完整版的八个干预点清单可以参考 bank_agent 示例清单：它把agent_startup、input、pre_model_call、post_model_call、pre_tool_call、post_tool_call、output、agent_shutdown全部绑定到同一份 Rego bundle，每个点用独立的 query（如data.agent_control_specification.bank_agent_rego.pre_tool_call_verdict）并声明了classifier注释器——这是"一个清单覆盖全生命周期"的直接范例。

路径语法：快照如何被寻址

清单中所有路径使用统一语法：.name选择对象成员，[n]选择零基数组元素（禁止负数），["name"]选择含点或方括号的成员名，读取不做类型强转。路径根有明确分工（规范第 3 节）：

不同字段被限定使用不同根：policy_target和tool_name_from只能使用快照根；注释器from可使用$pi（排除$pi.annotations）、$target、$tool、$snap系根；transform的path必须根植于$target。越界即 fail closed（runtime_error:manifest_invalid/runtime_error:transform_target_forbidden）。必选路径解析失败返回runtime_error:path_missing，路径段遇到不兼容 JSON 类型返回runtime_error:path_type_mismatch。

ACS 与 AGT 的三层集成

AGT 是 ACS 决策核心周围的宿主与策略执行点（PEP），集成横跨三层：

运行时消费原生 ACS/AGT 清单并解析 ACSextends。遗留治理文件夹发现仅通过单向的agt migrate v4-to-v5命令可用。

核心属性：无状态、确定性、fail closed

规范第 1.1 节把这些表述为 MUST 级不变式：单次调用栈内传递的状态被允许，影响裁决的进程级/模块级注册表不被允许；warn意图被归一化为allow加warnings[]条目，escalate意图被归一化为携带approval块的"可提升 deny"。

八个干预点

pre_tool_call与post_tool_call是仅有的工具干预点，也是仅有的接受tool_name_from的点。评估顺序固定（规范第 6 节）：先解析policy_target，工具点再投影工具，构建带空annotations的初步策略输入，按注释器名字典序收集注释，构建最终策略输入，调用策略 dispatcher，归一化裁决，最后校验并（在 enforce 模式下）应用 transform。任何一步失败都以匹配的保留 reason 返回deny。

与上游 ACS 的差异

以下行为属于 spec/SPECIFICATION.md（本引擎唯一的权威契约）的规范部分：

Manifest Schema 全解

干预点条目字段：

extends的解析遵循规范第 2.2 节：文件加载器把路径条目限定在顶层清单根目录树内；URL 条目仅限 HTTPS、不携带环境凭证、施加有限超时/体积/重定向限制，且对回环地址、RFC 1918 私网、链路本地、共享地址空间、IPv4 映射等形式的地址一律 fail closed，防止 SSRF 打到云元数据端点。合并是加性的，冲突定义、引用环、缺失文件、URL 拉取失败、父子版本不一致都会 fail closed；integrity（sha256-<base64>）与sha256（64 位十六进制摘要）互斥。URL 来源清单禁止声明文件系统路径字段与主机环境密钥字段（如api_key_env），详见 docs/acs-retarget.md。

四种策略类型

一个策略绑定通过policy.id选择策略；rego策略必须在绑定或定义上提供query。Cedar 策略通过policy_set（内联）或policy_path（文件/目录）给出，可选entities_path、schema_path与query；绑定可覆写principal/action/resource/context映射，默认映射为Agent::"<agent id>"、Action::"<干预点名>"、Tool::"<name>"（非工具点为PolicyTarget::"<kind>"）。Cedar 授权结果映射为裁决，策略作者可通过advice注解产出warn/escalate/transform（形状校验见 spec/schema/cedar_advice.schema.json）。

工件验证与裁决结构

Rust 核心暴露validate_acs_artifacts，所有语言 SDK 都委托给该实现，返回形状在 Rust、Python、Node、.NET 间完全一致：valid加针对清单 schema、类型化 ACS 语义与 OPA Rego 解析的结构化诊断。

use agent_control_specification::validate_acs_artifacts; let result = validate_acs_artifacts(manifest_yaml, &rego_modules, None);

裁决成员：

归一化规则（规范第 13 节）：warn归一化为allow加warnings[]条目；escalate归一化为携带approval块的deny（可提升 deny）。输出非对象、decision缺失或非法、reason带runtime_error:前缀、transform 与 decision 不匹配、evidence非对象、result_labels非字符串数组，一律runtime_error:policy_output_invalidfail closed。

transform是唯一改变策略目标的决策形态：body 为{path, value}，path必须根植于$target，运行时只替换策略目标内该位置的值，绝不触碰快照、注释、投影工具或宿主状态。越界路径返回runtime_error:transform_target_forbidden，无法解析或值无法设置返回runtime_error:transform_invalid。在enforce模式下宿主应用转换；在evaluate_only模式下宿主校验但不应用、不返回转换后目标，适合在真实流量上"影子运行"新策略。每次成功评估还会派生两个动作身份input_identity与enforced_identity（规范策略输入的 SHA-256 摘要，十六进制小写、sha256:前缀），审批路径绑定到enforced_identity，从机制上封堵 TOCTOU 与"一次审批授权不同动作"的风险。

注释器（Annotators）

核心声明注释器类型，通过宿主拥有的实现分发。运行时按注释器名字典序解析每个点特定from路径到初步策略输入，调用 dispatcher，并把返回值只写入annotations.<name>，绝不允许覆盖snapshot、policy_target、tool、intervention_point等根成员。注释器输出超大、畸形、或含保留前缀 reason 时以runtime_error:annotation_failedfail closed，超时以runtime_error:annotation_timeoutfail closed。ACS 不内置分类器/评判引擎，注释器执行总是宿主提供。

默认llmdispatcher 的 provider 预设覆盖 OpenAI 兼容 Chat Completions、Azure OpenAI、Amazon Bedrock Converse、GeminigenerateContent与 Ollama chat；凭证必须来自显式清单字段或命名环境变量，provider 响应须归一化为 JSON 注解后再进入策略执行，畸形响应/缺凭证/缺标签一律按注释器错误 fail closed。system_prompt_file、system_prompt_url与bundle_url属已移除形态，声明即runtime_error:manifest_invalid。

信息流控制（IFC）

ACS 把 IFC 实现为无状态标签流策略模型：宿主跟踪来源并在input.snapshot.ifc.source_labels提供源标签，清单在工具目录中声明 sink 元数据。核心不做内置 IFC 检查、不存标签状态、不传播污点——宿主是状态化策略执行点。

ifc_agent 清单 声明了两个工具public_egress（clearance: public）与trusted_archive（clearance: confidential），策略通过 policy/lib/ifc.rego 里的默认格public < internal < confidential < secret判定流向。no-write-down 规则要求 sink 许可级支配每个源标签，标签不可比较或缺失/未知一律视为拒绝，推荐 reason 为ifc_clearance_violation。result_labels是运行时无状态 IFC 的返回通道：策略可返回描述该 sink 产出数据敏感度的标签数组，宿主在数据实际产出时随数据持久化，并在后续评估作为snapshot.ifc.source_labels回填——标签流跨轮次正确而不需要运行时持有状态。配套的 Cedar 实现见 policy/cedar-lib/ifc.cedar。

可观测性：结构化遥测与 OpenTelemetry

Rust 核心通过TelemetrySink发出结构化遥测，事件类型包括decision、annotator_dispatch、policy_evaluation、evaluation_timing、intervention_point.transformed、annotator_failed、policy_failed。

性能遥测模式（wire 值）：Off=0（无外部/阶段计时事件）、External=1（注释器分发与策略评估成本事件）、Full=2（External 加每次评估计时）。

遥测默认脱敏。事件携带稳定字段（reason code、错误类、动作身份、策略 id、注释器名、决策、模式、时长、证据工件、证据指针键名），但绝不包含原始策略目标、工具参数、模型输出、注解负载、transform 值、证据指针 URL、密钥与个人数据。

每个 SDK 都提供可插拔遥测 sink，宿主无需手写审计层；每次评估发出一个decision事件，并收敛到同一 OpenTelemetry 契约——meteragent_control_specification下的每决策计数器acs_intervention_{allow,deny,warn,escalate,transform}_total与直方图acs_intervention_duration_ms。sink 抛错会被捕获吞掉，遥测永不成为承重环节。

Rust 中核心自己负责发事件，装 sink 即可；Python/Node/.NET 宿主层根据返回的InterventionPointResult构建事件，并通过原生policy_labels访问器在构造期从完全合并后的清单读取策略 id 与注释器名。事件清单与 OTel 映射详见 policy-engine/docs/observability.md。

SDK 矩阵与构建

ACS Cargo workspace 内嵌在 AGT 顶层 Cargo workspace 中。只构建本引擎时，从policy-engine/运行作用域 workspace 命令：

cd policy-engine cargo build --workspace cargo test --workspace

同一批 crate 也可从仓库根通过包级命令触达：

cargo build -p agt_core_engine cargo test -p agt_core_engine

目录布局

示例合集

保留 Reason 命名空间

策略不得使用该前缀。完整保留表见规范第 16 节与机器可读清单 policy-engine/spec/reserved-reasons.json，包括manifest_invalid、intervention_point_unknown、path_missing、path_type_mismatch、tool_unknown、annotation_failed、annotation_timeout、policy_invocation_failed、policy_output_invalid、transform_invalid、transform_target_forbidden、resource_limit_exceeded、resolution_cycle、resolution_merge_conflict、resolution_path_traversal、resolution_invalid_governance。宿主层另有host_error:*命名空间（如approval_identity_mismatch、approval_unresolved、streaming_unsupported、adapter_unsupported），由agt-host产生，拦截器不得发出。

实战接入：把 ACS 装进你自己的宿主

完整的分步指南见 policy-engine/QUICKSTART.md，要点如下：

1. 安装 SDK：Rustcargo add agent_control_specification；Pythonpython -m pip install agent-control-specification；Nodenpm install agent-control-specification；.NETdotnet add package AgentControlSpecification。前置条件为 Rust 1.85+、Python 3.11+、Node 18+ 或 .NET 8；仅在清单使用rego策略且走捆绑 OPA dispatcher 时才需要opa在PATH上。
2. 声明清单：如上述最小清单；tool_name_from在两个工具点是必填的。
3. 编写策略：写policy/my_agent.rego，以default verdict := {"decision": "allow"}兜底，用条件规则返回deny（含reason与message）。
4. 构造运行时：零配置from_path构造器（Rust/Pythonfrom_path、NodefromPath、.NETFromPath）自动绑定捆绑 OPA dispatcher 与清单相对 Rego bundle，Rego 宿主无需 dispatcher 代码。
5. 在干预点评估：调用evaluate_intervention_point，传干预点与快照；Rust 还需传EnforcementMode（Enforce/EvaluateOnly），Python/Node/.NET 通过run/enforce助手施加执行模式。
6. 执行裁决：allow/warn用原策略目标继续；deny阻断并呈现reason/message；escalate挂起并走审批解析器；transform只用返回的转换后策略目标继续（脱敏是典型场景，核心绝不会在allow/warn/deny/escalate下改写目标）。
7. 守护整个循环：run（护input/output）、run_model（护pre_model_call/post_model_call）、run_tool/protect_tool（护pre_tool_call/post_tool_call）等编排助手把评估、执行、transform 应用与审批打包成一次调用。
8. 验证集成：在临时宿主项目里跑一个 allow 与一个 deny 冒烟；设置AGENT_CONTROL_REQUIRE_OPA=1让本地 CI 奇偶校验中的 OPA 测试大声失败而非跳过；跨 SDK 奇偶 fixtures 位于 policy-engine/tests。

想"开箱即得有效工件"而不是手拼清单时，可用引导生成器：

acs-generate init --non-interactive --name "Demo Agent" --points input,pre_tool_call,output --tool send_email:internal --deny-keyword secret --escalate-tool send_email --sample-snapshot --out build/demo-acs

它会写出清单、Rego 策略、报告与可选样本快照；--strict让本地 OPA 校验与 CI 对齐。生成后用带extends的子清单做加性演进——子清单可加元数据键、策略、注释器、工具或新干预点，但不能以不同值替换既有干预点的策略、目标或tool_name_from（文件级extends必须留在顶层清单根内，如base/manifest.yaml）。

归属与许可证

本引擎不再在仓库内 vendored，而是 crates.io 上的agent-control-speccrate（MIT 许可，当前锁定 0.4.0-alpha.3，清单版本保持 0.4.0-alpha.1，状态 Draft，正式发布前建议精确锁定版本）。本目录代码按仓库根LICENSE的 MIT 许可发布；LICENSE.acs是仍携带上游文本的规范/schema/一致性文件的上游声明。安全边界与宿主义务的完整讨论见 policy-engine/docs/security-model.md，无状态运行时契约见 policy-engine/docs/stateless-runtime.md。

【免费下载链接】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