企业官网建设流程全解析

• 人工智能
• AI Agent
• AI 安全治理
• 策略引擎
• Agent 沙箱
• 认证鉴权

本篇技术指南以 policy-engine/QUICKSTART.md 为骨架，完整讲解如何把 Agent Control Specification（ACS）策略执行引擎接入任意 Agent Host：从一张空白的 manifest 开始，逐步构建出在每一个模型边界与工具边界都被策略中介（mediate）的 Agent 循环。文中 manifest 与策略编写步骤是语言无关的，构造与评估步骤则同时给出 Rust、Python、Node、.NET 四种 SDK 的等价写法，全部示例与底层原理均来自当前仓库 policy-engine/ 目录。读完后你将掌握：声明 ACS manifest 与 Rego 策略、在八个干预点评估并执行判定、用编排 helper 一次性完成"评估+执行+转换+审批"、通过生成器初始化合规的 ACS 制品，以及如何用仓库内的测试与示例验证自己的集成。

ACS 在 Host 中的定位：PEP 与 PDP 分离

ACS 是 Agent Governance Toolkit 的策略层，定位为一个**无状态、确定性、失败即关闭（fail closed）**的策略决策运行时（见 policy-engine/README.md）。它的集成模型非常清晰：

• Host 拥有 Agent 循环，充当策略执行点（PEP，Policy Enforcement Point）。在每个干预点上，Host 把"即将发生什么"的完整 JSON 快照交给 ACS，例如入站请求、一次模型调用、一次具体的工具调用。
• ACS 充当策略决策点（PDP，Policy Decision Point）。它评估绑定在该干预点上的策略，返回三种东西：verdict（判定）、仅当判定为transform时可选的已转换策略目标（transformed policy target）、以及产生该决策的策略输入（policy input）。

ACS 在调用之间不持有任何状态，因此 Host 每次都必须提供完整快照；同时 Host 负责对判定采取行动——ACS 决策，Host 执行。这与 README 中声明的运行时契约一致：无状态（运行时不保留会影响后续判定的可变状态）、确定性（相同 manifest、快照、模式与 dispatcher 输出必然产生相同判定）、失败即关闭（运行时故障一律返回deny，使用保留的运行时错误 reason，且不应用任何转换）。

前置条件

注意：OPA 只在策略通过内置 OPA dispatcher 求值时、于运行时才需要。如果 Host 自带策略 dispatcher，则无需安装 OPA。

Step 1. 安装 SDK

四种 SDK 的常规安装方式如下：

每个 SDK 都加载同一个原生核心：Rust crate 直接链接它，Python 与 Node 包携带编译好的原生扩展，.NET 包则把原生库与托管程序集一起发布。如果要从本仓库源码构建而非使用已发布包，请遵循 SDK 矩阵 中的构建命令。

使用独立 ACS 制品包（artifact kit）安装

如果软件包尚未发布、需要从独立制品包安装，请把ACS_KIT环境变量指向包含artifacts/的制品包根目录：

两点平台注意事项：Python 制品安装可能从你配置的软件包索引解析第三方 wheel 依赖，除非制品包同时包含 Python 依赖 wheelhouse；只有包含该依赖闭包的制品包才能配合--no-index --find-links "$ACS_KIT/artifacts"使用。Node 制品安装中，请把agent-control-specification-linux-x64-gnu与agent-control-specification-opa-linux-x64替换为与宿主平台匹配的原生包与 OPA 包。

Step 2. 声明 Manifest：把策略绑定到干预点

manifest 的作用是把命名策略绑定到干预点。最小的可用 manifest 声明一条 Rego 策略并守卫一个干预点。把下面的内容保存为 Host 旁边的manifest.yaml：

agent_control_specification_version: "0.4.0-alpha.1" metadata: name: "my-agent" policies: email_policy: type: rego bundle: ./policy query: data.my_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

字段含义：policy_target是待求值值在快照中的路径；tool_name_from仅在两个工具干预点上必需，用于指明承载当前工具名的路径；tools块是投影后的工具元数据目录，策略可以读取它。manifest 模式的完整概览见 README 的 Manifest schema overview，规范定义见 policy-engine/spec/SPECIFICATION.md。

从 README 可以进一步了解 manifest 的顶层块：

