Vizier Guard

Vizier

在 AI Agent 执行操作前进行范围限定的授权。

Vizier 会根据由所有者签名的权限检查 Agent 提议的操作。 它会返回 ALLOW、BLOCK 或 REVIEW，并附上策略结果和与请求绑定的 回执。集成方只有在验证授权后，才会调用受保护的工具。

可在 Agent 或定期运行的工作流的操作边界使用它：在部署、仓库写入、 数据库更改、发送消息或调用支付 API 之前。 持续运行的 Agent 可以获得针对特定操作和目标的短期权限，同时所有者仍掌控签名密钥。

Playground · 在线 API 参考 · OpenAPI · 委派设置 · 威胁模型

选择集成方式

你的任务	从这里开始	前提条件
在本地试用部署适配器	合成数据准备示例	Node 24+；准备步骤无需密钥
使用签名委派验证操作	SDK 设置	操作员 API 密钥、已注册的公钥和所有者签发的授权
保护现有 MCP 工具	私有 MCP 代理	由操作员管理的上游凭据和受限工具路由
检查托管 API	API 参考	公开文档；执行权限另行管理

控制 Agent 的基础设施部署

面向运行 DevOps Agent 的平台和安全团队：固定使用一个现有的 Cloudflare Worker，并要求提供所有者签名的范围，以及由人工批准 即将上传的确切版本，之后才能更改其流量。版本发生变化、目标超出范围、 权限过期或重复提交审批声明时，都会在执行前停止。云凭据和执行器应始终 处于 Agent 控制范围之外。

从 npm 安装 v0.5.14 SDK 和部署适配器（Node 24+）：

npm install @agenda-intelligence/[email protected] @agenda-intelligence/[email protected]
npx --no-install vizier-worker-deploy prepare \
  --scope node_modules/@agenda-intelligence/vizier-gated-deploy/examples/scope.json \
  --plan node_modules/@agenda-intelligence/vizier-gated-deploy/examples/plan.json

准备工作在本地进行，使用合成 ID，无需密钥。在提交真实审批或执行任何操作前， 请遵循集成与恢复指南。 在线沙盒跟踪记录展示了针对生产环境 Vizier 和一次性 Cloudflare Worker 的八种场景，其中包括一个在 v0.5.10 中修复的真实 API 响应不匹配问题。此适配器安装在操作员的执行器中；托管 MCP 端点提供的是验证， 而非云部署。自动化离线测试套件会模拟 Cloudflare；链接的维护者沙盒跟踪记录 使用了真实 API，但不代表外部客户采用。

申请范围限定的集成 · 辅助试点集成包含哪些内容

付费服务是针对一个双方约定工作流的辅助集成。托管订阅和持续支持是后续可与买方 商定范围的选项；目前没有自动结账或自助付费方案。代码仍采用 MIT 许可。 不声称已有外部客户采用，也不声称可防护 IoT 恶意软件。

工作原理

flowchart LR
    Owner[Owner-controlled signer] -->|Scoped, expiring grant| Guard[Tool guard or MCP proxy]
    Agent[Agent proposes action] --> Guard
    Guard -->|Action + grant| Vizier[Vizier policy service]
    Vizier -->|Decision + receipt| Guard
    Guard -->|Validated ALLOW| Tool[Protected tool]
    Guard -->|Submit REVIEW explicitly| Human[Human review workflow]

1. 所有者签署 ES256 委托：主体、Agent、允许的操作、约束和过期时间。运营方只在 Vizier 中注册公钥。
2. 集成将预期操作和授权提交到 /v1/verify。
3. Vizier 验证签名、身份、过期时间和精确的权限绑定，然后评估确定性策略。此决策路径中不会运行大模型。
4. 守卫在调用工具前验证响应和请求绑定。BLOCK、REVIEW、无效响应以及授权不可用都会中止该路径。

API 密钥用于验证调用方身份。委托授权用于证明所有者的许可。 两者职责不同。请求无法扩大有效授权中的权限；无效授权会被阻止。

截至 2026 年 9 月 30 日，托管部署使用 VIZIER_SIGNED_GRANT_MODE=required。未签名的验证请求会返回 BLOCK / GRANT_REQUIRED。托管环境中的 ALLOW 需要运营方注册的主体密钥、有效且匹配的授权，并通过策略检查。请查看 /docs 了解当前部署设置。可自托管的可选模式允许调用方自行声明权限；其收据不能证明所有者委托。

正在使用的集成

Agenda 机群在所有者运营的部署工作流中使用 Vizier。这是同一维护者的实际运营使用，并非外部客户采用。

工作流	受保护的操作	查看证据
Agenda Worker 机群	部署前进行目标范围限定的 deploy_worker 授权	公开工作流 和成功的签名部署

该工作流将签名与执行步骤分开，并提供短时有效的所有者签名授权。缺少或过期的授权，以及无效的必需收据，都会中止该部署路径。仍保留直接 Cloudflare 访问权限的运营方拥有独立的平台权限；Vizier 不会移除这些权限。

