Quick Start

What is AgentGate?

AI Agent → AgentGate → Identity, Delegation, Data, Policy, Risk, Operational Rules → ALLOW / REQUIRE_APPROVAL / BLOCK → Pre-execution Confirmation → MCP / GitHub / Model / Agent

Control AI agent interactions—including GitHub, MCP, models, and inter-agent communication—before execution. Pass only the AgentGate key to the agent; connection credentials are managed on the server side. Restrict direct connections at the organizational level and route all relevant operations through this path.

1. Getting Started with GitHub

1. Create an account. If starting with MCP or models, proceed to their respective connection guides.
2. Install the GitHub app with the "Only select repositories" option.
3. Create a sandbox agent by specifying its name, owner, and purpose, and save the displayed API key—this is the only time it will be shown.
4. Review permissions, delegation, and data rules for humans and agents under Organization/Permissions, and run safety simulations using policies with limited scope.

Verify policies and approval workflows using a test repository before connecting to a production repository.

GitHub Appの権限を接続前に確認する

最初はテスト用リポジトリだけを選んで接続してください。標準のGitHub連携で使う権限と用途は次のとおりです。実際に付与する権限と対象リポジトリは、GitHubのインストール確認画面で確認してください。

• Metadata（読み取り）：リポジトリ情報の取得。
• Issues（読み書き）：Issueの作成と、復旧操作でのクローズ。
• Pull requests（読み書き）：Pull Requestの作成。
• Contents（読み書き）：Pull Requestのマージと、復旧操作でのブランチ削除。

標準構成ではAdministration権限を付与しません。リポジトリ削除は既定のBLOCKルールで拒否します。GitHub側の権限だけでAgentの操作が許可されることはなく、AgentGate側でも対象・Tool・権限・委任・Policyの設定が必要です。

必要な権限はGitHub公式のリポジトリ取得、Issue作成、Pull Request操作、ブランチ参照の削除でも確認できます。利用を止める場合は接続解除・権限失効・削除へ進んでください。

2. Agents and Policies

Create an agent on the Agent screen and save the API key to a secrets management service. On the Policy screen, configure actions, resource patterns, decisions, and priorities. Requests are denied by default if no policy matches.

Stop the agent in the event of a leak or anomaly. While stopped, all actions are denied; you can resume operation or rotate keys via the Agent screen.

対象を限定してPolicyを設定する