干预点条目字段：policy_target（待求值值的快照路径）、policy_target_kind（可选描述性标签，会复制进策略输入）、annotations（按点选择已声明注释器及其from路径）、policy（含id、可选query与 Host 定义的 adapter 字段）、tool_name_from（仅工具干预点上的当前工具名快照路径）。

仓库中 policy-engine/examples/bank_agent/manifest.yaml 给出了一个绑定全部八个干预点、附带八个classifier注释器与工具目录（含clearance、security_labels）的完整参考 manifest，是理解字段组合方式的极佳样例。

Step 3. 编写策略：verdict 契约与五种决策

内置 dispatcher 会相对 manifest 解析bundle路径，所以创建policy/my_agent.rego。下面这条策略拒绝任何参数中提到外部收件人的工具调用：

package my_agent import rego.v1 default verdict := {"decision": "allow"} verdict := { "decision": "deny", "reason": "external_recipient_blocked", "message": "This tool may not send to external recipients.", } if { args := object.get(input.policy_target, "value", {}) contains(lower(object.get(args, "to", "")), "@external.example") }

verdict 必须携带decision，取值只能是allow、deny、warn、escalate、transform之一。其余字段约定（与 README 中 verdict 成员表一致）：

两条硬性规则：策略只有在transform决策下才能返回transform主体——allow、warn、deny、escalate四种决策永不修改策略目标；reason 不得使用保留的runtime_error:前缀（该命名空间是运行时故障专用的，详见 README 的 Reserved reasons 一节与规范第 15 节）。

仓库中 policy-engine/examples/bank_agent/policy/bank_agent_rego.rego 展示了更完整的策略写法：用default <point>_verdict声明八个默认判定，再以input.intervention_point分派到各点的具体规则，涵盖 deny（高风险输入、模型建议绕过审批）、escalate（大额转账需人工审批）、transform（插入系统提示、脱敏账号）、warn（关闭审计）等全部五种决策形态，与 Step 5-7 的语义一一对应。

Step 4. 构造运行时：零配置from_path

使用零配置的from_path构造器。不带任何 dispatcher 参数时，它会针对 manifest 相对路径的 Rego bundle 接好内置 OPA 策略 dispatcher，因此 Rego Host 无需编写任何 dispatcher 代码（何时需要自供 dispatcher 见 README 的 Zero-config construction）：

use agent_control_specification::AgentControl; let control = AgentControl::from_path("manifest.yaml")?;

from agent_control_specification import AgentControl control = AgentControl.from_path("manifest.yaml")

const { AgentControl } = require("agent-control-specification"); const control = AgentControl.fromPath("manifest.yaml");

using AgentControlSpecification; var control = AgentControl.FromPath("manifest.yaml");

Step 5. 在干预点求值：传入干预点与完整快照

在你声明的边界处调用 SDK，传入干预点与快照。结果携带verdict、transform时的已转换策略目标，以及产生决策的策略输入：

use agent_control_specification::{Decision, EnforcementMode, InterventionPoint}; use serde_json::json; let result = control.evaluate_intervention_point( InterventionPoint::PreToolCall, json!({"tool_call": {"id": "t1", "name": "send_email", "args": {"to": "user@external.example"}}}), EnforcementMode::Enforce, ); assert_eq!(result.verdict.decision, Decision::Deny);

from agent_control_specification import InterventionPoint result = await control.evaluate_intervention_point( InterventionPoint.PRE_TOOL_CALL, {"tool_call": {"id": "t1", "name": "send_email", "args": {"to": "user@external.example"}}}, ) assert result.verdict.decision.value == "deny"

const { InterventionPoint } = require("agent-control-specification"); const result = await control.evaluateInterventionPoint( InterventionPoint.PreToolCall, { tool_call: { id: "t1", name: "send_email", args: { to: "user@external.example" } } }, );

var result = await control.EvaluateInterventionPointAsync( InterventionPoint.PreToolCall, System.Text.Json.JsonDocument.Parse( """{"tool_call":{"id":"t1","name":"send_email","args":{"to":"user@external.example"}}}""").RootElement.Clone());

注意 API 差异：Rust SDK 在evaluate_intervention_point上接收EnforcementMode；Python、Node、.NET SDK 求值时不带模式，而是通过 Step 7 介绍的run与enforcehelper 应用执行（enforcement）。

Step 6. 执行判定：五种决策的 Host 动作

evaluate_intervention_point返回判定后，由 Host 决定如何处理：

