AgentGate

AgentGate

为 AI Agent 提供人在回路中的审批系统。
Agent 发起请求。策略作出判断。由人审批。
让人类始终掌控 AI Agent 的操作权限。

---

你的 AI Agent 想要发送邮件、删除文件或部署到生产环境。 应该允许它这么做吗？ AgentGate 让你定义策略，自动批准安全操作、自动拒绝危险操作，并将其他操作交由人工处理——通过控制面板、Slack、Discord 或电子邮件完成。

✨ 亮点

• 🛡️ 策略引擎 — 根据规则自动批准、自动拒绝，或交由人工处理
• 👥 多渠道审批 — 支持 Slack、Discord、电子邮件或 Web 控制面板
• 🔌 TypeScript SDK + MCP — 适用于任何 Agent 框架或 Claude Desktop
• 🪝 支持重试的 Webhook — 通过指数退避机制发送实时通知
• 📝 完整审计记录 — 记录每个请求、决策和操作；每项策略决策都会标注其所缓解的 OWASP LLM Top-10 风险（合规性证据）
• 🐳 支持 Docker — 运行一次 docker-compose up 即可启动完整技术栈
• 🔐 针对生产环境加固 — 提供 SSRF 防护、ReDoS 防御、结构化日志和优雅关闭
• 🔗 一键决策链接 — 直接通过通知邮件和 Webhook 批准或拒绝
• ♿ 无障碍 UI — 支持键盘操作的审批弹窗、焦点锁定和 ARIA 标签
• 💀 骨架屏加载 — 在每个控制面板页面提供流畅的加载状态
• ⚡ 快速轻量 — 基于 Hono 服务，支持 SQLite 或 PostgreSQL

快速开始

# Self-host the full stack (server + dashboard + Postgres):
docker compose up

# …or from source:
pnpm install && pnpm --filter @agentkitai/agentgate-server db:migrate && pnpm --filter @agentkitai/agentgate-server bootstrap && pnpm dev

将 AgentGate 接入 MCP 客户端（Claude Desktop / Cursor / VS Code）——将客户端指向网关：

{ "mcpServers": { "agentgate": { "command": "npx", "args": ["@agentkitai/agentgate-mcp"] } } }

控制面板

一目了然地查看所有待处理请求，并按紧急程度用颜色标记，让你知道应优先处理哪些请求。

审批请求

查看、批准或拒绝请求——按状态筛选，专注于重要事项。

审计日志

搜索每项决策，并按事件类型、操作、操作者和日期范围筛选。

请求详情

深入查看任意请求的参数、上下文、时间线和审计记录，并使用一键批准/拒绝按钮。

API 密钥

管理 API 密钥，包括精细的作用域、速率限制和用量跟踪。可在控制面板中创建、编辑或撤销密钥。

Webhook

配置用于实时通知的 Webhook 端点。添加 URL、选择事件，AgentGate 会自动处理重试。

登录

使用 API 密钥登录——通过 CLI 创建密钥，或向管理员索取。

---

目录

• 快速开始
• 架构
• 软件包
• SDK 用法
• 命令行
• MCP 集成
• 身份验证
• API 端点
• 速率限制
• Webhooks
• 配置
• Docker 部署
• 开发
• 故障排除
• 贡献
• 许可证

---

快速开始

1. 安装依赖

pnpm install

2. 运行数据库迁移

pnpm --filter @agentkitai/agentgate-server db:migrate

3. 初始化（创建管理员 API 密钥）

pnpm --filter @agentkitai/agentgate-server bootstrap

请保存 API 密钥——它只会显示一次！将其设置到环境变量中：

export AGENTGATE_API_KEY="agk_..."

4. 启动开发环境

# Start server (port 3000) and dashboard (port 5173)
pnpm dev

5. 运行演示

在新的终端中（已设置 API 密钥）：

export AGENTGATE_API_KEY="agk_..."
pnpm demo

6. 打开仪表板

访问 **http://localhost:5173**，查看和管理审批请求。

