decionis/agent-safe-pipeline · 上手攻略

  • 仓库：decionis/agent-safe-pipeline
  • 链接：https://github.com/decionis/agent-safe-pipeline
  • 分类：agent-safety / gateway / authorization
  • 作者：spark
  • 更新：2026-09-20

是什么

AgentSafe 是一个「执行权限网关」(execution-authority gateway)，放在 AI agent 或内部 API 前面，对 HTTP 写操作做集中裁决。Agent 不直接调目标服务，而是把请求发给 AgentSafe；AgentSafe 把请求捕获成一个 intent，向 Decionis（独立执行权限机构，Independent Execution Authority）询问，组织级策略回答三种结果之一：

  • ALLOW：附一次性执行凭证（single-use grant），原样转发一次。
  • ESCALATE：把请求挂起，由 Presence（人在回路的真人核验层）在本人设备上确认该精确动作。
  • BLOCK：直接拒绝。

每个动作都留下一个 chained 证据行（Decision Dossier），事后可离线校验。本仓库本身 不决策，只负责截获意图、问 Decionis、转或挂。许可证 Apache-2.0。

解决什么问题

传统 IAM 绑在「身份」上，而 agent 场景的真实威胁不是伪造凭证，而是「凭证有效、身份真实，但请求不是任何人授权的」（compromised principal）。AgentSafe 把授权绑在「精确动作」而不是「请求者」上，并通过 Decionis + Presence 的二阶段把关，让一笔支付、一次 DELETE、一条对未公开接口的写入，都先被问一句「这事是被允许的吗」。仓库自带 Compromised Principal Test 验证这一点。

快速安装

1. Homebrew（macOS）

brew tap decionis/agent-safe https://github.com/decionis/agent-safe \
  && brew trust decionis/agent-safe \
  && brew install agentsafe

2. Linux 安装脚本

curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/v0.3.0/packaging/install.sh | sh

3. Docker

mkdir -p secrets && (umask 077; printf '%s' "$DECIONIS_API_KEY" > secrets/decionis-api-key)

docker run --rm -p 8080:8080 \
  -e AGENTSAFE_LISTEN=:8080 \
  -e AGENTSAFE_UPSTREAM=http://host.docker.internal:3000 \
  -e AGENTSAFE_UPSTREAM_INSECURE=true \
  -e DECIONIS_API_KEY_FILE=/var/run/agent-safe/secrets/decionis-api-key \
  -e DECIONIS_TENANT_ID=<your organization id> \
  -v "$PWD/secrets:/var/run/agent-safe/secrets:ro" \
  ghcr.io/decionis/agentsafe:0.2.0

4. 从源码（开发模式）

要求 Node.js ≥ 22.14 与 pnpm 9：

git clone https://github.com/decionis/agent-safe-pipeline.git
cd agent-safe-pipeline
pnpm install --frozen-lockfile
pnpm --filter @decionis/agent-safe-pipeline build \
  && pnpm --filter @decionis/agentsafe build
alias agentsafe="node $PWD/packages/agentsafe/dist/Cli.js"

版本核对：当前 release 为 v0.3.0（npm tarball / 安装脚本 / Homebrew formula / SHA256SUMS 都走 v0.3.0）。⚠️ 容器镜像 ghcr.io/decionis/agentsafe 仓库里标注为 0.2.0（sha256 76f8d071…3651f，distroless、非 root、Node 权限模型），release 页说明 image 由 release workflow 自 v0.2.0 起推送；上线前请以 GitHub Releases 页 v0.3.0 是否同步推进 image tag 为准——若仍停在 0.2.0，先用安装脚本 + 源码构建过渡。

核心用法

第一步：五分钟自测边界（不依赖 Decionis 账号）

agentsafe test

会向一个 loopback 合成目标发 8 类写请求，对比「直连 / shadow / enforcement」三种模式。预期输出末尾：

Exposure     6 of 6 adversarial actions reached the target directly, 6 of 6 in shadow, 0 of 6 under enforcement
Work         routine actions went through under enforcement, once each
Evidence     26 chained lines, verified
Caller       the same on every row, and never the reason
Verdict      BOUNDARY HOLDS

退出码 0 表示边界成立；1 表示存在绕过；--json 给一行报告。仓库里的 release smoke test 也在每个打包产物上跑这一项。

第二步：跑一次真实的代理

先准备一个 HTTP 上游：

node -e 'require("http").createServer((q,s)=>{s.writeHead(201,{"content-type":"application/json"});s.end("{\"ok\":true}")}).listen(3000)' &

再启网关：

agentsafe proxy --upstream http://localhost:3000 --port 8080

未配 Decionis key 时，网关会在同进程内启一个本地 demo authority（loopback 合成策略，每一行都标注 Authority local/demo (synthetic policy on loopback; not Decionis)，别误以为是真策略）。演示策略：

  • amount 或 amountMinor 在 (100, 1 000] → ESCALATE
  • amount > 1 000 → BLOCK
  • DELETE、body 不可读 → ESCALATE
  • 其余 → ALLOW
  • Decionis 不可达 → 默认 fail-closed（503 NOT FORWARDED）

第三步：发请求，看三种决策

curl -i -X POST http://127.0.0.1:8080/payments \
  -H 'content-type: application/json' \
  -d '{"amount": 500}'     # → 202 ESCALATE HELD
curl -i -X POST http://127.0.0.1:8080/payments \
  -H 'content-type: application/json' \
  -d '{"amount": 50}'      # → ALLOW, 一次性转发, 响应头带 agentsafe-decision / agentsafe-dossier-id / agentsafe-execution: FORWARDED
