AI Agent Gatewayコントロール：ツールの使用、予算、ログ、停止条件

AI Agent Gatewayコントロールは、エージェントが何を呼び出せるか、いくらまで使用できるか、どのような証拠を記録する必要があるか、そしていつ実行を一時停止、フォールバック、または停止する必要があるかを決定する運用ルールです。これらのコントロールがなければ、エージェントゲートウェイは、ツールの無秩序な増加、トークン消費の暴走、不明確な本番環境での障害を隠すためのより速い方法になってしまいます。

目標は、すべてのエージェントをプロセスでがんじがらめにすることではありません。目標は、エージェントの動作が本番ユーザーに届く前に検査可能にすることです。注文を検索できるサポートエージェント、ファイルを編集できるコーディングエージェント、請求書を比較できる財務エージェントは、同じツールアクセス、予算、ロギング、または停止ポリシーを共有すべきではありません。

このガイドを使用して、AIエージェントゲートウェイコントロールをポリシー、証拠フィールド、および受け入れテストとして設計してください。次に、展開前にFlatkeyの価格設定で現在のFlatkeyモデル、ルーティング、使用状況、および請求の証拠を検証してください。

AIエージェントゲートウェイコントロールはポリシー境界から始まる

エージェントゲートウェイは、エージェントランタイム、モデルAPI、内部ツール、および財務レビューの間に位置します。そのため、4つの決定を標準化するのに適した場所となります。

これらのAIエージェントゲートウェイコントロールは、プロンプトのコピーとしてではなく、インフラストラクチャポリシーのようにレビューされるべきです。プロンプトは意図を説明できますが、ゲートウェイポリシーは、モデルが機密性の高いツールを要求したり、予算を超過したり、予期しないツール結果を受け取ったり、ループしたりした場合に何が起こるかを強制する必要があります。

ツールの使用コントロール：エージェントが知っているよりも少ないツールを許可する

ツール呼び出しは、モデルを実際のシステムに接続するため強力です。また、エージェントが提案から行動に移る場所でもあります。OpenAIの関数呼び出しのドキュメントでは、ツール呼び出しを複数ステップのフローとして説明しています。モデルがツールを要求し、アプリケーションがそれを実行し、ツールの出力がモデルに返されます。同様に、Anthropicのツール使用のドキュメントでは、Claudeがtool_useブロックを返し、アプリケーションコードが実行を担当します。Google Geminiの関数呼び出しも、宣言された関数とモデルが生成した関数呼び出しに依存します。

その共通パターンはAIエージェントゲートウェイコントロールにとって重要です。モデルはツールを直接実行すべきではありません。ゲートウェイまたはランタイムは、要求されたツールが許可されているか、引数がポリシーに一致するか、承認が必要か、そしてツール結果を安全に送り返せるかを決定する必要があります。

3層のツールポリシーを使用してください。

1. ツールカタログ：組織内に存在するツールの完全なセット。
2. ワークフロー許可リスト：特定のエージェントルートが呼び出すことができる、より小さなツールのセット。
3. ターンレベルの制限：役割、テナント、環境、予算、およびリスクのチェック後にこのリクエストで利用可能なツール。

たとえば、カスタマーサポートエージェントは、通常モードではlookup_order、search_policy、およびopen_ticketにアクセスできる場合があります。ワークフローが承認されたエスカレーションパスに達するまで、issue_refund、cancel_contract、またはdelete_accountを受け取るべきではありません。

コントロールは明示的であるべきです。

workflow: support_resolution_agent
tool_policy:
  default_mode: deny
  allowed_tools:
    - lookup_order
    - search_policy
    - open_ticket
  approval_required:
    - issue_refund
    - cancel_subscription
  blocked_tools:
    - export_customer_database
schema_rules:
  require_strict_arguments: true
  reject_unknown_fields: true
  log_redacted_arguments: true
on_violation:
  action: stop
  user_message: ask_for_human_review

OpenAIの関数呼び出しガイドでは、明確な関数記述、JSONスキーマ、サポートされている場合は厳格モードを使用し、最初に利用可能な関数を少なく保つことを推奨しています。これは単なるモデルパフォーマンスに関するアドバイスではありません。これはエージェントゲートウェイのコントロールでもあります。公開されるツールが少ないほど、インシデント後にレビューすべき無効な状態が少なくなることを意味します。

予算コントロール：1回のモデル呼び出しだけでなく、実行全体に上限を設ける

エージェントのコストが1回のクリーンなリクエストから発生することはめったにありません。コストは、ツールスキーマ、会話履歴、検索コンテキスト、推論トークン、ツール結果、リトライ、フォールバックモデル、および部分的な失敗後の繰り返しの試行から発生します。

予算に関するAIエージェントゲートウェイコントロールは、実行全体をカバーする必要があります。

ハードリミットを超えた場合、ゲートウェイはフェイルクローズする必要があります。要約、スコープの縮小要求、人間によるレビューのキューイング、または制御されたエラーの返却が可能です。サイレントに大きなプロンプトを送信したり、より高価なルートに切り替えたり、リトライを続けたりすべきではありません。