当策略返回transform时，运行时在enforce模式下校验转换路径、将其应用到策略目标，并把转换后的值暴露在结果上。执行工具、发送模型请求、存储工具结果或披露输出之前，必须读取已转换的策略目标而非原始值。脱敏（redaction）是最常见的用例，但核心在任何情况下都不会在allow、warn、deny、escalate时修改数据。这也呼应了 README 中与上游 ACS 的一个关键分歧：本引擎把 effect 机制移除、替换为transform判定类型，使"转换"成为可审计、可验证的显式决策。

Step 7. 中介整个 Agent 循环：八个干预点与编排 helper

真实 Host 守卫的不止一个点。在循环的对应位置接入每个相关干预点：

其中pre_tool_call与post_tool_call是仅有的两个工具干预点，也是仅有的接受tool_name_from的点。手动逐点调用evaluate_intervention_point可行，但每个 SDK 都内置了编排 helper，把求值、执行、转换应用与审批打包进一次调用，普通 Host 应优先使用：

在 enforce 模式下，这些 helper 遇到deny会抛出阻塞错误（blocked error），遇到escalate则咨询审批解析器（approval resolver）——它是 Host 侧的一个回调，返回 allow、deny 或 suspend。各语言的方法名与接线细节见仓库sdk/下的各 SDK README，以及制品包内附的PYTHON_README.md、NODE_README.md、DOTNET_README.md。

仓库中 policy-engine/examples/bank_agent/manifest.yaml 与配套 Rego 策略是"全循环中介"的完整可运行参考：八个干预点全部绑定策略，pre_tool_call对 10000 以上电汇返回escalate，post_model_call拦截"bypass approval"提示，output用正则把CHK-[0-9]+账号脱敏为ACCOUNT-REDACTED。另有 policy-engine/integrations/openai/、policy-engine/integrations/mcp/、policy-engine/integrations/rig/ 下的 Rust 集成 crate 示例，展示在真实框架的工具调用点挂上守卫的写法。

Step 8. 添加注释器与脱敏

有两类常见需求不需要在 Host 侧编写超出内置默认的 dispatcher 代码。

注释器（annotators）：把派生的信号（如分类器评分）挂到策略输入的annotations.<name>下，供策略读取。在 manifest 的annotators块中声明它们，并用annotations映射让某个干预点选入。注意，内置的classifier、llm、endpoint注释器会发起网络调用，因此零配置使用注释器需要一个可达的端点以及所需的凭证。参考 dispatcher 示例位于仓库 policy-engine/integrations/annotators/，Rust 侧实现对应core/src/dispatchers/classifier.rs、core/src/dispatchers/llm.rs、core/src/dispatchers/endpoint.rs；运行时把每个点特定的from路径对初步策略输入解析后调用 dispatcher，且只在annotations.<name>下写入返回值。README 中的 LLM 注释器供应商指南 提供了可插拔供应商预设。

脱敏（redaction）：不需要自定义 dispatcher。返回transform判定、让transform.value携带脱敏后的策略目标，然后按 Step 6 读取已转换策略目标即可。仓库示例 policy-engine/examples/support_agent/ 正是以这种方式脱敏 PII。

Step 9. 验证集成：制品冒烟测试与跨 SDK 一致性

先确认 SDK 在你的环境中能正确对接原生核心。在制品包场景下，把包安装进一个临时 Host 项目，用你计划发布的 manifest 跑一个 allow 和一个 deny 冒烟测试；在源码检出场景下，使用项目构建说明描述的各语言测试套件。

在本地验证 CI 对齐时设置AGENT_CONTROL_REQUIRE_OPA=1，让依赖 OPA 的测试在缺失 OPA 时响亮失败而不是被跳过。仓库 policy-engine/tests/ 下的跨 SDK 一致性 fixtures 断言四个 SDK 对同一批快照给出相同判定。

对于仅制品的包，请从临时 Host 项目验证已安装包，而不是运行仓库检出的测试套件：

制品校验：所有 SDK 共享同一个原生实现

除冒烟测试外，Rust 核心还暴露validate_acs_artifacts，每个语言 SDK 都委托给该实现；四个 SDK 返回的结果结构完全一致——valid加上针对 manifest 模式、类型化 ACS 语义、OPA Rego 解析的结构化诊断：

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

策略绑定通过policy.id选择一条策略；Rego 策略要求在策略定义或绑定上给出query。规范 JSON Schema 位于 policy-engine/core/schema/（含manifest.schema.json与approval.schema.json），规范的权威契约见 policy-engine/spec/SPECIFICATION.md。

