智能体安全协议 openguardrails/openguardrails-spec

OpenGuardrails

面向 AI 智能体安全与防护的厂商中立协议，以及给厂商排名的中立基准。

安全与防护只集成一次，就能在每一个智能体和 LLM 上生效，不必再手工把每家厂商接到每个工具上。

Apache-2.0 · openguardrails.com

这个 monorepo 是 OpenGuardrails（OGR）规范及其参考集成的家。规范是每个集成和检测器都要遵循的规范性契约；集成、基准、示例、技能和网站都与它放在一起，这样改动可以一起评审、一起测试。

OGR 不是防护产品：它定义通信协议，并为排行榜担任裁判。厂商在统一的插口后面比拼检测质量，用户则获得一种统一方式，为自己运行的每个智能体配置和组合安全与防护能力。

- 我们定义通信协议——分层模型、事件、判定、组合、分类体系。
- 我们担任基准的裁判。
- 我们不构建检测能力——厂商在契约后面竞争。

分层模型：OGR 与 OSI 并列

这是协议的基础概念。 OGR 之于智能体流量，就像分层网络模型之于数据包——它的构建方式也像防火墙：集成一次只看一个事件，就像防火墙一次只看一个 IP 数据包；运行时则重组它之上的一切，并从载荷中读出它之下的一切。

| # | OGR 层 | 网络类比 | 一个单位是 |
| L6 | 会话 | ——（本领域自有层） | 一次对话 |
| L5 | 轮次 | ——（本领域自有层） | 一条指令 → 静默 |
| L4 | 步骤 | 传输 | 一次模型调用：请求 + 响应，按 step_id 配对 |
| L3 | 事件 | 网络——数据包 | 一个 GuardEvent，半个步骤——通信协议上唯一的层 |
| L2 | 调用 | 链路 | 模型请求的一次工具调用 |
| L1 | 执行 | 物理 | 机器上的一次真实执行——由模型命名，不由契约承载 |

和数七：传输层之上，网络只剩「应用」一层，但智能体的流量就是一场结构稳定的对话，所以 Turn 和 Session 是这个领域自己的层，在这里定义，而不是映射到 OSI 里那两层早已名存实亡的会话层/表示层。而且智能体是端点，不是层——它零流量也能一直存在，会话属于它，就像 TCP 连接属于一台主机，寻址靠每个事件都携带的四元组。协议栈旁边还有每条防火墙都有的实体轴：租户（API key）、workspace = 安全区（一个区一套策略）、agent = 主机，从流量里发现并汇入清单。

每个事件都在集成仍能拒绝它的那一刻拿到裁决——请求在模型看到它之前，响应在智能体据此行动之前：