この予算の形式を使用してください：

budget_policy:
  workflow: invoice_reconciliation_agent
  owner_key: finance_ops
  per_request:
    max_input_tokens: 32000
    max_output_tokens: 4000
    max_model_calls: 4
    max_tool_calls: 5
  per_session:
    max_total_tokens: 90000
    max_total_cost_usd: reviewed_threshold
  retry:
    max_attempts: 2
    retryable_statuses: [408, 409, 429, 500, 502, 503, 504]
  fallback:
    max_fallbacks: 1
    require_reason: true
  on_over_budget:
    action: stop_or_request_scope_reduction

ここでFlatkeyの公開されている製品の側面が関連してきます。現在のFlatkeyのホームページは、プラットフォームを統一されたモデルアクセス、ルーティング、請求、使用状況分析、および運用管理を中心に位置づけています。現在の価格ページでは、プリペイドのチャージ、使用状況分析、コスト管理、リクエストログ、プロバイダー横断の単一請求書、およびチームの調達パスについて説明しています。これらを現在の公開計画の証拠として扱い、本番環境に移行する前にダッシュボードで独自の検証を実行してください。

ログ：生のプロンプトだけでなく、証拠を記録する

エージェントのログは、2つの質問に答える必要があります。実行時に何が起こったのか、そして誰がポリシーが機能したことを証明できるのか？

VercelのAI Gateway可観測性ドキュメントでは、支出、モデル使用状況、可観測性メトリクス、リクエストサマリー、APIキー、リクエストログに関するゲートウェイログについて説明しています。OpenAIのAgents SDK可観測性ドキュメントでは、モデル呼び出し、ツール呼び出し、ハンドオフ、ガードレール、カスタムスパンを含むことができるトレースについて説明しています。これらの例は同じ運用要件を指し示しています。つまり、エージェントゲートウェイには、モデルの動作をルート、ツール、予算、停止の決定に結びつけるログが必要です。

AIエージェントゲートウェイのコントロールのためには、最低限これらのフィールドをログに記録してください：

簡単だからといって、すべてを永久にログに記録しないでください。顧客データ、プロンプト、ツールの結果、ファイルには機密情報が含まれている可能性があります。耐久性のあるログ設計では、編集、保持、アクセスレビュー、エクスポートのニーズ、およびインシデント手順を定義する必要があります。ゲートウェイは、すべてのリクエストを制御不能なデータアーカイブに変えることなく、デバッグと使用状況の調整に十分な証拠を保存する必要があります。

停止条件：モデルが開始する前に実行の終了を定義する

停止条件は、単なるモデルの停止シーケンスではありません。エージェントの実行を安全に終了させるためのルールです。

プロバイダーのAPIは、さまざまな応答と停止の側面を公開しています。AnthropicのMessages APIは、ドキュメントでツールの使用、ターンの終了、最大トークン、停止シーケンスなどのstop_reasonフィールドを公開しています。OpenAIのAgents SDKガードレールドキュメントでは、ガードレールと人間によるレビューを、実行を継続、一時停止、または停止するタイミングを決定するコントロールとして位置づけています。本番環境では、ゲートウェイはこれらのプロバイダー固有の状態を、チームが理解できるワークフローの状態に正規化する必要があります。

停止マトリックスを使用してください：

重要な点は、すべての終端状態に名前があることです。「成功」と「エラー」という状態しかない場合、チームはエージェントがポリシーを遵守したのか、それとも単に偶然停止したのかを判断できません。

実用的なAIエージェントゲートウェイコントロールのテンプレート

エンジニアリング、セキュリティ、財務、製品の各チームが共同でレビューできるポリシーファイルを使用します。

policy_name: ai_agent_gateway_controls_v1
owner:
  team: ai_platform
  reviewers:
    - engineering
    - finance
    - security
workflow_classes:
  support_agent:
    route: balanced_text_tool_route
    allowed_tools: [lookup_order, search_policy, open_ticket]
    approval_tools: [issue_refund, cancel_subscription]
    max_tool_calls: 5
    max_model_calls: 4
  code_agent:
    route: code_review_route
    allowed_tools: [read_repo, search_repo, propose_patch]
    approval_tools: [apply_patch, run_shell_command]
    max_tool_calls: 12
    max_model_calls: 8
budget_rules:
  require_owner_key: true
  block_when_owner_budget_exceeded: true
  require_fallback_reason: true
log_rules:
  capture_request_id: true
  capture_requested_and_served_model: true
  capture_tool_call_status: true
  redact_sensitive_arguments: true
stop_rules:
  max_steps: 12
  max_retries_per_tool: 1
  on_policy_violation: stop
  on_approval_required: pause
acceptance_tests:
  - blocked_tool_is_not_executed
  - over_budget_request_fails_closed
  - approval_tool_pauses_run
  - fallback_records_reason
  - request_log_contains_usage_and_stop_condition