用生成器初始化：acs-generate init

当第一套 ACS 制品应当"构造即正确"（valid by construction）而不是手工拼装时，使用生成器。引导式初始化流程会询问你要中介的干预点、工具目录条目、要拦截的关键词、审批门与输出脱敏模式，然后写出 manifest、Rego 策略、报告与可选的示例快照：

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

输出目录必须为空，除非提供--force。当本地 OPA 校验必须与 CI 一致时，加上--strict。安装生成器包后，同一命令也可以写为acs init。生成器会写manifest.yaml、policy/<slug>.rego、report.md，以及可选的snapshots/<intervention_point>.json与test_policy.py冒烟测试。生成器 README（policy-engine/generator/README.md）还补充了两点生产实践：

• 可重复运行：--answers-file支持 CI 与重复本地运行，接受与 CLI 标志一致的字段（name、points、tools、deny_keywords、escalate_tools、redact_output_patterns），不支持的关键字会快速失败，避免 CI 静默忽略预期设置；--answers-file -支持从 stdin 读取 JSON/YAML。
• 严格模式下的 OPA：仅制品包内置本地 Node 可选 OPA 包，安装后把其bin目录前置到PATH再运行--strict：

  npm install "$ACS_KIT"/artifacts/agent-control-specification-opa-linux-x64-0.3.1-beta.0.tgz PATH="$PWD/node_modules/agent-control-specification-opa-linux-x64/bin:$PATH" \ acs-generate init --strict --non-interactive --name "Payments Agent" --out build/acs-payments

生成后的叠加：extends子 manifest

生成之后要做增量改动时，使用带extends的子 manifest。子 manifest 可以添加 metadata 键、策略、注释器、工具或新的干预点，但不能用不同的值替换已有干预点的策略、目标或tool_name_from——冲突的重复项在 manifest 加载时会失败即关闭。

基于文件的extends限定在顶层 manifest 根目录内：把父 manifest 放在子根目录之下，例如base/manifest.yaml；或者当 SDK 提供 manifest-chain 构造器时，用它加载并列的兄弟 manifest。这一"父策略不可被替换、只能叠加"的合并语义也体现在 AGT 的 ADR（docs/adr/0014-parent-deny-rules-immutable-in-merge.md）中，属于本项目对上游 ACS 的既定分歧之一。

更进一步：从 Quickstart 到生产落地

• 阅读权威契约：policy-engine/spec/SPECIFICATION.md
• 了解 Host 义务与安全边界：policy-engine/docs/security-model.md，以及无状态运行时契约 policy-engine/docs/stateless-runtime.md
• 挑选合适的 SDK 面：policy-engine/docs/sdk-surfaces.md
• 包装真实 Agent 框架：参考 policy-engine/docs/adapter-matrix.md 与 README 的 Framework adapters 一节
• 研究可运行 Host 示例：仓库 policy-engine/examples/ 下按场景组织，包括bank_agent（全生命周期点、转换与脱敏）、lifecycle_rego（零配置 Rego 全流程）、custom_dispatchers（离线分类器/端点/LLM 注释器与自定义策略 dispatcher）、manifest_extends（文件式 manifest 组合）、conformance_snapshots（fixture 驱动的策略评审）、coding_agent（Rust Host 应用）、ifc_agent（无状态信息流控制标签流转）
• 遥测：Rust 核心通过TelemetrySink输出结构化、默认脱敏的事件（decision、policy_evaluation、intervention_point.transformed等），四个 SDK 都内置可插拔 sink 与 OpenTelemetry 指标契约（acs_intervention_{allow,deny,warn,escalate,transform}_total计数器与acs_intervention_duration_ms直方图，meter 名为agent_control_specification），见 policy-engine/docs/observability.md

至此，你已拥有一套从空 manifest 到全循环中介的完整集成路径：声明策略、绑定干预点、零配置构造运行时、按五种判定执行、用编排 helper 覆盖整个 Agent 生命周期，并通过制品校验、冒烟测试与生成器保证制品质量。ACS 的"定义一次，处处执行（Define once. Enforce everywhere.）"理念，最终落地为 Host 与策略层之间清晰、可审计、失败即关闭的决策契约。

• 人工智能
• AI Agent
• AI 安全治理
• 策略引擎
• Agent 沙箱
• 认证鉴权