架构

┌─────────────────────────────────────────────────────────────────┐
│                         AI Agents                                │
│  (use @agentkitai/agentgate-sdk or MCP to request approvals)               │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP API (authenticated)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    AgentGate Server                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Policy Engine│  │ Request Store│  │ Audit Logger │          │
│  ├──────────────┤  ├──────────────┤  ├──────────────┤          │
│  │  API Keys    │  │  Webhooks    │  │  MCP Server  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└───────────────────────────┬─────────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│  Web Dashboard │ │   Slack Bot    │ │  Discord Bot   │
│(React+Tailwind)│ │(approve in DM) │ │(approve in ch) │
└────────────────┘ └────────────────┘ └────────────────┘
              │             │             │
              └─────────────┼─────────────┘
                            ▼
                      ┌──────────┐
                      │  Humans  │
                      └──────────┘

软件包

软件包	说明	文档
@agentkitai/agentgate-core	类型、架构和策略引擎	-
@agentkitai/agentgate-server	Hono API 服务	-
@agentkitai/agentgate-sdk	面向 Agent 的 TypeScript SDK	README
@agentkitai/agentgate-cli	命令行界面	-
@agentkitai/agentgate-mcp	面向 Claude Desktop 的 MCP 服务	-
@agentkitai/agentgate-slack	Slack 机器人集成	README
@agentkitai/agentgate-discord	Discord 机器人集成	README
@agentkitai/agentgate-dashboard	React Web 仪表板	-

SDK 用法

import { AgentGateClient } from '@agentkitai/agentgate-sdk';

// Create client with API key
const client = new AgentGateClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.AGENTGATE_API_KEY,
});

// Request approval
const request = await client.request({
  action: 'send_email',
  params: {
    to: '[email protected]',
    subject: 'Order shipped!',
  },
  urgency: 'normal',
});

// Wait for human decision
const decided = await client.waitForDecision(request.id, {
  timeout: 60000, // 1 minute
});

if (decided.status === 'approved') {
  // Execute the action
  await sendEmail(decided.params);
} else {
  console.log('Action denied:', decided.decisionReason);
}

命令行

AgentGate 提供命令行界面，用于管理审批请求。

安装

# From the monorepo
pnpm --filter @agentkitai/agentgate-cli build

# Or install globally (when published)
npm install -g @agentkitai/agentgate-cli

配置

使用服务 URL 和 API 密钥配置命令行工具：

# Set server URL
agentgate config set serverUrl http://localhost:3000

# Set API key
agentgate config set apiKey agk_your_api_key

# View current config
agentgate config show

配置存储在 ~/.agentgate/config.json 中。你也可以使用环境变量：

export AGENTGATE_URL=http://localhost:3000
export AGENTGATE_API_KEY=agk_...

命令

命令	说明
agentgate config show	显示当前配置
agentgate config set <key> <value>	设置配置值
agentgate request <action>	创建新的审批请求
agentgate status <id>	获取请求状态
agentgate list	列出审批请求
agentgate approve <id>	批准待处理的请求
agentgate deny <id>	拒绝待处理的请求

示例

# Create a request
agentgate request send_email \
  --params '{"to": "[email protected]", "subject": "Hello"}' \
  --urgency high

# List pending requests
agentgate list --status pending

# Approve a request
agentgate approve req_abc123 --reason "Looks good"

# Deny a request
agentgate deny req_abc123 --reason "Not authorized"

# Output as JSON
agentgate list --json

MCP 集成

AgentGate 提供 Model Context Protocol（MCP）服务，可与 Claude Desktop 及其他兼容 MCP 的客户端集成。

Claude Desktop 配置

添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "agentgate": {
      "command": "npx",
      "args": ["@agentkitai/agentgate-mcp"],
      "env": {
        "AGENTGATE_URL": "http://localhost:3000",
        "AGENTGATE_API_KEY": "agk_..."
      }
    }
  }
}

可用的 MCP 工具

