エージェントガバナンス
エージェントは Yabanin における第一級のプリンシパルです。エージェントとはマシン ID(自動ワーカー、CI パイプライン、OpenCode セッション)であり、人の API キーと同じ方法で認証します。ただし別々に追跡されるため、どのチームとも独立して、その支出に予算を設定し、タグを付け、利用分析できます。
このページでは、エージェントを統制可能にする 6 つの要素を扱います。
- エージェントキー(
yag_*) — エージェントが使う資格情報。 - エージェントごとの予算 — エージェントごとの、厳しい日次支出上限。
- タスクのタグ付け + トークン予算 — 支出を論理タスクに帰属させ、タスクごと / セッションごとにトークンの上限をかけます。
- ガードフック — 出口前に行う、決定的な PII / 秘密情報 / インジェクションの検査。
- 委任(子)キー — 時間制限、付与制限、予算上限のあるキー。エージェントのオペレーターがサブタスク用に発行します。
エージェントプロファイル — ロールオブジェクト(ティアのヒント + 付与テンプレート + 予算上限
- ガードモード)。キーはこのオブジェクトに対して発行されます。
ここにある機能はすべてオプトインであり、デフォルトではオフです。新しい環境変数を設定しない導入は、以前とまったく同じように動作します。
決定ヘッダー
ゲートウェイは、機械可読な経路決定をレスポンスヘッダー X-Yabanin-Decision として出します(有効な場合は、利用分析イベントにも載せます)。このヘッダーは、リクエストが使ったモデルになぜ着地したかを説明する、コンパクトな JSON オブジェクトです。
X-Yabanin-Decision: {"source":"tier_router","class":"easy","confidence":0.92,"threshold":0.7,"from":"gpt-4o","to":"gpt-4o-mini","reason":"time_window_downgrade"}
| フィールド | 意味 |
|---|---|
source | モデルを選んだ主体: cache_exact、cache_semantic、tier_router、rule_override、または passthrough。 |
class | 使用した分類クラス(easy / medium / hard)。分類器が実行されなかった場合は空です。 |
confidence | 分類器の確信度 [0..1]。分類器が実行されなかった場合は 0 です。 |
threshold | 確信度と比較した、組織ごとの経路しきい値。 |
from | 決定が移動した元のモデル(クライアントが要求したもの、または上書き前)。 |
to | 決定が移動した先のモデル。 |
reason | 任意の自由形式の理由。例: always_premium、always_cheap、time_window_downgrade。 |
affinity / preferred | KV キャッシュを考慮したセッションアフィニティの結果(used / miss)と、優先するウォームなモデル。 |
ヘッダーの有効と無効は YABANIN_DECISION_HEADER(デフォルトはオン)で切り替え、利用分析イベントへの複製は YABANIN_DECISION_EVENT(デフォルトはオン)で切り替えます。
エージェントキー
エージェントキーは、API キーとは別の資格情報クラスです。admin API で作成および失効します(yb CLI はこれらを管理しません)。
POST /api/agent-keys {"name": "nightly-etl", "org_id": "<org>"} → 201
GET /api/agent-keys?org_id=<org>
GET /api/agent-keys/<id>
POST /api/agent-keys/delegate mint a delegated child key (below)
POST /api/agent-keys/<id>/revoke
GET /api/agent-keys/<id>/budget read the agent's daily budget
PUT /api/agent-keys/<id>/budget upsert (daily_limit_cents)
DELETE /api/agent-keys/<id>/budget remove (returns the agent to denied)
POST /api/agent-keys は yag_ キーを生成し、レスポンスの中で平文をちょうど 1 回だけ返します。保存されるのはその sha256 だけです。返されるキーの例(形: yag_ + 16 進 32 文字):
{
"key": "yag_9f2c1a4b7e8d30f6a5c9b2d1e4f7a8c3",
"key_id": "8d4f…",
"name": "nightly-etl",
"org_id": "…",
"active": true
}
エージェントは、キーを Authorization: Bearer <yag_…> 資格情報として送ることで認証します。一致すると、ゲートウェイは次を行います。
- リクエストの
org_id、agent_id(プリンシパル)、およびチームのスコープがあればそれを設定します。 - 支出を帰属できるよう、
request_logsにagent_idをタグ付けします。 - エージェントごとの予算が設定されていれば、それを適用します。
エージェントキーは失効できます(ソフト削除: active=false、revoked_at をスタンプ)。失効したキーは認証に失敗します。
エージェントごとの予算
エージェントごとの日次上限は、agent_budgets テーブル(agent_id、daily_limit_cents)で設定します。動作(フェイルセーフ。チームの予算と同じです):
| 条件 | 結果 |
|---|---|
エージェントに agent_budgets の行がない | 403 agent_budget_not_configured — 予算のないエージェントは支出できません。 |
| 日次支出 ≥ 上限 | 429 agent_budget_exceeded — あとで再試行してください。 |
| 予算ストアが利用できない | 503 agent_budget_check_unavailable — フェイルクローズ(DB 障害の間、無制限の支出を決して許可しません)。 |
| 上限の範囲内 | リクエストは続行します。支出は agent_spend_daily (agent_id, day) に記録されます。 |
設定された行がないエージェントは拒否されます。そのため、エージェントごとの予算を有効にすることは意図的な行為です。支出を許可するエージェントごとに、行を作成してください。
委任(子)キー
エージェントのオペレーターは、親の資格情報を渡すことなく、範囲を限定したサブタスク用の子キーを発行できます。
POST /api/agent-keys/delegate
{"parent_agent": "<agent-key id>", "org_id": "<org>", "name": "subtask-render",
"ttl": 86400, "budget_caps": 500, "mcp_grants": ["knowledge"]}
(ttl は秒であり、上限は 90 日です。mcp_grants は、子が呼び出せるサーバー名を列挙します。それぞれ、親に付与されたサーバーとの積集合を取ります。)
子キーは同じ yag_ の形であり、どのエージェントキーとも同じように認証します。不変条件(発行時に適用します。TTL は解決時に適用します):
| 不変条件 | 適用 |
|---|---|
| 付与 ⊆ 親の有効な付与 | 保存される付与は、要求された集合と親の積集合です。子は、親が呼び出せる範囲を広げることはできません |
| 子の予算 ≤ 親の残り枠 | 親の残りの日次上限を超えることになる場合、委任は拒否されます |
| 時間制限 | すべてのリクエストで、キーのリゾルバが expires_at を確認します。期限切れの子キーは認証に失敗し、期限切れという結果は決してキャッシュされません(TTL のずれはありません) |
| 帰属 | 支出は子自身の agent_id(agent_spend_daily)に載ります。タスクタグによって親へ報告できます |
| 構造 | parent_id がスタンプされます。子は常に子です。委任できるのはルートキー(親がないもの)だけです |
エージェントプロファイル
プロファイルは、あるクラスのエージェントが共有するロール設定をまとめます。経路のティアヒント、MCP 付与のテンプレート、日次予算上限(セント)、ガードモードです。プロファイルに対してキーを発行すると、キーごとに手で設定するのではなく、これらすべてを継承します。
POST /api/agent-profiles {"name": "ci-runner", "tier_hint": "cheap", ...}
GET /api/agent-profiles
GET /api/agent-profiles/<id>
PUT /api/agent-profiles/<id>
DELETE /api/agent-profiles/<id>
profile_id を付けた POST /api/agent-keys は、キーをプロファイルに対して発行します。予算の行はプロファイルの上限から作成され 、MCP 付与はテンプレートから適用されます。不変条件: プロファイルの付与テンプレートは、組織が登録していないサーバーを参照できません(付与 ⊆ 組織自身のレジストリ)。発行によって、組織の影響範囲が広がることはありません。
MCP 付与とユーザーごとの資格情報
MCP 付与(mcp_server_grants)は、エージェントが何を呼び出せるかを表します。MCP の資格情報は、その呼び出しが上流でどのように認証するかを表します。付与は、資格情報フローのすべてのステップに対する上限です(詳細は MCP ゲートウェイ §6)。
- ユーザーごとの資格情報は、そのエージェントがそのサーバーに対する有効な付与を持っている間だけ、送信(headers)または開始(oauth)できます。ストアは、送信、開始、トークンの書き込みでこれを適用します。
- 付与を失効すると、資格情報は孤立します(ステータス
orphaned)。行と、enc:で暗号化された秘密は残りますが、どの呼び出しもそれを使いません。同じ(server, agent)の組を再付与すると、資格情報は復元されます。人が再認可する必要はありません。 - 子キーの
mcp_grants(上記の委任キーを参照)は親との積集合になるため、 委任されたエージェントが、親の付与より広い資格情報フローを持つことはありません。
付与は上限であり、拡大ではありません。資格情報は呼び出しごとに解決され(ユーザーごとで有効 → サーバーレベルで有効 → なし)、SSRF で守られた出口面を広げることはできません。
タスクのタグ付けとトークン予算
X-Yabanin-Task
X-Yabanin-Task ヘッダーを送ると、リクエストを論理タスク(例: バッチジョブ、機能、テナントのワークロード)に帰属できます。形式は [A-Za-z0-9._:-]{1,128} です。タグのないリクエストでも問題ありません。利用分析では '(untagged)' バケットに入ります。無効な値は 400 invalid_task_id で拒否されます。
タスクタグは次に使われます。
- タスクごとのトークン予算(下記)、および
- CTOR / タスクコストの利用分析 —
GET /api/analytics/tasks?group_by=taskと、ダッシュボードのタスク画面(タスクごとのグループ化されたコスト / 反事実 / 節約。チャージバック用の CSV エクスポート付き)。
Yabanin-Task: コミットトレーラー + YABANIN_TASK CI 環境変数
エージェンティックな開発(エージェント駆動の 1 つのタスク → 1 つ以上のコミット → 1 つの PR)では、タスクタグをコミットそのものに載せることで、PR の支出を git から再構成できます。
トレーラーの規約。 タスクが生成するすべてのコミットに Yabanin-Task: トレーラーを追加します(値 = タスクタグ、[A-Za-z0-9._:-]{1,128}、X-Yabanin-Task ヘッダーと同じ形式です):
git commit -m "feat: …" -m "Yabanin-Task: a142-add-login"
git trailer(自由形式の本文行ではないもの)が、git interpret-trailers と下記の CI チェックが依拠するものです。
CI 環境変数。 CI(またはエージェントランナー)で、タスクの期間中そのタグをエクスポートすると、エージェントが行うすべてのモデル呼び出しにタグが付きます。
YABANIN_TASK=a142-add-login # CI env, mirrors the X-Yabanin-Task header
YABANIN_TASK が設定されていると、ゲートウェイは、エージェントのキーが送る各リクエストに同じタスクタグを適用します(クライアントが X-Yabanin-Task を送るのと同等です)。中央のゲートウェイでは、yb ci exec または task ラベルを使います。その後タグは request_logs.task_id に入るため、ダッシュボードのタスク画面と GET /api/analytics/tasks?group_by=task は、PR のモデル支出を a142-add-login に帰属します。これはコミットトレーラーに現れる値と同じです。
この組み合わせが、PR のコストを監査可能にします。コミット上のトレーラー(そのタグの下で出荷されたもの)+ トラフィック上のCI 環境変数(そのタグが使った金額)。タスク画面の CSV エクスポート(グループ、コスト、反事実、節約、キャッシュヒット、リクエスト数)は、その数字をチャージバックに使える成果物です。
トークン予算(タスクごと / セッションごと)
24 時間のウィンドウに対する、任意のインメモリ累積トークン上限です。
| 環境変数 | デフォルト | 意味 |
|---|---|---|
YABANIN_TASK_TOKEN_BUDGET | 0(オフ) | X-Yabanin-Task ごとのトークン上限。推奨の開始値: 500000。 |
YABANIN_SESSION_TOKEN_BUDGET | 0(オフ) | X-Session-Id ごとのトークン上限。推奨の開始値: 200000。 |
0 は、そのスコープがオフであることを意味します(状態は作られず、動作の変化はありません)。上限が設定されている場合:
- 転送の前に、ゲートウェイは累計を確認します。上限の 80% 以上になると、レスポンスヘッダー
X-Yabanin-Budget-Warning: token budget at or above 80%を設定し、リクエストを通します(停止ではなく予告です)。100% 以上になると、Retry-Afterヘッダー付きの 429token_budget_exceededを返します。 - レスポンスの後に、最終的なトークン使用量(プロンプト + コンプリーション)を、タスク予算とセッション予算の両方に記録します。これはチャット経路とストリーミング経路の両方で実行されます。
429 と警告の意味は、他の予算ゲートと同じです。警告は致命的ではなく、超過はクライアントがバックオフできる構造化された 429 です。
ガードフック
ガードフックは、外向きのモデル応答と内向きのプロンプトに対して、出口前に実行されます。機密データとプロンプトインジェクションのための、決定的な正規表現/チェックサムの検出器です。DLP システムではありません(下記の注意を参照)。
モード(YABANIN_GUARD_MODE、デフォルトは off):
| モード | 動作 |
|---|---|
off | スキャンなし(デフォルト)。オーバーヘッドはありません。 |
log | 検出してメトリクス/ログを出します。レスポンスは変更しません。 |
redact | レスポンスを返す前に、検出した範囲をプレースホルダに置き換えます。 |
deny | 検出が発火したとき、リクエストを拒否します(400 guard_denied)。 |
検出されるカテゴリには次が含まれます(網羅的ではありません)。
- PII: INN(チェックディジット検証付きの、10 桁または 12 桁のロシアの納税者 ID)、SNILS(制御桁付きの社会保障番号)、PAN(Luhn 検証に通る支払いカード番号)。
- 秘密情報: 秘密鍵の材料(PEM ヘッダーの検出)、高エントロピーのトークン/キーのパターン。
- プロンプトインジェクション: 高精度パターンの小さな集合(指示の上書き / 持ち出しの言い回し)。
偽陽性についての正直な注意
検出器は意図的に保守的です。単なる 10 桁または 12 桁の数字の並びは、対応するチェックディジット / Luhn の検証にも通った場合にだけフラグが立ちます。そのため、普通の数字(ID、電話番号、金額)にはフラグが立ちません。これにより偽陽性率は低く保たれますが、ゼロではありません。そしてこれはデータ損失防止の統制ではありません。ガードフックは、明らかな機密データを表面化し、ブロックできるガードレールです。機密データが決して外に出ないことを保証するものではありません。規制の対象となる導入では、出口フィルタリング、ならびにレジデンシーとリネージの統制と組み合わせてください。
CTOR / タスクコストの利用分析
GET /api/analytics/tasks は、グループごとに、実コスト、反事実コスト(同じ作業がプレミアムティアだった場合にかかるコスト)、その結果としての節約、キャッシュヒットを返します。
GET /api/analytics/tasks?org_id=<org>&from=<RFC3339>&to=<RFC3339>&group_by=task&limit=100
group_byはtask、session、またはagentです(デフォルトはtask)。from/toは RFC3339 です(デフォルト: 直近 24 時間 → 現在)。limitの上限は 500 です(デフォルトは 100)。グループはコストの降順に並びます。- グループ値がない行は、
'(untagged)'バケットに入ります。
例(1 つのグループ):
{
"org_id": "…",
"from": "2026-09-01T00:00:00Z",
"to": "2026-09-02T00:00:00Z",
"group_by": "task",
"groups": [
{
"group": "nightly-etl",
"cost_usd": 10.0,
"counterfactual_usd": 20.0,
"savings_usd": 10.0,
"cache_hits": 5,
"request_count": 50
},
{ "group": "(untagged)", "cost_usd": 3.0, "counterfactual_usd": 6.0, "savings_usd": 3.0, "cache_hits": 1, "request_count": 10 }
],
"total_cost_usd": 13.0
}
counterfactual_usd は、リクエストごとに記録されたプレミアムティアのコストです。そのため savings_usd が実際の CTOR(counterfactual-of-the-router)の数字になります。使った金額と、ルーターのティア最適化がなかった場合にその作業にかかったであろうコストとの差です。
環境変数リファレンス
| 変数 | デフォルト | 目的 |
|---|---|---|
YABANIN_GUARD_MODE | off | ガードフックのモード: off / log / redact / deny。 |
YABANIN_TASK_TOKEN_BUDGET | 0 | タスクごとのトークン上限(0 = オフ)。 |
YABANIN_SESSION_TOKEN_BUDGET | 0 | セッションごとのトークン上限(0 = オフ)。 |
YABANIN_TIME_ROUTING | false | 安価な時間帯 / バッチのティア降格を有効にします。 |
YABANIN_TIME_CHEAP_WINDOW | 22:00-07:00 | 安価な時間帯(HH:MM-HH:MM。深夜 0 時をまたいでもかまいません)。 |
YABANIN_DECISION_HEADER | true | X-Yabanin-Decision レスポンスヘッダーを出します。 |
YABANIN_DECISION_EVENT | true | 決定を利用分析イベントに載せます。 |
クライアントが送れるヘッダー:
| ヘッダー | 目的 |
|---|---|
X-Yabanin-Task | リクエストを論理タスクに帰属します(トークン予算と利用分析に使います)。 |
X-Yabanin-Batch: true | 安価なティアへの降格を強制します(バッチ作業)。 |
X-Yabanin-Priority: high | このリクエストについて、安価な時間帯の降格をオプトアウトします。 |
X-Session-Id | セッションの識別子(セッションのトークン予算に使います)。 |