Agentgate

AgentGate

AI エージェント向けの、人間が介在する承認システムです。
エージェントがリクエストし、ポリシーが判断し、人間が承認します。
AI エージェントが実行できる操作を、人間の管理下に保ちます。

---

AI エージェントがメールを送信したり、ファイルを削除したり、本番環境にデプロイしたりしようとしています。 実行させてよいでしょうか？ AgentGate では、安全な操作を自動承認し、危険な操作を自動拒否し、それ以外はダッシュボード、Slack、Discord、またはメール経由で人間に回すポリシーを定義できます。

✨ 主な特長

• 🛡️ ポリシーエンジン — ルールに基づいて自動承認、自動拒否、または人間に回すことができます
• 👥 複数チャネルでの承認 — Slack、Discord、メール、またはウェブダッシュボードに対応
• 🔌 TypeScript SDK + MCP — あらゆるエージェントフレームワークや 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 の使い方
• CLI
• MCP 統合
• 認証
• API エンドポイント
• レート制限
• ウェブフック
• 設定
• 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	エージェント向け 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 ウェブダッシュボード	-

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);
}

CLI

AgentGate には、承認リクエストを管理するためのコマンドラインインターフェースが含まれています。

インストール

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

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

設定

サーバー URL と API キーを使って CLI を設定します。

# 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 には、Claude Desktop やその他の MCP 対応クライアントと統合するための Model Context Protocol（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 キーを使用します。すべての API リクエスト（/health を除く）には、有効な 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キーごとのレート制限に対応しています。

仕組み

• レート制限にはスライディングウィンドウアルゴリズム（1分あたりのリクエスト数）を使用します
• 制限はAPIキーごとに設定されます
• 制限を超えると、リクエストは429 Too Many Requestsを返します
• 認証済みのすべてのレスポンスにレート制限ヘッダーが含まれます

レート制限ヘッダー

ヘッダー	説明
X-RateLimit-Limit	1分あたりの最大リクエスト数
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
}

ダッシュボード

レート制限は、ウェブダッシュボードの設定 → APIキーからも管理できます。

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 を実行してください。

Slack または Discord ボットを使用する場合

ボットサービスを含めるには、bots プロファイルを使用します。

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

設定

設定はすべて環境変数で行います。すべてのオプションについては .env.example を参照してください。

必須変数:

• ADMIN_API_KEY — Admin 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. TLS 終端にはリバースプロキシ（nginx、Caddy、Traefik）を使用します
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. リポジトリをフォークします
2. クローンして依存関係をインストールします（pnpm install）
3. 上記の開発セクションに従って、ローカル環境をセットアップします
4. 機能ブランチを作成し、変更を加えます
5. pnpm build && pnpm test を実行して、すべてが正しく動作することを確認します
6. プルリクエストを作成します

提出前に、すべてのテストが合格し、コードがフォーマットされている（pnpm format:check && pnpm lint）ことを確認してください。

🧰 AgentKit エコシステム

プロジェクト	説明
AgentLens	AI エージェントの可観測性と監査証跡
Lore	エージェント間のメモリと教訓の共有
AgentGate	人間が介在する承認ゲートウェイ	⬅️ 現在のプロジェクトです
FormBridge	エージェントと人間が混在する形式のフォーム
AgentEval	テストおよび評価フレームワーク
agentkit-cli	統合 CLI オーケストレーター

ライセンス

MIT