your own agent · harness plugins gateway integrations (two POSTs at the loop's seams) (an LLM proxy: Higress, …)
│ │
│ raw provider bodies + step_id │
▼ ▼
┌───────────────────────────────────────────────┐
│ OGR core contract │
│ GuardEvent · Verdict · │ │ composition · taxonomy │ └───────────────────────────────────────────────┘ ▲ │ detector plugins (config rules OR model/classifier)

同样的六层，换五种说法

智能体框架早就给这类流量起了名字。它们能对上：

| # | OGR | 网络（OSI / TCP-IP） | OTel GenAI | OpenAI Agents SDK | Claude Agent SDK | LangGraph |
| L6 | Session——一次对话 | 没有对应 OSI 层——防火墙的会话表、空闲老化 | gen_ai.conversation.id （无 span） | Session / SQLiteSession id；一条 trace 的 group_id | 会话——session_id、resume、fork | thread——thread_id + checkpointer |
| L5 | Turn——一条指令 → 静默 | 没有对应 OSI 层——一条流的 FIN / RST / 超时 | invoke_agent span | 一次 Runner.run()——一条 trace | 一次 query() 提示词，直到它的 ResultMessage | 图上的一次 invoke() / stream() |
| L4 | Step——一次模型调用 | transport（OSI L4） | 推理 span，chat {model} | generation_span / response_span——他们的「turn」 | 一轮循环往返——他们的「turn」（max_turns） | 一次模型节点执行（before_model → after_model） |
| L3 | Event——半个 step，线上单位 | network（OSI L3）——数据包 | 那个 span 的 start / end | 那个 span 的 start / end | 输出 AssistantMessage；工具结果搭下一条 UserMessage | 聊天模型 invoke() 前后的两个时刻 |
| L2 | 调用 — 一次工具调用 | 数据链路（OSI L2） | execute_tool span | function_span | 一个 tool_use 块；PreToolUse 是它的闸门 | 一次 ToolNode 调用；wrap_tool_call 是它的闸门 |
| L1 | 执行 — 一次真实执行 | 物理层（OSI L1） | — | — | Bash / Edit 在主机上实际做了什么 | 工具函数实际做了什么 |
| — | 智能体 （实体，不在栈上） | 主机 / 端点 | gen_ai.agent.id / .name | Agent 对象（agent_span）；交接会切换它 | 智能体，以及每个子代理 | 编译后的图 |
| — | 工作区 · 租户 | 安全区 · 管理边界 | (deployment.environment.name) | — | — | — |

这些编号一路对齐到 L4，是有意为之。 执行/调用/事件/步骤分别落在物理层/链路层/网络层/传输层，数据包在两列里都是 L3。传输层往上，两列就分开了：网络只有「应用层」，因为网络应用之间没有共同结构——智能体的流量是一场对话，结构稳定，所以轮次和会话是这个领域自己的 L5 和 L6，不是 OSI 的会话层和表示层（这两层实践中已被丢弃）。

⚠️ 「轮次」在三个 SDK 中的两个里，指的是本栈的步骤。 在 OpenAI Agents SDK 和 Claude Agent SDK 里，轮次都是智能体循环的一次迭代——一次模型调用，加上它触发的工具运行——max_turns 数的就是这个。OGR 的轮次是用户指令片段，包含这些迭代：一次 Runner.run()、一次 query() 提示词、一次图 invoke()。同一个词，差一层。（OpenAI Agents SDK 文档两种含义都用：max_turns 数循环迭代，而「聊天对话中的单个逻辑轮次」是一次 Runner.run()——一个 OGR 轮次。）

完整映射——包括 session_hint 该发什么、为什么 SDK 的钩子（PreToolUse、wrap_tool_call）是强制执行点而追踪 span 不是、交接如何移动实体轴而不是栈——见 Overview § The layer model in harness vocabularies。

规范文本：Overview § The layer model。

五分钟集成你的智能体

整个协议就是一个端点，每次模型调用两次请求。你原样转发已经发给 LLM、并从 LLM 收到的请求体；其余的事（会话、轮次、分解、检测）由运行时完成。默认失败开放：运行时不可达时，你的智能体照常运行。

import uuid, requests

OGR = "https://ogr.example.com" # your runtime's base URL
KEY = "ogr_xxxxxxxx" # your organization API key

The identity four-tuple. All four always present; "" = nothing to assert
(the runtime then derives identity from the API key).
IDENTITY = {
"agent_id": "invoice-bot", # WHICH agent — unique in your org "agent_type": "my-harness", # what KIND — a label, never policy "agent_workspace": "finance-agents", # agent GROUP — one policy set "agent_user": "u-8232", # who is USING it this session }

SESSION = uuid.uuid4().hex # optional session_hint: one id per conversation —
sessions become declared instead of inferred

def evaluate(kind, step_id, payload):
"""The whole protocol is this one call. Fail-open: no verdict → proceed."""
try:
r = requests.post(f"{OGR}/v1/evaluate",
headers={"Authorization": f"Bearer {KEY}"},
json={"kind": kind, "step_id": step_id,
"llm_protocol": "openai.chat",
"session_hint": SESSION,
*IDENTITY, "payload": payload},
timeout=5)
return r.json() if r.ok else None
except requests.RequestException:
return None

def blocked(v):
return v is not None and v["decision"] == "block"

your agent loop, with the two calls added:
while True:
step_id = uuid.uuid4().hex # binds this call's 2 events
body = {"model": "gpt-5", "messages": messages, "tools": TOOLS}
if blocked(evaluate("step/request", step_id, body)): # ① before the model
break
resp = call_llm(body) # your code, unchanged
if blocked(evaluate("step/response", step_id, resp)): # ② before acting on it
break
... # execute tool calls, loop

可运行版本（带流式）：examples/minimal-agent/。
完整契约：Runtime API —— 其中包括一次完整交互：一次模型调用的两半完整写出，并附各自返回的裁决。

接入时最先冒出来的问题 —— 该声明哪个 llm_protocol、协议不在我们列表里时该发什么、换个模型为什么不等于换一套集成 —— 都在 协议 FAQ 里有答案。

为什么要定标准

没有 OGR，给智能体做安全就是 N × M × L 的集成难题：每个智能体、每家检测厂商、每种 LLM 协议都要两两对接。OGR 把它压成 N + M + L —— 对着契约集成一次就行。

两层：API → 插件

没有 SDK 层。 API 就是集成面 —— 一个决策端点加一份配方 ——智能体开发者直接调用它来集成：

| 层 | 是什么 | 位置 |
| API | 运行时（PDP）暴露的线上契约：POST /v1/evaluate（裁决 + 记录）、心跳、健康检查 —— 承载 GuardEvent，返回 Verdict。 | Runtime API 绑定 + JSON Schema |
| 插件 | 位于一个席位上的代码——在智能体框架内、在作为字节路径的网关产品内，或在组织自有服务旁的独立桥接器中——观察步骤、构建事件并执行裁决，直接使用 API 通信。 | integrations/ |

规范性组件

| 组件 | 定义内容 | OTel 对应物 |
| 概览 | 分层模型与集成面 | — |
| GuardEvent | 在集成点观察到的类型化单元 | span / log record |
| Verdict | 运行时对事件做出的决定 | — |
| obligations | 执行点在动作继续之前必须做什么——随 allow 一同携带 | XACML obligations |
| mandate | 授权信封——工作区中的智能体可以做什么；属于配置，绝不上线传输 | — |
| grounding | 证据信封——智能体可以声称什么，需对照记录服务商校验；属于配置，绝不上线传输（1.7 草案） | — |
| provenance | 因果信封——是什么导致了某个动作；信任在运行时中推导，仅有一个可选的上线字段（sources）用于运行时无法推导的部分（1.10 草案） | — |
| artifact scan | 扫描器实现的同级契约——哈希优先、范围协商、可插拔 | ICAP |
| local redaction | 进程内集成要做什么，才能让密钥永不离开主机——出口时遮蔽，进入工具时还原，规则由运行时提供 | — |
| composition | 多个检测器的答案如何合并成一个决定 | — |
| degraded mode | 运行时不可达时集成要做什么（默认：失败开放） | — |
| Runtime API | 运行时暴露的 HTTP 绑定、配方以及最小集成 | OTLP/HTTP |

风险类别位于分类法中（safety. 和 security.），有版本、可替换——契约引用类别 ID，但对什么算「不安全」保持中立。

两个领域，一份契约

- 安全（Safety）——有害的内容/行为（毒性、自残、CSAM、品牌、话题）。多数在内容 I/O 边界由分类器判定。
- 安全（Security）——系统失陷（提示词注入、数据外泄、恶意命令、SSRF、密钥泄露、供应链）。基于动作和数据流判定——即工具调用即将做什么。

契约统一；流水线和执行点不同。从概览开始。

一致性与基准

- 检测器若接受 GuardEvent 并返回一个针对 JSON Schema 校验 Verdict 是否合法。参见 CONFORMANCE.md。
- 基准测试在共享语料上评估符合规范的检测器，并发布排行榜。

Monorepo 布局

| 路径 | 内容 |
| specification/ 和 schema/ | 规范性协议、schema（JSON Schema + OpenAPI）、分类体系、一致性规范与治理。 |
| integrations/ | 网关插件、独立桥接和智能体插件，各自直接调用 API。 |
| benchmarks/ | 中立的检测器基准测试与排行榜。 |
| examples/ | 可运行的最小集成示例（minimal-agent/）。 |
| skills/openguardrails/ | 用于起草和执行策略的智能体技能。 |
| — | openguardrails.com 位于独立仓库；本仓库只存放它文档化的协议和插件。 |

集成状态

v0.6 的 SDK 包已在 v0.7 中退役——API 就是集成面。v0.8 把两套集成方案合并为一套，下面每个集成都遵循它（v1.0 发布的线上协议保持不变）：

| 类别 | 目标 | 状态 | 本地脱敏（1.4） |
| 网关插件——位于产品内部，本身就是字节通路 | Higress（Go/WASM） | integrations/gateway/higress——参考网关插件 | 不适用（运行时替它做掩码） |
| | OpenAFW（Rust，本地 AI 防火墙） | integrations/gateway/openafw——代码位于独立仓库 | 是——minter F |
| | OpenAI/Anthropic 示例 · mitmproxy | 当前 | 不适用（运行时替它做掩码） |
| 独立桥接——你自己的服务向它投递消息的进程 | Java（/guard/v1/step/） | integrations/bridge/java | 不适用（运行时替它做掩码） |
| 智能体插件——位于 harness 内部 | DeepSeek Harness（dsh） | integrations/agent/dsh——参考智能体直连集成 | 否 |
| | litellm | integrations/agent/litellm——当前 | 否 |
| | Hermes · opencode · OpenClaw | 当前 | 2.0 / 0.4 / 0.4（进行中） |
| | Claude Code · Codex · LangGraph | 当前 | 否 |

开发

benchmark tests
python -m pip install pytest && python -m pytest

higress plugin
cd integrations/gateway/higress && go test ./...

dsh plugin (npm workspace)
npm install && npm run build && npm test

原则

1. 中立。 协议开放，由基金会治理；基准测试是裁判，不是参赛者。
2. 规范边界，不规定大脑。 检测能力保持竞争。
3. 按 harness 的方式命名循环。 会话、轮次、步骤、调用——一个集成永远不该为了对接协议而翻译自己的词汇。
4. 协议只承载生产者才知道的信息。 身份和步骤配对 id 由生产者声明；其余一切可推导的内容——会话、轮次、编号、时间戳、协议版本——都是运行时的职责，这样集成才能保持无状态。

状态

当前协议版本：v1.10（协议版本见 CHANGELOG.md）。协议就是 2026-08 宣布稳定的 v1.0 那一版：此后所有改动都是增量可选的（additionalProperties: false 拒绝的是未知键，不是缺失的键，所以两端可以各自独立向前滚动），因此按 v1.0 写的集成今天仍然合规，并且可以一次增加一个键。
⚠️ 每个键都先在运行时上线——领先一个版本的生产者会发送严格 schema 不认识的键，结果就是它发送的每个事件都收到 400。任何破坏性改动都是新的主版本。规范如何演进见 GOVERNANCE.md。欢迎贡献——CONTRIBUTING.md。

许可证

Apache-2.0。