curl -i -X POST http://127.0.0.1:8080/payments \
  -H 'content-type: application/json' \
  -d '{"amount": 5000}'    # → 403 BLOCK, 不转发

GET 不被视为 consequential，原样透传。

第四步：连真实 Decionis（先 shadow）

agentsafe login              # 把 key 存到当前用户可读的本地
export DECIONIS_TENANT_ID=...  # 如 login 未写入
agentsafe doctor            # 二进制 / 配置 / upstream / Decionis / 凭证 / 证据 一并体检
agentsafe proxy --upstream http://localhost:3000 --port 8080

Mode 变 SHADOW：每个 consequential 请求原样通过，Decionis 记录它「本会怎么判」。验一段时间再切 --mode enforcement。

第五步：看证据 / 离线验链

agentsafe proxy --upstream http://localhost:3000 --port 8080 --verbose

或在 agentsafe.yaml 设 evidence.journalDir，每一步（捕获 intent / authority 决策 / grant 消费 / 执行 / 终结）都写一行到 evidence.jsonl，然后：

agentsafe verify chain evidence.jsonl

典型适用场景

  • Agent 对接内网写接口：把 agent 从「能访问内部所有写入路径」降到「每次写入都要被网关问一句」。
  • 支付 / 计费 / 退款 / 删除客户记录 等高风险动作的统一闸门：金额 / 资源 ID 直接走策略，超过人类上限的请求必须 Presence 真人确认。
  • 多 agent 协作：把策略集中到 Decionis，组织策略改了，所有 agent 立刻生效，无需逐个 agent 改代码。
  • 影子模式灰度：先 shadow 一周看 Decionis 会拒什么，再 enforcement。
  • 合规与审计：每个动作的 chained 证据行可直接喂给 SOC/审计。

坑与注意

  • ⚠️ 演示策略 ≠ 真实策略。不设 Decionis key 时的本地 demo 只是为了让你 5 分钟内看到三态决策，别在演示策略下当成生产行为。
  • ⚠️ 镜像版本落后于 release tag：当前 GitHub Releases 走 v0.3.0，GHCR image 标签仍为 v0.2.0；上线前确认 image tag 是否跟进，否则用安装脚本或源码构建过渡。
  • ⚠️ 默认 fail-closed。当 Decionis 不可达，缺省是「503 NOT FORWARDED」，可设 failurePolicy failOpen，但仓库与 README 都强调「fail-open 即 ungoverned」，必须明示同意才开。
  • ⚠️ 容器内拒演示策略 + 拒环境变量 key。image 强制 NODE_ENV=production：在这个模式下本地 demo authority 拒绝启动，key 也必须以文件挂载，不能写在 env。要在容器里跑 agentsafe test 必须先 unset NODE_ENV。
  • ⚠️ Key 文件权限。挂载到 /var/run/agent-safe/secrets/decionis-api-key 的文件必须能被容器用户 65532 读到（chmod 0440 + chown :65532），否则 Decionis 调用直接失败。
  • ⚠️ Plain-HTTP 上游需要显式声明。AGENTSAFE_UPSTREAM_INSECURE=true 是「容器到 plain-http upstream 的这一跳由网络保护」的声明；https:// 上游不需要。
  • ⚠️ POST /payments 示例的金额字段名。demo 策略读 amount 或 amountMinor（minor units，整数分）。生产集成时把字段对齐到策略。
  • ⚠️ agentsafe test 不读你的凭证。它跑在 loopback 合成目标上，不会触发任何外部副作用，但 ledger=<host:port> 参数会让它真的拨号判定对方「不绕网关能否被直连」——这是有副作用的探测，慎用。

与同类对比

  • 相对 OAuth2 / API Gateway (Kong/Apigee)：传统网关绑身份 + scope；AgentSafe 绑「精确动作 + 单次 grant」，且把决策权外置到独立机构 Decionis，避免「网关本身被攻陷就等于策略失守」。
  • 相对 OPA / Cedar / Casbin（策略引擎）：这些是「问策略」，但不强制执行「一次性、绑定到具体动作」的执行凭证；AgentSafe 在网关层把「policy decision + execution grant + chained evidence」打包成一个原子单元。
  • 相对 human-in-the-loop 框架（HumanLayer / LangGraph interrupt）：后者把「人确认」嵌进 agent 循环，绑代码；AgentSafe 把这一层独立成 Presence 设备侧核验，绑网络层。
  • 相对 prompt-injection 防护：AgentSafe 不判读 agent 说了什么意图，它只问「这一次 HTTP 写动作有没有被授权」。是把「意图恶意」与「执行越权」切成两层。

一句话推荐结论

把 AI agent 接进有写权限的内网时，最薄且最值得加的一层就是 AgentSafe——它用 Decionis 做策略、用 Presence 做真人核验、用 chained evidence 做审计，三件事用一个 5 分钟自测就能验。

字数：约 1 950 字（中文 CJK 估）。来源：GitHub repo README、docs/quickstart/README.md、docs/install/docker.md、GitHub Releases 页（v0.3.0 / image 0.2.0）。不确定处：① 容器 image 是否已随 v0.3.0 release 同步推送（README 注明自 v0.2.0 起推送，releases 页列出 image 为 0.2.0），上线前需在 GHCR 重新核对；② Decionis 与 Presence 的托管版价格 / SLA 不在本仓库内披露，需到 decionis.com 与 presence.decionis.com 各自确认。