ツール方針
ツール方針は、エージェントが実行してよいツール呼び出しを決める、組織ごとの規則です。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 メトリクスで数えられます — 方針決定の追跡面です(レスポンス自体には、拒否された呼び出しはもう含まれません)。
評価順序
最も具体的な一致が勝ちます。
- 正確なツール名 > より長いワイルドカード接頭辞 > より短いワイルドカード >
* - エージェント固有のサブジェクトは
*に勝ちます - より小さい
priority番号(0–1000、デフォルト 100) - 安定した名前順
ワイルドカードは末尾の星のみです(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_fetch | yabanin:web_fetch | URL への HTTP GET。テキスト系のコンテンツのみ、上限 2 MiB |
http_request | yabanin:http_<method> | JSON ボディ付きの任意の HTTP メソッド(get/post/put/patch/delete)。方針名はメソッドと合成されるため、network-readonly は yabanin:http_post を自然に拒否します |
http_head | yabanin:http_head | HEAD リクエスト。ボディなしのレスポンスヘッダー(資格情報ヘッダーは除去) |
dns_lookup | yabanin:dns_lookup | ゲートウェイのリゾルバから、ホスト名を A/AAAA レコードへ解決します |
time_now | yabanin: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 アノテーション)、意味的なツール照合、ツールごとのクォータ。