工具	说明
agentgate_request	提交新的审批请求
agentgate_get	根据 ID 获取审批请求的状态
agentgate_list	列出审批请求，可选择使用筛选条件
agentgate_decide	批准或拒绝待处理的请求
agentgate_list_policies	按优先级顺序列出所有策略
agentgate_create_policy	创建包含规则的新策略
agentgate_update_policy	替换现有策略
agentgate_delete_policy	根据 ID 删除策略
agentgate_list_audit_logs	使用筛选条件和分页列出审计日志条目
agentgate_get_audit_actors	获取审计日志中的唯一操作者值

身份验证

AgentGate 使用 API 密钥进行身份验证。除 /health 外，所有 API 请求都需要有效的 API 密钥。

API 密钥权限范围

权限范围	描述
admin	完全访问所有操作
request:create	创建新的审批请求
request:read	读取审批请求
request:decide	批准或拒绝请求
webhook:manage	创建／更新／删除 Webhook

使用 API 密钥

HTTP 标头：

curl -H "Authorization: Bearer agk_..." http://localhost:3000/api/requests

SDK：

const client = new AgentGateClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.AGENTGATE_API_KEY,
});

创建其他 API 密钥

// Via API (requires admin scope)
POST /api/api-keys
{
  "name": "My Agent",
  "scopes": ["request:create", "request:read"]
}

API 端点

方法	端点	描述	所需权限范围
POST	/api/requests	创建审批请求	request:create
GET	/api/requests	列出请求（带筛选条件）	request:read
GET	/api/requests/:id	按 ID 获取请求	request:read
POST	/api/requests/:id/decide	提交批准／拒绝决定	request:decide
GET	/api/requests/:id/audit	获取审计记录	request:read
GET	/api/policies	列出策略	admin
POST	/api/policies	创建策略	admin
PUT	/api/policies/:id	更新策略	admin
DELETE	/api/policies/:id	删除策略	admin
POST	/api/api-keys	创建 API 密钥	admin
GET	/api/api-keys	列出 API 密钥	admin
PATCH	/api/api-keys/:id	更新 API 密钥	admin
DELETE	/api/api-keys/:id	撤销 API 密钥	admin
GET	/api/webhooks	列出 Webhook	webhook:manage
POST	/api/webhooks	创建 Webhook	webhook:manage
DELETE	/api/webhooks/:id	删除 Webhook	webhook:manage
GET	/health	健康检查	（无）

速率限制

AgentGate 支持按 API 密钥设置速率限制，以防止滥用并确保公平使用。

工作原理

• 速率限制采用滑动窗口算法（每分钟请求数）
• 每个 API 密钥单独配置限制
• 超出限制时，请求将返回 429 Too Many Requests
• 所有经过身份验证的响应中都会包含速率限制标头

速率限制标头

标头	描述
X-RateLimit-Limit	每分钟的最大请求数
X-RateLimit-Remaining	当前窗口内剩余的请求数
X-RateLimit-Reset	窗口重置前的秒数

配置速率限制

创建或更新 API 密钥时设置速率限制：

// Via API (requires admin scope)
POST /api/api-keys
{
  "name": "My Agent",
  "scopes": ["request:create", "request:read"],
  "rateLimit": 60  // 60 requests per minute
}

// null = unlimited
{
  "name": "Internal Service",
  "scopes": ["admin"],
  "rateLimit": null
}

控制面板

也可以在 Web 控制面板的 Settings → API Keys 下管理速率限制。

Webhook

AgentGate 可在请求事件发生时通知外部系统。

设置 Webhook

// Create a webhook via API
POST /api/webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["request.created", "request.decided"],
  "secret": "optional-signing-secret"
}

Webhook 事件

事件	描述
request.created	新的审批请求已创建
request.decided	请求已获批准或被拒绝
request.expired	请求过期且未作出决定

Webhook 负载

{
  "event": "request.decided",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "abc123",
    "action": "send_email",
    "status": "approved",
    "decidedBy": "[email protected]"
  }
}

Webhook 签名