从签名委托开始

实验性功能。 可运行示例固定使用已发布的 npm 客户端 v0.5.14。服务和客户端版本分别跟踪。TypeScript 包使用自有的 @agenda-intelligence npm 组织：SDK、MCP 代理和部署适配器。较早的 GitHub 存档保留了原有的 @vizier/* 名称；从这些存档切换到 npm 时，请更新导入项。

npm install @agenda-intelligence/[email protected]

首先，从所有者控制的签名器注册主体公钥并签发授权。此示例要求 platform-owner → release-agent 的授权，且权限必须严格如下：

{
  "allowed_actions": ["deploy_worker"],
  "constraints": {
    "allowed_targets": ["worker:example-worker"],
    "allowed_sensitive_actions": ["deploy_worker"]
  }
}

请将私有签名密钥保存在执行操作的 Agent 之外。向受信任的守卫提供集成 API 密钥和当前授权文件：

import { readFile } from "node:fs/promises";
import { Vizier } from "@agenda-intelligence/vizier-sdk";

const client = new Vizier({
  baseUrl: "https://vizier.agendamcp.dpdns.org",
  apiKey: process.env.VIZIER_API_KEY,
});

const grantPath = process.env.VIZIER_GRANT_FILE;
if (!grantPath) throw new Error("An owner-issued grant file is required.");
const grant = (await readFile(grantPath, "utf8")).trim();

const result = await client.verify({
  agent: { id: "release-agent", owner: "platform-owner" },
  principal: { id: "platform-owner" },
  action: {
    type: "deploy_worker",
    target: "worker:example-worker",
    parameters: { commit: "reviewed-commit" },
  },
  authority: {
    allowed_actions: ["deploy_worker"],
    constraints: {
      allowed_targets: ["worker:example-worker"],
      allowed_sensitive_actions: ["deploy_worker"],
    },
  },
  context: { request_id: null, timestamp: null, source: "rest" },
  grant,
});

// The SDK validates the response contract and recomputes the request hash.
const proof = result.receipt.grant;
if (
  result.decision !== "ALLOW" ||
  result.receipt.authority_provenance !== "principal_signed" ||
  proof?.issuer !== "platform-owner" ||
  proof?.subject !== "release-agent" ||
  Date.parse(proof.expires_at) <= Date.now()
) {
  throw new Error("Stop: no valid signed authorization for this action.");
}

// Invoke the fixed protected deployment here; record its actual outcome.
console.log("Authorized request:", result.receipt.id);

该示例会授权一项操作，但不会执行部署。未知主体或密钥会被阻止。若使用自己的服务来源，请同时更新客户端 URL 和授权受众。授权设置与轮换涵盖完整的运营方流程。

若要建立 MCP 边界，请从 npm 安装 SDK 和代理：

npm install @agenda-intelligence/[email protected] @agenda-intelligence/[email protected]

请将强制代理配置与运营方拥有并轮换的授权文件搭配使用。Agent 连接到代理；必须移除其直接上游路由和下游凭据。仅将 Vizier 作为可选 MCP 工具公开，并不能强制建立工具边界。

通过 MCP 连接

在 Glama 上，请使用托管的 Vizier 连接器， 查看实时工具目录并检查连接。代码仓库列表采用独立的 Docker 发布生命周期，并非托管端点。

对于支持 Streamable HTTP 的客户端，请使用 https://vizier.agendamcp.dpdns.org/mcp。托管服务为 Vizier v0.5.14， 并提供一个工具：vizier_verify_action。发现服务无需 API 密钥。构造请求前，请读取其 inputSchema 和 com.vizier/readiness 元数据；源材料是数据，绝不是指令或委托的权限。

会话握手支持 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05：先发送 initialize，然后在 notifications/initialized 和 tools/list 中使用返回的修订版设置 MCP-Protocol-Version。独立的 2026-07-28 无状态配置从 server/discover 开始， 并要求每个请求都包含 _meta，且 MCP-Protocol-Version 和 Mcp-Method 标头匹配。不要将其元数据与会话 initialize 混用。 连接错误会在 error.data.connection_hint 中包含支持的配置和标头要求。重试前，请先更正被拒绝的连接请求；发现响应不授予任何执行权限。

连接前，请 GET /mcp 或 /.well-known/mcp-probing.json，并从 connection_guide.recovery_requests 中选择一套完整序列。默认推荐使用会话 2025-11-25；独立的无状态序列使用 2026-07-28。每套序列都包含相应的标头、元数据和只读后续请求，因此不会将扁平列表中的版本误认为通用握手。不会自动重试任何请求。

提示会推荐一种配置和受支持的公开修订版，并尽可能保留已识别的客户端修订版。对应的 recovery_requests 条目会提供初始请求及按顺序排列的 follow_up_requests：会话模式为 initialize → initialized 通知 → tools/list；无状态模式为 discover → tools/list。请明确选择一种序列。automatic_retry 为 false；序列中绝不包含 tools/call，也不会重放被拒绝的操作。不会将未知的客户端字符串复制到指引中。混用配置的请求仍会被拒绝。

未知工具名称会返回 error.data.tool_hint，其中包含已公布的名称，以及针对所选配置、可执行且只读的 tools/list 恢复请求。请执行该发现请求，并在发起新调用前检查返回的 inputSchema。automatic_tool_retry 为 false：服务端绝不会重放操作，也不会猜测调用方想使用的工具。协议或版本不匹配仍会报错。

连接观测结果仅包含服务端选择的配置和修订版类别：受支持的公开日期、missing、other、invalid 或 unmeasured。不会包含原始客户端修订版、标头或请求文本。较早的事件无法确定是哪个修订版或配置导致了拒绝。

对于仅支持 stdio 的客户端，此固定版本的传输适配器会连接到同一个托管工具：

{
  "mcpServers": {
    "vizier": {
      "command": "npx",
      "args": [
        "-y", "[email protected]",
        "https://vizier.agendamcp.dpdns.org/mcp",
        "--transport", "http-only"
      ]
    }
  }
}

此配置会将调用发送到托管服务，并采用匿名方式： 验证结果可以是 BLOCK 或 REVIEW，绝不会是 ALLOW。它不会执行任何受保护的操作。要执行强制控制，可信集成需要提供其现有凭据，以及与实际请求匹配的有效所有者签发授权；请参阅 授权设置。请将私有签名密钥保存在 Agent 之外，也不要将凭据粘贴到工具参数中。 单独进行版本管理的 Python vizier-guard v0.3.3 stdio 辅助工具公开了 vizier_screen_action、vizier_verify_receipt 和 vizier_check_policy。该 本地目录不是托管授权服务：其本地 ALLOW 并非由主体签名的委托，其回执辅助工具也不会验证 JWS 签名。对于上述签名授权工作流，请使用托管工具以及维护中的强制执行 SDK/代理。根 npm 工作区为私有： npm install vizier 并非本项目的安装命令。TypeScript 包按上文链接所示，以 @agenda-intelligence/vizier-* 名称发布。

Python SDK 0.3.3 修复了 stdio 会话版本协商问题。请从 GitHub Release v0.5.13 安装经过测试的 wheel：

python -m pip install https://github.com/vassiliylakhonin/vizier/releases/download/v0.5.13/vizier_guard-0.3.3-py3-none-any.whl

该 wheel 是 GitHub Release 发行包；这并不表示它已发布到 PyPI。

接口和功能

如需开展范围明确的基础设施试点，请参阅Worker 版本部署。 可安装的适配器会固定使用一个现有 Worker，并要求提供所有者签名的范围，以及在调用 Cloudflare 之前由人工批准确切版本。离线演示使用真实的授权/审核处理程序和模拟的 Cloudflare 响应； 它不会创建基础设施，也不能作为外部采用的证据。

表面	作用
REST /v1/verify	使用确定性策略、委托来源信息和绑定请求的回执检查操作
TypeScript SDK	验证响应契约和绑定；包含明确的人工审核辅助工具
Python SDK	标准库客户端、函数防护和框架适配器
MCP 服务	发现并调用验证工具；清单
MCP 强制执行代理	拦截已配置的工具调用、验证授权，并转发获准的调用
A2A	验证适配器和 Agent 卡片
人工审核队列	独立的审核者凭证、签名批准令牌和原子服务器声明

策略涵盖允许的操作、目标、金额限制、敏感操作和已配置的审核要求。SDK/代理断路器可 限制重复工具调用和会话预算。其他审核工作流和金融预留各自有独立的契约和部署要求； 请参阅在线参考文档和 金融预留限制。

回执和信任边界

/v1/verify 回执会记录请求哈希、决策、规则结果和权限来源信息。旧版验证回执本身未经签名； principal_signed 决策所依据的授权由所有者签名。SDK 会检查响应一致性，并基于规范化 JSON 重新计算请求哈希。 回执记录的是授权，而非工具已成功执行的证明。

旧版 Action Covenant 和人工审核令牌使用独立的签名回执格式。必需授权模式会阻止旧版 covenant 授权， 因为该入口不携带委托授权。使用兼容接口之前，请参阅 covenant 契约和 威胁模型。

Vizier 是应用层授权服务。集成负责执行其决策。拥有直接工具凭证的 Agent 或管理员可以绕过该集成。 短期授权并非一次性执行预留。提供的证据未经独立验证；授权也不能证明事实真实、已获得法律许可、付款已结算或存在客户需求。

开发

Worker 和 TypeScript 包需要 Node.js 24+。

npm ci
npm run check

check 会运行包构建、类型检查、迁移检查、lint、测试和 Worker 部署试运行。它不会发布或部署。联网检查单独运行：npm run check:deployed 会检查生产环境构建包摘要；npm run check:live 会检查已部署服务和发现契约。

架构 · 声明 · 安全审查 · 试点范围 · 问题和集成反馈

MIT 许可证。