メインコンテンツまでスキップ

ツール方針

ツール方針は、エージェントが実行してよいツール呼び出しを決める、組織ごとの規則です。1 つの規則は、サブジェクト(エージェントキーの id、または * = 組織のすべてのエージェント)を ツールパターン と アクション(allow / deny)に結びます。

方針のない組織はすべてを許可します — 配線は無料で、動作が変わるのはオペレーターが規則を定義したときだけです。

方針が適用される場所​

対象効果
MCP 呼び出し(/api/mcp/invoke)生のツール名は、プロキシが外へ出る 前 に検査されます。deny なら → 403 policy_denied
A2A 送信(/api/a2a/send)ツール名 a2a:<agent> を、同じ方法で検査します
組み込みエグゼキュータ(yabanin:web_fetch、…)実行前に yabanin:<tool> として検査します
モデル応答(/v1/chat/completions、JSON と SSE)モデルが 宣言する tool_calls は、クライアントが見る前に検査されます。拒否された呼び出しは取り除かれ、すべての呼び出しが拒否された choice は tool_calls ではなく stop で終わります — クライアント側エグゼキュータはそれらを受け取りません

拒否された呼び出しは、組織とツールごとに gateway_tool_policy_denied_total メトリクスで数えられます — 方針決定の追跡面です(レスポンス自体には、拒否された呼び出しはもう含まれません)。

評価順序​

最も具体的な一致が勝ちます。

  1. 正確なツール名 > より長いワイルドカード接頭辞 > より短いワイルドカード > *
  2. エージェント固有のサブジェクトは * に勝ちます
  3. より小さい priority 番号(0–1000、デフォルト 100)
  4. 安定した名前順

ワイルドカードは末尾の星のみです(web_*、mcp:github:*)。内部の星は拒否されます。したがって deny web_* + allow web_search は合成でき、エージェント単位の例外は組織全体の deny に勝ちます。

サーバー側実行(組み込みツール)​

仮想の yabanin MCP サーバーは、ツールを ゲートウェイプロセス内 で実行します。そのため外向き通信は、開発者のマシンからではなく、ゲートウェイのネットワーク位置と管轄から起きます。

POST /api/mcp/invoke {"server":"yabanin","tool":"web_fetch","params":{"url":"https://example.com/doc"}}

組み込みカタログ​

ツール実効方針名動作
web_fetchyabanin:web_fetchURL への HTTP GET。テキスト系のコンテンツのみ、上限 2 MiB
http_requestyabanin:http_<method>JSON ボディ付きの任意の HTTP メソッド(get/post/put/patch/delete)。方針名はメソッドと合成されるため、network-readonly は yabanin:http_post を自然に拒否します
http_headyabanin:http_headHEAD リクエスト。ボディなしのレスポンスヘッダー(資格情報ヘッダーは除去)
dns_lookupyabanin:dns_lookupゲートウェイのリゾルバから、ホスト名を A/AAAA レコードへ解決します
time_nowyabanin:time_now現在のゲートウェイ時刻(RFC3339 UTC + epoch)。外向き通信はありません

発見(エージェントプリンシパルのみ。組織方針が拒否するツールは、カタログから隠されます):

GET /api/mcp/yabanin/tools

すべての外向きダイヤルのツールは、導入の SSRF 許可リストと予約 IP 検査を共有し(MCP レジストリと同一の外向き面)、パラメータに対して外向き前のガードフックを実行します。すべての実行は、エージェント/タスクの帰属とともに、標準の監査証跡へ mcp:yabanin:<tool> として記録されます。

スタータープリセット​

管理コンソール(ツール方針画面)または API から適用します。プリセットは 編集可能な行 を作ります — 隠れた動作ではなくテンプレートであり、2 回適用すると既存の行はスキップされます。

  • network-off — すべてのエージェントについて、外向きネットワークに見えるツールを拒否します(web fetch/browse/http ファミリー。サーバー側エグゼキュータを含む)
  • network-readonly — 読み取り形のネットワークツールを許可し、書き込み形の名前(http_post、post_*、send_*、…)を拒否します
  • internal-only — yabanin:web_fetch 以外をすべて拒否します(すべての外向き通信を、制御された点を通します)

プリセットのパターンは、一般的な ツール名に対する誠実なベストエフォートです。網羅的ではありません — お使いのスタックに合わせて見直し、拡張してください。

管理 API(root のみ、組織スコープ)​

メソッドパス
POST/api/organizations/{id}/tool-policies
GET/api/organizations/{id}/tool-policies
GET/api/organizations/{id}/tool-policies/{name}
PATCH/api/organizations/{id}/tool-policies/{name}
DELETE/api/organizations/{id}/tool-policies/{name}
GET/api/organizations/{id}/tool-policies/presets
POST/api/organizations/{id}/tool-policies/presets/{preset}

エンジンの決定は、組織ごとに 5 秒間キャッシュされます。すべての CRUD 変更は、直ちにキャッシュを破棄します。

延期(v1 の文書化された非目標)​

  • 承認ワークフロー(deny / allow / 管理者への確認 と保留キュー)— スキーマの action 列はそれを見越していますが、エンジンと UI が出荷するのは allow/deny のみです。
  • 名前パターンを超えるツールクラス(readOnly/destructive アノテーション)、意味的なツール照合、ツールごとのクォータ。