如果提供了 secret，请求将使用 HMAC-SHA256 签名：

X-AgentGate-Signature: sha256=...

通过计算 HMAC-SHA256(secret, body) 并进行比对来验证。

Webhook 重试

Webhook 投递失败时会自动使用指数退避进行重试。服务器会扫描待投递项，并以递增的延迟重试（2^attempts * 1000ms），直到投递成功或达到最大重试次数。

配置

环境变量

变量	默认值	描述
PORT	3000	服务端口
DATABASE_URL	./data/agentgate.db	SQLite 数据库路径
AGENTGATE_API_KEY	-	SDK／CLI 的 API 密钥
SLACK_BOT_TOKEN	-	Slack 机器人令牌（用于 Slack 集成）
SLACK_SIGNING_SECRET	-	Slack 签名密钥
DISCORD_BOT_TOKEN	-	Discord 机器人令牌（用于 Discord 集成）
DISCORD_DEFAULT_CHANNEL	-	用于通知的默认 Discord 频道

基于文件的密钥（_FILE 后缀）

对于 Docker 密钥或 Kubernetes 密钥挂载，AgentGate 支持 _FILE 后缀约定。无需直接在环境变量中设置密钥，只需指向包含该值的文件：

变量	从文件读取密钥
ADMIN_API_KEY_FILE	设置 ADMIN_API_KEY
JWT_SECRET_FILE	设置 JWT_SECRET
DATABASE_URL_FILE	设置 DATABASE_URL
REDIS_URL_FILE	设置 REDIS_URL
SLACK_BOT_TOKEN_FILE	设置 SLACK_BOT_TOKEN
SLACK_SIGNING_SECRET_FILE	设置 SLACK_SIGNING_SECRET
DISCORD_BOT_TOKEN_FILE	设置 DISCORD_BOT_TOKEN
SMTP_PASS_FILE	设置 SMTP_PASS

行为：

• 文件内容会去除首尾空白字符
• 如果同时设置了环境变量和 _FILE 变体，则优先使用显式环境变量
• 文件不存在或无法读取时会发出警告，但不会导致服务崩溃

Docker Compose 配置示例：

services:
  agentgate:
    environment:
      ADMIN_API_KEY_FILE: /run/secrets/admin_api_key
      JWT_SECRET_FILE: /run/secrets/jwt_secret
    secrets:
      - admin_api_key
      - jwt_secret

secrets:
  admin_api_key:
    file: ./secrets/admin_api_key.txt
  jwt_secret:
    file: ./secrets/jwt_secret.txt

策略配置

策略存储在数据库中，可通过 API 管理：

// Example: Auto-approve low-risk emails
{
  name: "auto-approve-emails",
  priority: 10,
  enabled: true,
  rules: [
    {
      match: { action: "send_email" },
      decision: "auto_approve"
    }
  ]
}

Docker 部署

AgentGate 提供 Docker 镜像，便于轻松进行可自托管部署。

快速开始

1. 复制示例环境文件：

cp .env.example .env

2. 生成安全凭据：

# Generate admin API key (required)
echo "ADMIN_API_KEY=$(openssl rand -hex 32)" >> .env

# Generate JWT secret (recommended for production)
echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env

3. 启动所有服务：

docker-compose up -d

4. 访问服务：

• 控制面板： http://localhost:3003
• API 服务： http://localhost:3002
• 运行状况检查： http://localhost:3002/health

主机端口可通过 SERVER_PORT（默认值为 3002）和 DASHBOARD_PORT（默认值为 3003）配置；两者分别映射到容器的内部端口 3000/80。

服务

服务	说明	主机端口
server	AgentGate API 服务	3002
dashboard	Web 控制面板（nginx）	3003
postgres	PostgreSQL 数据库	仅限内部网络*
redis	Redis（速率限制、队列）	仅限内部网络*

* PostgreSQL 和 Redis 位于内部 Docker 网络（agentgate-internal）中，默认情况下不会暴露给主机。开发期间会自动加载 docker-compose.override.yml，并在端口 5432/6379 上暴露它们。生产环境请运行 docker-compose -f docker-compose.yml up -d，以跳过 override 文件。