このファイルはアプリケーションコードを置き換えるものではありません。コードに強制すべき契約を与え、レビュー担当者に検査すべき具体的な成果物を提供します。

本番稼働前の受け入れテスト

トラフィックを本番に流す前に、各ワークフロークラスに対して受け入れテストを実行します。

1. 通常のリクエストを送信し、許可されたツールのみが公開されていることを確認します。
2. ブロックされたツールを要求し、そのツールが実行されないことを確認します。
3. 承認が必要なツールを要求し、実行が再開可能な状態で一時停止することを確認します。
4. 大きすぎるプロンプトを送信し、ゲートウェイが停止するか、スコープの縮小を要求することを確認します。
5. ツールエラーをトリガーし、再試行回数、フォールバック理由、最終状態がログに記録されることを確認します。
6. プロバイダーのタイムアウトを強制し、フォールバックがフォールバック予算内に収まることを確認します。
7. 最大ステップ数をトリガーし、実行がループしないことを確認します。
8. リクエストログに所有者キー、リクエストされたモデル、提供されたモデル、使用状況、ツールステータス、予算結果、停止条件が表示されることを確認します。
9. リクエストログから請求書または前払い残高の動きへの財務照合をサンプリングします。
10. モデル、ツール、プロンプト、またはルートポリシーを変更した後、同じテストを再実行します。

この記事を、FlatkeyのAI APIゲートウェイアーキテクチャ、LLM APIゲートウェイアーキテクチャ、AI APIの負荷分散とフェイルオーバー、モデルルーティングポリシーの設計に関するガイドと合わせてお読みください。ゲートウェイアーキテクチャはコントロールの配置場所を決定し、受け入れテストはそれらが機能することを証明します。

Flatkeyが適合する場面

Flatkeyは、エージェントポリシーが存在する唯一の場所であるべきではありません。ポリシーはコード、設定、または内部のコントロールリポジトリに保持してください。Flatkeyは、チームがモデルアクセス、ルートレビュー、使用状況の可視性、リクエストログ、コスト管理、前払い残高、請求レビューを一元化できるゲートウェイサーフェスとして使用します。

Flatkeyの実用的な展開は次のようになります。

1. 既知のツールと所有者を持つエージェントワークフローを1つ選択します。
2. 許可されたツール、承認ツール、予算上限、ログフィールド、停止条件を定義します。
3. Flatkeyの価格で現在のモデルと価格オプションを確認します。
4. 非本番用のキーで受け入れテストを実行します。
5. リクエストされたモデル、提供されたモデル、使用状況、ルート決定、フォールバック理由、停止条件についてログを確認します。
6. テスト済みのワークフローのみを本番に移行します。
7. 新しいツールとフォールバックルートを一度に1つのポリシー行ずつ追加します。

証明が通ったら、キーを取得し、最初の展開は範囲を狭く保ちます。最も強力なAIエージェントゲートウェイコントロールは、本番環境では退屈なものです。すべてのツール呼び出しには理由があり、すべての予算決定には追跡があり、すべての失敗には名前付きの停止条件があり、すべてのレビュー担当者が何が起こったかを確認できます。

よくある質問

AIエージェントゲートウェイコントロールとは何ですか？

AIエージェントゲートウェイコントロールは、ゲートウェイを介してモデルとツールを呼び出すエージェントワークフローのための、ツールのアクセス、予算、ログ、フォールバック動作、停止条件を管理するポリシーです。

AIエージェントゲートウェイコントロールはモデルルーティングと同じですか？

いいえ。モデルルーティングは、どのモデルまたはプロバイダーがリクエストを処理すべきかを決定します。AIエージェントゲートウェイコントロールは、エージェントがツールを呼び出すか、より多くの予算を消費するか、再試行するか、フォールバックするか、承認のために一時停止するか、または停止するかを決定します。

エージェントのツール使用に関して何をログに記録すべきですか？

リクエストID、ワークフロークラス、所有者キー、要求されたモデル、提供されたモデル、ツール名、スキーマバージョン、編集された引数、結果ステータス、使用量、予算結果、フォールバック理由、停止条件をログに記録します。

機密性の高いツールは常にモデルから利用可能であるべきですか？

いいえ。完全なツールカタログは、ワークフローの許可リストとは別に保持してください。機密性の高いツールには、承認、より狭いスコープ、または別のエスカレーションルートが必要です。

予算超過はどのように処理すべきですか？

厳格な予算超過はフェイルクローズにすべきです。ゲートウェイは、スコープの縮小を要求したり、要約したり、レビューをキューに入れたり、制御されたエラーを返したりすることができますが、より高価なルートに黙って切り替えるべきではありません。

FlatkeyはAIエージェントゲートウェイコントロールにどのように役立ちますか？

Flatkeyは、モデルアクセス、ルーティングレビュー、使用状況の可視性、リクエストログ、コスト管理、前払い残高、請求レビューのための一元的なゲートウェイサーフェスをチームに提供します。本番環境のエージェントワークフローには、そのサーフェスをポリシー・アズ・コードや受け入れテストと併用してください。