1. ポリシーでAgent・接続先・Tool・リソースを選び、判定と理由を入力します。MCP ServerのTool詳細からも追加できます。
2. 一致する有効なBLOCKルールがあれば、ALLOWや承認ルールの優先度が高くても拒否します。たとえばALLOWの優先度が1000、同じ操作に一致するBLOCKが10でも結果はBLOCKです。BLOCKがない場合は、一致する有効なルールのうち優先度が高いものを使います。同じ優先度ではAgent指定が全Agent指定より先になり、それも同じならID順です。
3. MCPのリソースは同期したToolのResource引数から取得します。docs/*はdocs/publicに一致しますが、docs/a/bには一致しません。大文字・小文字も区別します。Resource引数未指定では対象が*になります。
4. ALLOWは権限・委任・データ規則の不足を補いません。設定のシミュレーションで実際のAgentと要求を確認し、変更後は再検証してください。

無効にしたPolicyは判定とAgent一覧の適用件数から除外されます。個別の要求に一致したルールとバージョンは監査履歴で確認できます。

Agentの用途を登録・変更する

エージェントの登録では用途が必須です。何を、どの対象に対して行うかを具体的に記載してください。空白だけでは登録できません。

既存Agentの用途は組織・権限のIdentity設定で変更します。保存した利用目的はAgent一覧にも反映されます。古い記録で用途が未設定の場合、設定画面は利用できますが、新規操作や承認後の実行は拒否されます。目的を設定してから新しいリクエストを送ってください。

Shadow判定を比較する

運用・事故対応のShadow比較レポートで、外部実行しなかった判定を選び、人の判断または保存済みのProduction判定と比較できます。Productionとの比較は、同じ接続先・Tool・対象・保存済み入力の記録が必要です。記録時のProduction / Autonomousが対象です。

Owner・Admin・Approverが比較を保存すると、一致・不一致と両方の記録へのリンクが表示されます。同じ判定・比較種別は最後の比較を集計し、取得範囲は最新1,000件以内の監査履歴です。比較や詳細表示による外部再実行はありません。

3. Action API

curl -X POST https://app.agentgatehq.com/api/v1/actions \
  -H "Authorization: Bearer $AGENTGATE_API_KEY" \
  -H "Idempotency-Key: $AGENTGATE_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"github.repo.read","resource":{"owner":"YOUR_ORG","repo":"sandbox","installationId":"YOUR_INSTALLATION_ID"},"payload":{}}'

Set `AGENTGATE_REQUEST_KEY` to an identifier (8–160 characters) saved for this specific operation. When resending the same operation, ensure the identifier and request body remain unchanged. In TypeScript, pass the same headers and JSON body to `fetch`. Store API keys exclusively in a server-side secret management service.

// Node.js 24 / TypeScript: run on your server, never in browser code.
async function readSandbox(apiKey: string, requestKey: string) {
  const response = await fetch("https://app.agentgatehq.com/api/v1/actions", {
    method: "POST",
    redirect: "error",
    signal: AbortSignal.timeout(50_000),
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Idempotency-Key": requestKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "github.repo.read",
      resource: { owner: "YOUR_ORG", repo: "sandbox", installationId: "YOUR_INSTALLATION_ID" },
      payload: {},
    }),
  });
  const result: unknown = await response.json();
  return { httpStatus: response.status, result };
}

// Supply your server-side secret and the saved key for this exact request.
// const result = await readSandbox(apiKey, savedRequestKey);
// Check result.result.decision and execution.status before treating it as executed.
// On timeout/network failure, inspect audit history; do not retry with a new key.

4. Determination

Requests are rejected by default if no matching valid policy exists.

MCPの接続

1. ServersでStreamable HTTP対応の公開HTTPSエンドポイントを登録し、Toolを同期します。
2. ToolのResource引数を指定し、組織設定でHumanからAgentへの委任と権限の上限を設定します。
3. Tool・Resourceのポリシーと、入力・出力のデータ規則を登録します。未設定は拒否されます。
4. MCP Clientを/api/mcpへ接続し、AgentキーをBearerヘッダーに設定します。Tool呼び出しには8〜160文字のIdempotency-Keyを付けます。

Agentには接続先の資格情報を渡さず、接続先側でもAgentGate以外の直接接続を拒否してください。

モデルの接続と予算

運用・事故対応のModel Registryで設定します。追加・変更はTeam以上が対象です。提供元の認証情報は運営者がサーバー側に設定し、AgentにはAgentGateのキーだけを渡します。

1. 識別名をsummary-model、対応する用途をsummaryとしてモデルを登録します。標準のクラウド接続アダプターはai-gatewayです。提供元（例: openai）と、その提供元で利用可能なモデルID・バージョン・単価を指定します。
2. 許可する組織とAgentを必ず選び、処理地域・機密性・トークン上限を設定します。組織やAgentの選択が空のモデルは使えません。内容を確認して利用状態をAPPROVEDにします。
3. 組織・権限で接続先「AgentGate 内部モデル・Agent間通信」、Tool名model.generate、対象リソースsummary-modelを指定します。HumanとAgentそれぞれのREAD権限、HumanからAgentへの有効な委任、Toolに必要なREAD権限を設定します。
4. 同じ接続先・Tool・リソースについてデータ分類とINPUT / OUTPUTのデータルールを登録し、外部送信を許可する公開データだけをREADにします。ポリシー画面では対象Agent・Tool・リソースを限定したALLOWまたはREQUIRE_APPROVALを設定します。未設定やDENYはモデル登録では解除されません。
5. BudgetでAgent単位または組織全体の日次・月次予算（USD）と超過時のBLOCK・承認・代替モデルを設定し、ルールを公開します。

{
  "provider": "mcp",
  "server": "00000000-0000-4000-8000-000000000005",
  "tool": "model.generate",
  "resource": "summary-model",
  "arguments": {
    "prompt": "公開用の短い挨拶文を作成してください。",
    "task": "summary",
    "sensitivity": "PUBLIC",
    "residency": "GLOBAL",
    "maxOutput": 512,
    "maxCost": 0.02
  }
}

resource: "auto"では条件を満たす承認済みモデルから見積費用の低いものを選びます。autoを使う権限とポリシーも必要です。特定の識別名を指定した場合はそのモデルを使い、失敗時は登録した代替モデルの優先順に試します。各代替先でも権限・データ・予算・Agentの運用段階を再確認します。途中で廃止・Shadow・Limitedの制限が適用された場合、以後の呼び出しを停止します。先行モデルの結果が不明なまま切り替えを停止した場合は「結果不明」を維持し、提供元の記録を確認するよう案内します。

成功はexecution.statusとexecution.result.usage、失敗はアクティビティの詳細で確認します。利用拒否は提供元の権限・接続設定を、結果不明は提供元側の記録を確認してください。同じ要求を自動でやり直さず、結果不明分の見積費用を予算に残します。

Agent間通信を確認する

送信側Agentは内部Tool agent.requestで受信AgentのIDとmessageを指定します。同じ組織のAgent間で通信許可を登録し、送信側と受信側の両方に権限・Policy・Data Policyが必要です。受信専用のagent.receiveへ直接要求することはできません。

受信側が拒否・承認待ちの場合、その処理は進みません。送信側の操作結果に受信側の判定が含まれます。事故調査のReplayでは、Agent間通信の追跡から送信側・受信側それぞれの保存済み判定へ移動できます。履歴を開いても通信は再実行しません。設定した委任の深さ・日次件数、循環、組織境界を検査します。

設定案を保存せずに確認する

運用・事故対応のRule Simulationで対象Agentと要求を指定し、保存済み設定または同じ画面で編集中の設定案による最終判定を確認できます。事故調査でReplayを開くと、保存された要求をコピーできます。マスク済みデータは元に戻りません。

設定案は公開されず、Toolの実行や承認要求の作成も行いません。現在の権限・データ規則・緊急停止は設定案でも適用されます。Intent分析が有効な場合は分析モデルの利用料が発生する場合があります。判定は実施時点のもので、入力や設定を変更したら再確認してください。

データ制御

PUBLIC・INTERNAL・CONFIDENTIAL・RESTRICTEDをフィールド単位で分類し、入力と出力にREAD・MASK・DENYを設定します。MASKした値は元に戻せません。外部送信にはexternalAllowedと接続先の許可が必要です。

PromptとTool outputは信用できない入力です。指示文が含まれていても権限やポリシーは変更されません。Secret・Cookie・Tokenをリクエスト本文に含めないでください。

判断と実行を追跡する

API応答のcontrolはcontractVersion・requestId・actionId・decisionId・executionId・reasonCodes・versionsを返します。同じIdempotency-Keyと同じ本文を再送すると、同じ操作を追跡できます。異なる本文への使い回しは409です。

BLOCKは後段のリスク評価・承認・課金によって解除されません。ALLOWは実行の許可を示します。実行結果はexecution.statusで確認してください。

緊急停止・Replay・復旧

EnterpriseのSTOP ALL AGENTSで組織の新規実行を停止します。停止前の承認待ちは、再開後も新しい要求が必要です。個別AgentはSuspend、MCP ServerとModelは無効化できます。

ActionのReplayで当時と現在のPolicy・Authority・Riskを比較します。Replay自体は外部操作を実行しません。補償可能なToolは現在のバージョンを検証し、高影響の復旧には人の承認を求めます。UNKNOWNは自動再実行せず、接続先で結果を確認してください。

対応プランでは運用画面の「証跡を書き出す」から、選択した組織の保存期限内の監査・Action・承認・Black Box・Enterprise・権限・Risk設定履歴をJSONLで取得できます。画面の表示件数による省略はありません。1行ごとにJSONがあり、最終行に取得完了と種類別の件数を記録します。途中で失敗した場合はファイルを保存せず、再試行を案内します。保存先はブラウザのダウンロードで確認してください。期限切れの記録や伏せ字化前の秘密値は復元できません。

Risk・BLOCKの急増を確認する

AI SOCの急増監視で、直近1時間とその前の1時間のBLOCK件数・High/Critical Risk件数を比較できます。各対象が20件以上、かつ3倍を超えると要確認です。少量データは正常の証明にはなりません。全保持データを対象とし、比較時刻と件数も表示します。

「イベントで要因を確認」からAgent・Tool・拒否理由を調べ、必要に応じて権限やPolicyを見直します。検知だけで設定変更やAgent停止は行いません。画面の再読み込み時と定期ワーカーで評価します。外部通知には運用側でログ通知先を設定する必要があります。

役割と退職者の処理

Adminは管理、Securityは停止と安全ポリシー、Approverは承認、MANAGERはPolicy Manager、VIEWERは閲覧・監査を担当します。SSOはSupabase AuthのProvider IDを組織へ登録して接続します。初回は組織専用SSOリンクからログインして利用条件に同意し、表示されたユーザーIDを組織Ownerに共有してください。Ownerがメンバーの追加方法「ユーザーID」で所属とRoleを設定すると利用できます。同じメールの通常ログインとは別のアカウントで、既存権限は自動で移しません。

退職時は組織メンバーを無効化し、所有Agentを停止してキーと委任を失効します。Enterpriseのセッション失効は既存アクセスTokenにも反映されます。他組織にも所属する利用者の全セッション失効は、本人または全社の認証管理者が行います。

プラン・保存期間

Freeから開始し、「運用・事故対応 → 料金・利用状況」からStripe Checkoutで変更、Customer Portalで契約を管理できます。支払い失敗・解約で利用枠が変更されても、安全ポリシーと緊急停止は残ります。履歴は書き込み時の保存期限を持ち、プラン変更で既存履歴の期限は短縮されません。

証跡はEnterpriseから書き出せます。Complianceラベルは規則との対応を示し、外部認証の取得を意味しません。

5. Approval Flow

Review the `approvalId` from the response on the approval screen; check the target Tool, resources, input, and reason before approving or rejecting. The original input is locked; execution will not proceed if the request expires, is rejected, or undergoes duplicate approval. Permissions, data rules, and suspension status are re-verified even after approval. Check the results via the approval card and audit history.

6. Activity / Audit Logs

Activity logs record events—such as action receipt, policy determination, approval, and execution success or failure—as append-only entries. You can filter by agent, determination, action, or date, and trace the entire process using the request ID.

Compliance・設定履歴では、ルールへの該当理由・記録時のバージョン・対応ラベルを確認し、該当操作のReplayへ進めます。運用ルールの公開履歴には、公開時点の設定を保存しています。表示する履歴を切り替えると、該当記録と設定公開を絞り込めます。

Complianceは組織が定めた規則を登録する機能です。Team以上で運用ルールのComplianceを開き、対象の接続先・Tool・リソース・機密性と、停止または承認必須を設定します。既存ルールを変更するときはバージョンを増やして公開してください。ラベルの登録は外部認証の取得や法令適合の保証ではありません。

7. Errors and Retries

For 401 errors, check authentication credentials; for 409, check for request conflicts or approval/configuration status; for 429, check for rate limits or plan caps. If a 429 response includes a `Retry-After` header, wait for the specified duration. Since 5xx errors or communication interruptions may leave the execution status uncertain, verify the `requestId` and check audit logs or connection destination records. Use the same request body and `Idempotency-Key` to check the status of a request; do not automatically retry an operation with an unknown result using a new key.

8. Security

• Do not send API keys or GitHub tokens to logs, feedback channels, or browsers.
• Limit GitHub App permissions to the minimum required and restrict access to selected repositories.
• If a leak occurs, stop the agent and rotate (update) the keys.
• Installation tokens cannot be issued after the GitHub integration is disconnected.

接続解除・権限失効・削除

1. 対象Agentを停止し、必要な監査証跡を保存期限内に書き出します。キー更新で旧キーを失効し、HumanからAgentへの委任と不要な所属を無効にします。
2. MCP Server・Modelを無効にし、接続先でもAgentGate用の資格情報とアクセス許可を失効します。
3. Remove the AgentGate association on the settings screen, and also configure or uninstall AgentGate via the "Installed GitHub Apps" screen on GitHub. Revoking repository access will cause operations on that repository to fail for security reasons.
4. Agent本体の削除には、管理者の認証済みセッションで管理API DELETE /api/v1/agents/:idを利用します。履歴は保存期限・進行中の処理に応じて残るため、削除を外部操作の取消しや監査の即時消去と解釈しないでください。

契約の解約は料金・利用状況から行います。個人情報の削除請求と保存期間はプライバシーポリシーを確認してください。画面での接続解除だけでは提供元アカウントや既存の外部データは削除されません。

Sample Agent / Example MCP Server

Node.js 24で動く実行用サンプルを、このページから取得できます。Agentは標準のfetchでアクションAPIへ接続し、MCP Serverは公開サンプル文書のdocument.readだけを提供します。

1. 空のフォルダーを作り、次の4ファイルを同じフォルダーに保存します。
   • Agentをダウンロード（agent.mjs）
   • MCP Serverをダウンロード（mcp-server.mjs）
   • 依存関係をダウンロード（package.json）
   • 環境設定のひな形をダウンロード（agent.env.example）
2. ターミナルでそのフォルダーを開き、下のコマンドで依存関係をインストールしてServerを起動します。Node.js 24とnpmが必要です。
3. agent.env.exampleを.env.agent.localという名前で保存し、AgentGateのURL・Agentキー・登録済みMCP Server ID・要求識別子を設定します。キーを設定したファイルは公開・コミットしないでください。

npm install
npm run server
# 別のターミナルで同じフォルダーを開く
npm run agent

ローカルServerは127.0.0.1:3110/mcpで待ち受けます。公開AgentGateからlocalhostには接続できません。実接続には、サンプルを管理下のHTTPS環境へ配置し、Gateway専用認証・直接接続制限を追加してから登録・同期します。Resource引数はpath、対象はdocs/publicです。Human/Agentの権限・委任・入力/出力のデータ規則とPolicyを先に設定してください。

MCP SDKを使うClientはStreamable HTTPで/api/mcpへ接続し、Bearerと呼び出しごとのIdempotency-Keyを送ります。tools/listで返されたTool名をそのままtools/callに指定してください。接続先の元のTool名とGateway上の名前は異なる場合があります。

10. Troubleshooting

• GitHub not connected: Reconnect the app via the setup process.
• MCP connection failure: Check the Endpoint, Secret reference, and Timeout settings under "Servers," then retry the connection test and tool synchronization. If only the list retrieval fails, simply reload the list.
• Repository not found / Insufficient permissions: Check the selected repositories and app permissions on the GitHub side.
• BLOCK: Check the reason code to verify the agent's purpose, permissions, delegation, data rules, policies, and suspended status. Do not bypass this using unconditional ALLOW or by directly distributing credentials.
• Usage Limits / Timeouts: Check error codes, the "Retry-After" header, and audit logs. For UNKNOWN errors, check the execution result at the destination; do not automatically retry.
• Agent Suspended: Check the status on the agent screen and resume operation after resolving the cause. When updating keys, the old key becomes invalid; ensure agent-side settings are updated accordingly.