使用 Slack 或 Discord Bot

若要启用 Bot 服务，请使用 bots 配置：

# Set required bot credentials in .env first
docker-compose --profile bots up -d

配置

所有配置均通过环境变量完成。所有可选项请参阅 .env.example。

必需变量：

• ADMIN_API_KEY — 管理员 API 密钥（最少 16 个字符）

生产环境建议设置：

• JWT_SECRET — JWT 签名密钥（最少 32 个字符）
• CORS_ALLOWED_ORIGINS — 限制为你的域名
• POSTGRES_PASSWORD — 使用强密码

构建镜像

在本地构建所有镜像：

docker-compose build

构建指定服务：

docker-compose build server
docker-compose build dashboard

数据库迁移

服务启动时会自动运行迁移。若需手动控制：

# Run migrations inside the container
docker-compose exec server node -e "
  import('./dist/db/migrate.js').then(m => m.runMigrations())
"

查看日志

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f server

# Last 100 lines
docker-compose logs --tail=100 server

停止服务

# Stop all
docker-compose down

# Stop and remove volumes (WARNING: deletes data)
docker-compose down -v

生产环境注意事项

1. 使用反向代理（nginx、Caddy、Traefik）终止 TLS
2. 为 PostgreSQL 设置强密码
3. 将 CORS 来源限制为你的域名
4. 在生产环境中使用 Docker 密钥存储敏感值
5. 为 PostgreSQL 数据卷设置备份
6. 监控运行状况端点，以检查服务是否正常运行

开发

# Install dependencies
pnpm install

# Run migrations
pnpm --filter @agentkitai/agentgate-server db:migrate

# Bootstrap (create admin key)
pnpm --filter @agentkitai/agentgate-server bootstrap

# Start development (server + dashboard)
pnpm dev

测试

AgentGate 使用 Vitest 对所有软件包进行测试。

# Run all tests
pnpm test

# Run tests with coverage report
pnpm test:coverage

# Run tests in watch mode (single package)
pnpm --filter @agentkitai/agentgate-server test:watch

# Run a specific test file
pnpm --filter @agentkitai/agentgate-server test -- src/__tests__/integration.test.ts

覆盖率报告按软件包生成，包含行、分支和函数覆盖率。

代码质量

# Build all packages
pnpm build

# Type checking
pnpm typecheck

# Lint (ESLint)
pnpm lint

# Fix lint issues
pnpm lint:fix

# Format code (Prettier)
pnpm format

# Check formatting
pnpm format:check

项目结构

agentgate/
├── packages/
│   ├── core/           # Shared types, schemas, policy engine
│   ├── server/         # Hono API server
│   ├── sdk/            # TypeScript SDK
│   ├── cli/            # Command-line interface
│   ├── mcp/            # MCP server for Claude Desktop
│   ├── slack/          # Slack bot
│   ├── discord/        # Discord bot
│   └── dashboard/      # React dashboard
├── apps/
│   └── demo/           # Demo application
├── docker-compose.yml  # Docker deployment
└── package.json        # Monorepo root

贡献

欢迎贡献！开始之前：

1. Fork 此仓库
2. 克隆仓库并安装依赖（pnpm install）
3. 按照上方的开发部分设置本地环境
4. 创建功能分支并进行修改
5. 运行 pnpm build && pnpm test，验证一切正常
6. 提交 pull request

提交前，请确保所有测试均通过，且代码已格式化（pnpm format:check && pnpm lint）。

🧰 AgentKit 生态系统

项目	描述
AgentLens	AI Agent 的可观测性和审计跟踪
Lore	跨 Agent 记忆和经验分享
AgentGate	人工审核批准网关	⬅️ 你在这里
FormBridge	Agent 与人工混合模式表单
AgentEval	测试和评估框架
agentkit-cli	统一的 CLI 编排工具

许可证

MIT