C3EQUALZz/agate
GitHub: C3EQUALZz/agate
Agate 是一个用 Rust 编写的 LLM Agent 安全网关，以无代码侵入的反向代理方式检查流量、执行安全策略并记录防篡改的透明度审计日志。
Stars: 1 | Forks: 0
# Agate
**一个专为 LLM agent 设计的安全网关 —— 一个内联反向代理，能够检查 agent 流量、执行策略，并将每一个决策写入防篡改的透明度日志。无需修改 agent 代码。**
[](https://github.com/C3EQUALZz/agate/actions/workflows/ci.yml)
[](https://github.com/C3EQUALZz/agate/actions/workflows/docker.yml)
[](https://C3EQUALZz.github.io/agate/)
[](https://sonarcloud.io/summary/new_code?id=C3EQUALZz_agate)
[](https://github.com/C3EQUALZz/agate/blob/main/Cargo.toml)
[](https://doc.rust-lang.org/edition-guide/rust-2024/index.html)
[](https://github.com/C3EQUALZz/agate/pkgs/container/agate)
[](LICENSE)
[文档](https://C3EQUALZz.github.io/agate/) ·
[快速开始](#quickstart) ·
[架构](#architecture-at-a-glance) ·
[示例](examples/) ·
[贡献指南](docs/en/contributing/index.md)
**English** · [Русский](README.ru.md)
## 为什么选择 Agate
现代的 LLM agent 会调用工具、改变状态，并将自由格式的文本流式传输回
前端。它们所使用的通信协议 —— [AG-UI](https://docs.ag-ui.com/) ——
是一个普通的 HTTP `POST` 请求加上一个 Server-Sent Events 流。它
**没有身份验证，没有针对每个事件的签名，没有大小限制**，
并且包含许多无类型的字段。就其本身而言，这意味着：
- 任何能够访问到该 endpoint 的人都可以控制这个 agent；
- 工具调用、状态改变和发出的文本都不受检查 —— 遭受 prompt 注入的
agent 可能会泄露机密或调用它本不该碰的工具；
- 没有可靠的记录来表明 agent 被要求做什么，或者它做了什么。
**Agate 在网络边缘弥补了这些缺陷。** 它位于你的 agent 前面，
终止 TLS 以便检查明文，对请求进行**边界限制**，逐个事件地
**检查**流式响应，应用**策略判定**
（允许 / 拒绝 / 转换 / 终止），并将每一个 `(event, verdict)`
对**追加**到可验证的 [RFC 6962](https://www.rfc-editor.org/rfc/rfc6962) Merkle
透明度日志中 —— 所有这些都无需对 agent 代码做任何改动。
## 功能
- **检查型反向代理** —— 将 Agate 放置在任何 AG-UI agent 前面；
它会在检查后转发流量，无论是请求还是 SSE 响应。
检查核心是协议无关的；AG-UI 只是其中一个适配器。
- **工具允许/拒绝策略** —— 通过 `allow-all`、`allowlist` 或
`denylist` 模式来管控 agent 可以调用哪些工具。
- **机密信息脱敏** —— 在发出的助手文本离开边界之前，
从中剥离已配置的机密标记（例如 `sk-`, `AKIA…`）。
- **RFC 6962 透明度日志** —— 每一个决策都会被追加到 PostgreSQL 中一个防篡改的、
仅追加的 Merkle 日志中，而不是简单的哈希链。篡改是
可检测的；包含性是可证明的。
- **密码敏捷性** —— 可插拔的、自描述的哈希 / 签名 / AEAD
策略（SHA-2/3、Streebog、Ed25519），算法标签随
每个摘要和签名一起传输。
- **TOML + 环境变量配置** —— 挂载 `agate.toml` 并支持基于键的环境变量
覆盖（`AGATE__SECTION__KEY`）；将机密信息保留在环境变量中。
- **Prometheus 指标** —— 在其独立端口（`:9090`）上提供可选的 `/metrics` endpoint，
远离公共数据面；在 `deploy/` 中提供了一个开箱即用的
[Grafana + Prometheus stack](deploy/observability/)。
- **优雅关闭** —— 在收到 `SIGTERM`/`SIGINT` 时，Agate 会清理正在处理中的请求，并在退出前
**刷新审计发件箱**；适用于滚动重启和
Kubernetes pod 终止。
- **容器原生** —— 每次推送到 `main` 分支以及发布 tag 时，都会发布到 GHCR（`ghcr.io/c3equalzz/agate`）。
## 快速开始
Agate 在 Docker 中运行。你需要一个 **AG-UI agent** 置于其后，以及一个
**PostgreSQL** 数据库用于透明度日志（迁移会自动运行）。
**1. 拉取镜像：**
```
docker pull ghcr.io/c3equalzz/agate:latest
```
**2. 编写 `agate.toml`**（从 [`agate.example.toml`](agate.example.toml) 开始）：
```
[proxy]
agent_endpoint = "http://your-agent:9000/run" # the real agent's AG-UI endpoint
bind = "0.0.0.0:8080"
[audit]
database_url = "postgres://agate@db:5432/agate" # password via env, below
[policy.tools]
mode = "allowlist"
names = ["search", "fetch"]
[policy]
redact = ["sk-", "AKIA"]
```
**3. 运行它**（将机密信息作为 `AGATE__*` 环境变量覆盖传入）：
```
docker run --rm \
-p 8080:8080 \
-v "$PWD/agate.toml:/etc/agate/agate.toml:ro" \
-e AGATE_CONFIG=/etc/agate/agate.toml \
-e AGATE__AUDIT__DATABASE_URL='postgres://agate:secret@db:5432/agate' \
ghcr.io/c3equalzz/agate:latest
```
**4. 将你的前端指向 `http://localhost:8080`**，而不是指向 agent。
Agate 会在检查后将每个请求转发给 agent —— 并将
判定结果记录到透明度日志中。
## 架构一览
该代理会终止 TLS，在 agent 运行之前验证请求，然后
在流式传输响应的同时咨询策略，并将数据写入远离
热路径的审计日志。
```
flowchart LR
client["Frontend / client(untrusted)"] agent["Agent app
(AG2 / AG-UI)"] subgraph agate["Agate (agate-server)"] direction TB proxy["agate-proxy
inline inspection
(request + SSE response)"] policy["agate-policy
verdict: allow / deny /
transform / terminate"] audit["agate-audit
RFC 6962
transparency log"] proxy -- "event → verdict?" --> policy policy -- "verdict" --> proxy proxy -- "(event, verdict)" --> audit end client <-->|"AG-UI over TLS"| proxy proxy <-->|"forwarded traffic"| agent audit -.->|"append-only"| store[("Postgres
Merkle log")] ``` Agate 是一个 Cargo workspace，其中**每个 crate 都是一个限界上下文**，采用 领域驱动设计和整洁架构构建；依赖关系只向内流动， 没有共享内核。 | Crate | 限界上下文 | 职责 | | --- | --- | --- | | `agate-crypto` | 通用子域（库） | 密码敏捷性：可插拔、自描述的哈希 / 签名 / AEAD 策略 | | `agate-audit` | 审计 | 仅追加的 RFC 6962 透明度日志 | | `agate-proxy` | 代理（数据面） | Agent 流量的内联检查；event → verdict 的交接点 | | `agate-policy` | 策略 | 内容与授权决策：工具允许/拒绝 + 机密脱敏 | | `agate-server` | 组合根 | 连接 proxy ↔ audit ↔ policy；Docker entrypoint | ## 文档 完整的文档 —— 包括概述、入门、配置、架构以及 威胁模型 —— 使用 Material for MkDocs 发布，并且是 **双语的（English + Russian）**。 - **文档站点：**
标签：DLL注入, JSONLines, LLM代理, Rust, 人工智能, 反向代理, 可视化界面, 安全网关, 流量审计, 测试用例, 用户模式Hook绕过, 网络流量审计, 自定义请求头, 请求拦截, 通知系统, 防御绕过, 零信任