sample-agentcore-gateway-usage-interceptor

AgentCore Gateway によるモデル利用の認証・認可と利用量・予算管理 はじめに こんにちは、AWS Japan AI Specialist Solutions Architect の Narimoto です。 業務での AI 活用には、問い合わせへの回答や文書の要約、コーディングエージェントによる実装やテストなど、さまざまな使い方があります。さらに、継続的な役割を持ち、人と協働しながら複数のタスクを進める AI Teammate (AI 社員) としての活用も考えられます。本稿では、このようなエージェントを AI 社員と呼びます。 利用者が一度依頼した後も、AI 社員はモデルを繰り返し呼び出します。組織でこうした利用を広げるには、呼び出し元の利用者やエージェントを認証し、役割や業務に応じて利用できるモデルを許可する必要があります。また、複数のエージェントが同時に動く場合は、特定の呼び出し元から要求が集中しないよう、呼び出し頻度や同時実行数にも上限を設けたいところです。さらに、調査や試行錯誤が続けば費用も積み上がります。できるだけ品質の高い結果を得られるようにしながら、どの予算へ費用を計上し、いくらまで使えるかも管理する必要があります。 LLM Gateway としての AgentCore Gateway このようなモデルの利用の課題 (認証・認可、利用量の制限、費用・予算) 以外にも、次のような課題が挙げられます。 こうしたモデルの利用の課題を共通のエントリポイントで管理するために、本稿では Amazon Bedrock AgentCore Gateway (以下 AgentCore Gateway) を LLM Gateway として活用します。 AgentCore Gateway の機能と、追加実装で扱う範囲を次の表に整理します。 観点 機能 接続・API AgentCore Gateway の inference target でモデル呼び出しを構成 モデル選択・最適化 AgentCore Gateway ルール でモデルの振り分けを設定 認証・認可 AgentCore Gateway の Inbound auth で呼び出し元を検証し、Amazon Bedrock AgentCore Policy (以下 AgentCore Policy) で操作とモデルの権限を管理、AgentCore Gateway Interceptors で業務固有の検査を追加 利用量の制限 AgentCore Gateway の rate limit で要求数・トークン数・同時接続数を制限 費用・予算 公開サンプル の AgentCore Gateway の REQUEST interceptor で予算を検査し、RESPONSE interceptor で応答の usage と設定単価から費用を計上 障害対応 AgentCore Gateway ルールの fallback で接続先の失敗などに対応 ガードレール AgentCore Policy と Bedrock Guardrails の連携 を利用 本稿で扱う構成と管理単位 今回は、「利用を管理する」観点から AgentCore Gateway における「認証・認可、利用量の制限、費用・予算」の範囲を紹介します。 その構成例として、利用者から依頼を受けた AI 社員が、利用者の権限と予算でモデルを呼び出す構成を考えます。AgentCore Gateway で利用者と許可されたモデルを確認し、呼び出し頻度や同時接続数を制限します。費用・予算管理には AWS の公開サンプル を使い、応答の利用量から費用を計上します。日次または月次の予算への到達を確認したら、新しいモデル呼び出しを拒否します。 モデルの利用権限や費用・予算は、例えば次の単位で管理する設計が考えられます。呼び出し元のユーザーやエージェントを認証したうえで、担当業務や所属、タスクの目的に応じて利用できるモデルと予算を設定します。 管理の単位 認証・認可の例 費用・予算の例 タスク単位 認証済みの利用者やエージェントに、対象タスクで必要なモデルの利用を許可 一つの調査やコード修正について、完了または停止までに使う費用を制限 プロジェクト単位 所属する利用者やエージェントに、プロジェクトで利用を認めたモデルへのアクセスを許可 参加する利用者やエージェントの費用を集計し、共有の枠で管理 ユーザー単位 利用者を認証し、担当業務や役割に応じて利用できるモデルを設定 一人の利用者が複数のタスクで使う費用を、月単位などで管理 AI 社員単位 AI 社員を呼び出し元として識別・認証し、任せる業務に必要なモデルの利用を許可 継続的な役割を任せたエージェントについて、複数タスクの費用を月単位などで管理 AI 社員へ継続的に仕事を任せるなら、「どの業務で、どのモデルを使わせるか」と「一カ月いくらまで使わせるか」を組み合わせて管理する必要があると考えています。 このうち、公開サンプルが実装するのは JWT から識別した利用者ごとの日次・月次予算です。本稿ではその実装を使い、AgentCore Gateway における inbound auth、AgentCore Policy、rate limit を追加する設定例を紹介します。 AgentCore Gateway のターゲットと推論の接続 AgentCore Gateway の接続先 は「target」と呼びます。集約したい呼び出しに合わせて target の種類を選びます。 MCP targets は、AWS Lambda、OpenAPI などで定義した API、既存の MCP サーバーなどのツールを一元管理します。エージェントへツールを公開し、一覧取得やセマンティック検索を使いたい場合の選択肢です。 HTTP targets は、リクエストのパスに応じて接続先を選び、HTTP のまま転送します。AgentCore Runtime 上のエージェント や HTTPS endpoint を共通のエントリポイントから呼ぶ場合に使います。 Inference targets は、指定されたモデル ID に応じて推論先を選びます。Amazon Bedrock、OpenAI、Anthropic などのモデル呼び出しを一元管理します。本稿の LLM Gateway 用途として使用します。 MCP targets を前提としたアクセス制御は、以下の「AgentCore Gateway で MCP サーバー・ツールのアクセス制御を実現する 3 つの方法の徹底比較」の Zenn 記事をご覧ください。 zenn.dev 図の青い実線は通信、紫の点線は AgentCore Gateway に関連付ける接続設定です。組み込みの定義を使う connector と、HTTPS endpoint、モデルの対応、操作のパスを指定する provider があります。 図の Responses、Messages、InvokeModel はモデル提供者側の API です。connector / provider は接続を設定する方法なので、API の種類とは別に選びます。 Connector によるターゲット登録 connector は、対応するプロバイダーの組み込み設定を使う方法です。接続先や操作、モデル ID の扱いを個別に設定する代わりに、connectorId を指定します。以下は bedrock-mantle の登録例です。 gateway_id には作成済み AgentCore Gateway の ID を指定します。Boto3 は実行環境の認証情報を使い、region_name で操作先のリージョンを明示します。 import boto3 control = boto3.client("bedrock-agentcore-control", region_name="<Region>") target = control.create_gateway_target( gatewayIdentifier=gateway_id, name="bedrock-mantle", targetConfiguration={ "inference": { "connector": {"source": {"connectorId": "bedrock-mantle"}} } }, credentialProviderConfigurations=[ {"credentialProviderType": "GATEWAY_IAM_ROLE"} ], ) 組み込み ID は bedrock-mantle、bedrock-runtime、openai、anthropic です。たとえば bedrock-runtime connector は Bedrock のモデルカタログから検出し、InvokeModel / InvokeModelWithResponseStream などの操作を設定します。モデルの検出元や対応 API は接続先の仕様を確認します。 ! この例の接続先は Amazon Bedrock です。GATEWAY_IAM_ROLE は AgentCore Gateway の実行ロールで送信要求を署名する設定であり、利用者の JWT を Bedrock へ転送する設定ではありません。OpenAI や Anthropic の直接契約は必須ではありません。 Provider による接続先・モデルの指定 provider は、HTTPS endpoint や操作ごとのモデルを明示する方法です。path は AgentCore Gateway 側の操作パス、providerPath は転送先で異なるパスを使う場合の指定です。 次は今回追加する bedrock-models target の例です。SDK から取得したリージョンの Bedrock Runtime endpoint に、Responses と Messages の 2 操作と、それぞれの global inference profile ID を登録します。 import boto3 region_name = "<Region>" control = boto3.client("bedrock-agentcore-control", region_name=region_name) runtime = boto3.client("bedrock-runtime", region_name=region_name) provider_target = control.create_gateway_target( gatewayIdentifier=gateway_id, name="bedrock-models", targetConfiguration={ "inference": { "provider": { "endpoint": runtime.meta.endpoint_url, "operations": [ {"path": "/v1/responses", "providerPath": "/openai/v1/responses", "models": [{"model": "global.openai.gpt-6-sol"}]}, {"path": "/v1/messages", "providerPath": "/anthropic/v1/messages", "models": [{"model": "global.anthropic.claude-haiku-5-5"}]}, ], } } }, credentialProviderConfigurations=[ {"credentialProviderType": "GATEWAY_IAM_ROLE"} ], ) 呼び出し元は /inference/v1/responses または /inference/v1/messages に要求を送ります。元の Mantle target と REQUEST / RESPONSE Lambda は保持し、AI 社員用の Policy は追加した bedrock-models の操作とモデル ID を許可します。 ! 追加実装では、AgentCore Gateway の実行ロールに選択した inference profile と参照先の foundation model に対する推論権限を付与します。Responses API の権限要件に合わせ、アカウント・リージョンの project/default にも bedrock:InvokeModel を許可します。既存の interceptor 呼び出し権限も保持します。 AWS サービス構成 今回の構成では、AgentCore Gateway の認証・認可、利用量の制限、費用・予算を組み合わせます。Inbound auth で呼び出し主体を検証し、AgentCore Policy で操作とモデルの利用を認可します。Rate limit で呼び出し頻度と同時接続数を制限し、公開サンプルの REQUEST / RESPONSE interceptors で費用・予算を管理します。 図では、利用者が Amazon Cognito から JWT を取得し、リクエストとともに AgentCore Runtime へ送ります。Runtime 上のエージェントは、その JWT を付けて AgentCore Gateway を呼び出します。AgentCore Gateway は利用者の主体を検証し、REQUEST interceptor で予算を確認してからモデルを呼びます。応答は RESPONSE interceptor で費用を計上した後、エージェントへ返します。 Lambda は AgentCore Gateway が呼び出す interceptor として配置します。Runtime と AgentCore Gateway の間に、モデル呼び出しを中継する専用のバックエンドは設けません。本稿の実装 は、公開サンプルの構成に AgentCore Runtime V2 上の簡易な AI 社員を追加しています。AI 社員は作業計画を考え、ツールで作業項目を記録し、その結果を利用者へ返します。 ! 同じ JWT を引き継ぐには、Runtime と AgentCore Gateway の両方で、その JWT を受け入れる authorizer を設定します。Runtime では requestHeaderConfiguration.requestHeaderAllowlist に Authorization を追加 し、エージェントコードで受け取った値を AgentCore Gateway 向けリクエストの Authorization に設定します。Runtime が AgentCore Gateway へ自動転送する機能ではありません。同じ利用者の JWT で動く複数のエージェントは、利用者の予算を共有します。 設計するもの 判断すること 使用するサービス・機能 呼び出し元の識別 誰の依頼としてモデルを呼び出しているか Amazon Cognito のユーザープール、AgentCore Runtime と AgentCore Gateway の inbound auth 操作とモデルの認可 その主体に Responses / Messages と対象モデルを許可するか AgentCore Policy の Policy Engine と Cedar ポリシー [Optional] 呼び出し頻度と同時実行数の制限 呼び出し元ごとに設定した RPM・同時接続数の範囲か AgentCore Gateway の rate limit (requests / connections) 予算の設定・変更 利用者ごとに日次・月次でいくら使えるか AWS CloudFormation の既定予算パラメータと Amazon DynamoDB の利用者別上限 予算の検査 計上済み費用が日次・月次予算へ到達したか AgentCore Gateway の REQUEST interceptor と AWS Lambda 利用者と応答の対応付け どの利用者の要求に対する応答か AgentCore Gateway の REQUEST_ID と Amazon DynamoDB のリクエストコンテキストテーブル 費用計上と可視化 どのモデルをどれだけ使ったか RESPONSE interceptor の AWS Lambda、Amazon DynamoDB、Amazon CloudWatch 多層防御とアクセス制御 AWS は、AWS AI セキュリティフレームワーク で、複数の制御を組み合わせる多層防御を推奨しています。判断に必要な情報に応じて実装場所を選びます。 仕組み 実装するもの 判断に使う情報 本構成での役割 AgentCore Gateway の Inbound auth AgentCore Gateway の authorizer 設定 JWT の発行元・client・scope・カスタム claim など AgentCore Gateway を利用できる主体か検証 AgentCore Policy Policy Engine とポリシー 主体・操作・リソース・評価可能な入力 呼び出せる API とモデルの認可ルールを独立して管理 AgentCore Gateway interceptors REQUEST / RESPONSE の Lambda 関数 リクエスト・レスポンスと外部情報 REQUEST で予算を検査し、RESPONSE で費用を計上 AgentCore Policy を使う理由は、認可ルールをモデルの判断から分離し、適用前に決定論的に検証できるようにするためです。累積費用による判断は REQUEST interceptor、どの API とモデルを使ってよいかというルールは AgentCore Policy に置きます。予算が残っていても、認可されていないモデルは使えません。 図は、モデルの呼び出しを例に、JWT の検証、API とモデルの認可、interceptors による独自処理の役割を示しています。AgentCore Gateway の設定やポリシーを変更する権限は、推論する主体から分離します。 AgentCore Gateway への inbound auth Inbound auth は、AgentCore Gateway へのアクセスを受け入れる段階の制御です。JWT を使う場合は、IdP の公開鍵を使った検証に加えて、指定した claim や scope の条件を満たすかを確認します。本稿では Cognito が利用者へ発行した JWT を使い、Runtime を経由する場合もその主体を引き継ぎます。 customJWTAuthorizer の主な設定 は次のとおりです。discoveryUrl に加え、受け入れ条件として allowedAudiences、allowedClients、allowedScopes、customClaims のうち少なくとも一つを指定します。複数を指定した場合は、それぞれの条件が検証されます。 設定 検証する内容 discoveryUrl JWT 検証に必要な公開鍵や認証サーバー情報を取得する IdP の OIDC discovery URL allowedAudiences JWT の aud が許可した宛先に含まれるか allowedClients JWT の client_id が許可したアプリケーションに含まれるか allowedScopes JWT に、指定した scope のうち少なくとも一つが含まれるか customClaims グループやロールなどの claim が、型と比較演算子で指定した条件を満たすか Cognito のアクセストークンを使う設定例では、sub で主体を識別します。Cognito のグループ による共通利用資格を設定するなら、cognito:groups に llm-gateway-access を含むことを要求できます。 この条件は、AgentCore Gateway 自体を使えるかどうかの判定です。利用できるモデルと累積費用は、AgentCore Policy と AgentCore Gateway interceptors で判定します。 次は、作成済みの user pool、app client、実行ロールを使う create_gateway の例です。以下では allowedClients だけではなく、追加のアクセス制御例として customClaims も指定し、利用者を事前に llm-gateway-access グループへ追加する構成にしています。 import boto3 control = boto3.client("bedrock-agentcore-control", region_name="<Region>") cognito = boto3.client("cognito-idp", region_name="<Region>") issuer = cognito.meta.endpoint_url.rstrip("/") + "/" + user_pool_id gateway = control.create_gateway( name="llm-gateway", roleArn=gateway_role_arn, protocolType="MCP", authorizerType="CUSTOM_JWT", authorizerConfiguration={ "customJWTAuthorizer": { "discoveryUrl": issuer + "/.well-known/openid-configuration", "allowedClients": [app_client_id], "customClaims": [ { "inboundTokenClaimName": "cognito:groups", "inboundTokenClaimValueType": "STRING_ARRAY", "authorizingClaimMatchValue": { "claimMatchOperator": "CONTAINS", "claimMatchValue": { "matchValueString": "llm-gateway-access" }, }, } ], } }, ) gateway_id = gateway["gatewayId"] allowedClients と customClaims を組み合わせ、対象のアプリケーション向けに発行された JWT であり、必要なグループも claim に含まれることを確認します。 Cognito のアクセストークンに独自の claim を追加する場合は、AWS Blog How to customize access tokens in Amazon Cognito user pools もあわせてご覧ください。 AgentCore Policy による API とモデルの認可 AgentCore Policy は、AgentCore Gateway が受けたリクエストに対し、ポリシーで定めた操作を許可・拒否する仕組みです。複数のポリシーを Policy Engine に登録して AgentCore Gateway へ関連付けます。Cedar の principal は主体、action は操作、resource は対象の AgentCore Gateway を表します。 Responses / Messages の本文には model があります。推論モデルを制限する公式ガイドのポリシー例 と同じように、context.input.model と主体・操作を組み合わせて認可します。AgentCore Policy は、公開サンプルで作成した AgentCore Gateway に追加する設定です。 次は、一人の利用者に Responses / Messages と対象モデルを許可する Cedar の例です。山括弧の値を実際の値へ置き換えます。action 名は target 名と操作の組み合わせ です。<responses-action-id> と <messages-action-id> には、登録した target のスキーマから確認した action を指定します。 permit( principal == AgentCore::OAuthUser::"<gateway-caller-sub>", action in [ AgentCore::Action::"<responses-action-id>", AgentCore::Action::"<messages-action-id>" ], resource == AgentCore::Gateway::"<gateway-arn>" ) when { ( action == AgentCore::Action::"<responses-action-id>" && context.input.model == "<approved-openai-model-id>" ) || ( action == AgentCore::Action::"<messages-action-id>" && context.input.model == "<approved-anthropic-model-id>" ) }; 本稿は一意に解決するモデル ID を本文へ指定する例です。target 名を付けたモデル ID やモデル名を書き換えるルールを使う場合は、Policy が評価する値との一致も確認します。すべての API を許可する広い permit を併存させると、モデルを限定した条件が意図どおりの制限にならないため、既存のルールも合わせて見直します。 まず、Boto3 で Policy Engine とポリシーを作成します。<cedar ポリシーを記述> には、上の Cedar の例を設定に合わせて記述します。validationMode="FAIL_ON_ANY_FINDINGS" で検証し、ポリシーが ACTIVE になるまで待ちます。 リソースを作成する管理者側には、Policy 作成時の検証に使う bedrock-agentcore:InvokeGateway などの管理権限 が必要です。AgentCore Gateway の実行ロールと、構築作業を行う管理者の権限は別々に設定します。 import boto3 control = boto3.client("bedrock-agentcore-control", region_name="<Region>") engine = control.create_policy_engine(name="model_access_engine") policy_engine_id = engine["policyEngineId"] control.get_waiter("policy_engine_active").wait( policyEngineId=policy_engine_id ) policy = control.create_policy( policyEngineId=policy_engine_id, name="allowed_model_apis", definition={ "cedar": { "statement": "<Cedar ポリシーを記述>" } }, validationMode="FAIL_ON_ANY_FINDINGS", enforcementMode="ACTIVE", ) control.get_waiter("policy_active").wait( policyEngineId=policy_engine_id, policyId=policy["policyId"], ) 関連付けの前に、Policy 評価に必要な IAM 権限 を AgentCore Gateway の実行ロールへ追加します。 IAM 権限を追加したら、update_gateway の policyEngineConfiguration に Policy Engine の ARN を指定して関連付けます。gateway_id は作成済みの AgentCore Gateway の ID です。この API は設定全体を置き換えるため、既存の認証や interceptor などの設定も引き継ぎます。 current = control.get_gateway(gatewayIdentifier=gateway_id) update = { key: current[key] for key in ( "name", "roleArn", "authorizerType", "authorizerConfiguration", "protocolType", "protocolConfiguration", "description", "exceptionLevel", "kmsKeyArn", "interceptorConfigurations", "customTransformConfiguration", "wafConfiguration", ) if key in current } control.update_gateway( gatewayIdentifier=gateway_id, **update, policyEngineConfiguration={ "arn": engine["policyEngineArn"], "mode": "ENFORCE", }, ) ENFORCE は拒否を強制し、LOG_ONLY は評価しても拒否しません。AgentCore Gateway の更新完了後、許可する要求と拒否する要求の両方を試して適用範囲を確認ください。 ポリシーの作成・検証・段階的な適用の進め方は、AWS Blog Secure AI agents with Policy in Amazon Bedrock AgentCore もあわせてご覧ください。 AgentCore Gateway interceptors による追加検査 AgentCore Gateway interceptors は、AgentCore Gateway が扱うリクエストやレスポンスを Lambda 関数へ渡し、独自の検査や変換を追加する仕組みです。REQUEST interceptor は接続先へ送る前、RESPONSE interceptor は接続先から応答を受け取った後に処理します。 実行箇所 受け取る情報 本稿での処理 REQUEST リクエスト本文と、転送を有効にしたリクエストヘッダー JWT から利用者を特定し、DynamoDB の日次・月次費用と予算上限を検査 RESPONSE 接続先から返されたレスポンス usage を解析し、設定単価から費用を計算して DynamoDB と CloudWatch へ記録 HTTP / inference のイベントでは、本文を Base64 から復号して扱います。REQUEST から transformedGatewayResponse を返すと、接続先のモデルを呼ばずに拒否できます。例えば、予算到達時に HTTP 403 と BUDGET_EXCEEDED を返すように設計します。 Inference target は、HTTP 形式の interceptor ペイロードを使用します。Inference target の場合、RESPONSE 側のイベントには、元のリクエスト情報が含まれません。公開サンプルでは、Lambda の context.client_context.custom に渡される REQUEST_ID をキーに、REQUEST 側で利用者とチームを DynamoDB に一時保存し、RESPONSE 側で参照します。 ! 以下は、公開サンプルをもとに処理の要点を示したコードです。_ で始まる補助関数、設定の読み込み、料金表にないモデルの拒否、ログ・例外処理の詳細は省略しています。単独でデプロイするコードではなく、実行にはリンク先の実装全体を使用してください。 REQUEST 側の Lambda では、inbound auth で検証済みの JWT から利用者を特定し、計上済み費用を検査します。予算到達時は拒否の応答を返し、それ以外は空の http を返して元のリクエストを通します。 cloudformation/standalone.yaml: RequestInterceptorFunction の簡略例 import base64 import json def lambda_handler(event, context): request = event["http"]["gatewayRequest"] headers = {k.lower(): v for k, v in (request.get("headers") or {}).items()} user, team = _user_id(headers) request_id = _request_id(context) stashed = _stash_context(request_id, user, team) if not stashed and request_id and user != "unknown" and ENFORCE: return _service_unavailable("context stash write failed") if user == "unknown": return {"interceptorOutputVersion": "1.0", "http": {}} 料金表にないモデルの拒否処理などは省略。 daily_spend, daily_cap, monthly_spend, monthly_cap = _lookup_state(user) if ENFORCE and (daily_spend >= daily_cap or monthly_spend >= monthly_cap): body = json.dumps({"error": {"code": "BUDGET_EXCEEDED"}}) return { "interceptorOutputVersion": "1.0", "http": { "transformedGatewayResponse": { "statusCode": 403, "headers": {"content-type": "application/json"}, "contentType": "application/json", "body": base64.b64encode(body.encode()).decode(), } }, } return {"interceptorOutputVersion": "1.0", "http": {}} RESPONSE 側の Lambda では、REQUEST_ID から利用者を参照し、応答の usage を費用へ換算します。DynamoDB の費用加算と CloudWatch 向けのメトリクス出力を行い、応答自体は変更せずに返します。費用計算は公開サンプルの _cost に任せます。 cloudformation/standalone.yaml: ResponseInterceptorFunction の簡略例 def lambda_handler(event, context): response = event["http"]["gatewayResponse"] passthrough = {"interceptorOutputVersion": "1.0", "http": {}} if response.get("statusCode", 200) >= 400: return passthrough user, team = _fetch_context(_request_id(context)) body = _decode_body(response.get("body"), response.get("contentType") or "") model = _normalize_model(body.get("model")) tokens = _extract_usage(body) if not any(tokens): return passthrough cost = _cost(model, *tokens) if cost > 0 and user != "unknown": _bump_spend(user, cost) _emf(user, team, model, *tokens, cost) return passthrough 次は、両方の interceptor を AgentCore Gateway に関連付ける例です。Lambda 関数の ARN には公開サンプルで作成した alias の ARN を使います。既存の authorizer や前節の Policy Engine の関連付けを保持して更新します。 current = control.get_gateway(gatewayIdentifier=gateway_id) update = { key: current[key] for key in ( "name", "roleArn", "authorizerType", "authorizerConfiguration", "protocolType", "protocolConfiguration", "description", "exceptionLevel", "kmsKeyArn", "policyEngineConfiguration", "customTransformConfiguration", "wafConfiguration", ) if key in current } control.update_gateway( gatewayIdentifier=gateway_id, **update, interceptorConfigurations=[ { "interceptor": {"lambda": {"arn": request_function_arn}}, "interceptionPoints": ["REQUEST"], "inputConfiguration": {"passRequestHeaders": True}, }, { "interceptor": {"lambda": {"arn": response_function_arn}}, "interceptionPoints": ["RESPONSE"], }, ], ) 上のコードは、その関連付けを Boto3 で設定する例です。追加の AgentCore Gateway 設定を持つ場合は、その設定も保持します。 ! 本稿の構成では、RESPONSE interceptor が応答の usage を解析して費用の加算を試みた後、エージェントが結果を返します。 Policy と interceptors の使い分けや組み合わせ方は、MCP ツールのアクセス制御を題材とした AWS Blog Secure AI agents with Policy and Lambda interceptors in Amazon Bedrock AgentCore gateway もあわせてご覧ください。 AWS 公開サンプルによる費用・予算管理 ! 本節は、2026 年 10 月 30 日時点で参照した公開サンプル (コミット d79bd57) に基づいています。サンプルの実装や設定項目は更新される場合があるため、利用する版の README とコードもご確認ください。 Guidance for per-user cost attribution and hard budget enforcement on Amazon Bedrock AgentCore Gateway の AWS 公開サンプルは、利用者ごとの計上済み費用を使って、次のリクエストを受け付けるか判断します。モデルが応答で返した usage を、RESPONSE interceptor が費用へ換算します。 利用者ごとの予算設定 公開サンプルでは、利用者ごとに日次・月次の予算を設定します。共通の既定予算に加え、DynamoDB で利用者別の上限を管理できます。利用者の識別方法と費用の集計単位を先に決め、予算の変更権限は管理側に限定します。 主な変更箇所は次のとおりです。共通の設定は、cloudformation/standalone.yaml の CloudFormation パラメータとして指定します。 変更したい内容 変更箇所 利用者に適用する既定の日次・月次予算と、予算到達時の拒否 DailyBudgetUsd / MonthlyBudgetUsd / EnforceBudget。本稿では拒否を有効にするため EnforceBudget=true 利用者別の予算上限 CloudFormation 出力の SpendTableName が示す DynamoDB テーブルの、対象利用者の daily_cap_usd / monthly_cap_usd 費用集計に使う利用者の識別情報 UserClaim。認可や rate limit と同じ JWT の sub を使う場合は sub を指定 利用するモデルと料金 PriceTableJson。リクエストと応答で扱うモデル ID に対応する単価を登録 日次・月次の期間更新のタイムゾーン RolloverTimezone 設定値の形式や変更手順は 公開サンプルの設定ガイド をご確認ください。 リクエスト時の検査と応答後の計上 REQUEST interceptor は、計上済み費用を日次・月次の予算と比較します。本稿では予算による拒否を有効にし、どちらかに到達した利用者の新しいモデル呼び出しを拒否します。RESPONSE interceptor は、応答の usage と設定したモデル単価から費用を計算し、DynamoDB に加算します。 usage の取得方法やキャッシュ料金の扱いは API・モデルによって異なるため、利用するモデルが計上処理と料金設定の両方に対応しているか確認します。解析・費用計算の詳細は 公開サンプルの Lambda コード、Amazon Bedrock の最新単価は 料金ページ をご確認ください。 ! 参照した版の _extract_usage は、Responses API の usage.input_tokens_details.cached_tokens を読み取らず、キャッシュ分も通常の入力トークンとして扱います。キャッシュ利用時の費用を区別するには、PriceTableJson の変更に加えて、usage の解析処理も対応させる必要があります。 対応する usage の形式や料金区分を拡張する場合は、同テンプレートの ResponseInterceptorFunction 内にある _extract_usage (利用量の解析) と _cost (費用計算) を確認し、必要な処理を追加します。既存の処理で対応できるモデルの単価変更は、PriceTableJson で行います。 ! ここで計上する金額は、usage と設定単価によるモデル推論費用の計算値です。AgentCore Gateway や Lambda などの実行費用、請求上の割引まで含む総額ではありません。 予算到達時の動作と制約 この方式では、予算への到達を確認した後の新しいモデル呼び出しを止めます。実行中の生成を、費用が一定額になった瞬間に中断する仕組みではありません。 ! 費用を事後計上するため、最後の呼び出しや並行要求によって予算を超える可能性があります。キャッシュなどによる状態反映の遅れも考慮が必要です。予算超過を許容できない用途では、事前予約など別の受付設計が必要です。 ! 参照した版の 費用計上時のエラー処理 は、DynamoDB の加算に失敗すると bump_failed を記録しますが、モデルの応答は返します。利用者を特定できない場合も加算を省略するため、usage_recorded の spend_recorded などで計上状況を確認し、未計上分の検出・復旧を設計します。 公開サンプルの 予算読み取り時の処理 も確認し、読み取りに失敗した場合の受付動作を要件に合わせて設計します。 利用量の可視化と期間更新 DynamoDB の費用情報を予算検査に使い、CloudWatch のメトリクスで利用者・チーム・モデルごとの利用傾向を確認します。予算検査の対象は利用者単位であり、チーム共有予算を制御する場合は別途設計が必要です。 日次・月次の費用カウンターの更新や履歴保存も、公開サンプルに含まれます。公開サンプルの メトリクスの出力項目 と 期間更新の実装 をご確認ください。 [Optional] AgentCore Gateway の Rate limit による呼び出し頻度と同時実行数の制限 ユースケースごとの利用ペースを管理したいときに、AgentCore Gateway の rate limit を追加します。例えば、バックグラウンドの調査を進める AI 社員に対して、短い要求を繰り返す頻度や、長時間の推論を並行して実行する数に上限を設ける使い方です。 ! この制限はモデルの処理能力を増やしたり、他の要求へ容量を予約したりするものではありません。上限を低くすれば待機時間が増えるため、すべての仕事を速く進めたいだけなら、制限の追加が有利とは限りません。 RPM と同時接続数の組み合わせ Rate limit の metric は、次の 3 種類です。 Metric 制限するもの 本構成での扱い requests 秒または分あたりの要求数 (Request Per Second / Request Per Minute: RPS / RPM) RPM を採用し、短い要求や再試行の集中を抑制 tokens 分あたりの入力・出力の合計トークン数 (Token Per Minute: TPM) 機能を紹介に留まる connections 受付から応答完了までの同時処理中の要求数 採用し、長い推論やストリーミングの並行数を制限 ! connections は connector の設定数ではなく、同時に処理している要求数です。設定の period は second ですが、毎秒の新規接続回数という意味ではありません。 Rate limit の dimension には、認証済み JWT の claim、IAM の主体、モデル ID、target などを指定できます。今回は $.context.jwt.sub で利用者を識別し、同じ利用者の要求をモデルにかかわらず一つの枠で扱います。* は全員の共有枠ではなく、異なる sub ごとに独立した枠を作る既定値です。Runtime が利用者の JWT を引き継ぐため、その利用者が動かす複数のエージェントも同じ枠を使います。 以下は、Boto3 による rate limit の作成 に二つの metric を指定した例です。300 RPM・同時 5 件は説明用の例の値で、推奨値やサービスの既定値ではありません。 control = boto3.client("bedrock-agentcore-control", region_name="<Region>") rate_limit = control.create_gateway_rate_limit( gatewayIdentifier=gateway_id, description="Per-caller request and concurrency limits", dimensionKeys=["$.context.jwt.sub"], entries=[ { "dimensions": {"$.context.jwt.sub": "*"}, "requests": [{"rate": 300, "period": "minute"}], "connections": [{"rate": 5, "period": "second"}], } ], ) 同じ entry の RPM と同時接続数は両方を評価し、いずれかの metric で制限されると要求を拒否 します。既存の設定を変更する場合は、作成時の rateLimitId を使って更新します。部署全体の共有枠も必要なら、部署を示す検証済み JWT claim に対する rate limit を別途設けます。 上限で拒否された場合の動作 短時間の利用ペースと金額予算では、拒否後の処理を分けます。以下は、呼び出し元のアプリケーションやエージェントで設計する動作です。 状況 呼び出し元の動作 AgentCore Gateway の rate limit による一時的な拒否 retryAfter を使って待機し、回数に上限を設けて再試行 REQUEST interceptor の予算到達による HTTP 403 即時再試行を繰り返さず、利用者へ停止理由を提示 モデル側で処理されたか不明なタイムアウト 再送による重複実行の可能性を考慮し、状態を確認 Rate limit では retryAfter は再試行まで待つ秒数 を設けることが可能です。待機時間と再試行回数には上限を設けます。上流が処理していないと識別できる AgentCore Gateway の拒否と、モデル側の処理状況が不明なタイムアウトを同じ扱いにしません。 Rate limit の詳細やプラクティスは、AWS Blog Configure rate limits for AI traffic on AgentCore gateway も合わせてご覧ください。 すぐに試せるサンプル 本稿の内容をご自身の AWS アカウントで確認できるサンプルリポジトリを用意しました。 SeongHaedu/amazon-bedrock-agentcore-gateway-llm-gateway-samples 以下を体験できます。 AgentCore Runtime V2 に簡易な AI 社員を配置し、作業項目のメモを記録しながら文章の成果物をまとめる処理を試せます。 Cognito が発行した利用者の JWT を Runtime から AgentCore Gateway へ引き継ぎ、不正な JWT やアクセス用グループに所属しない利用者の拒否を確認できます。 AgentCore Policy で利用者ごとにモデルの権限を変え、許可されたモデルの呼び出しと、許可されていないモデルの拒否を比較できます。 AgentCore Gateway の rate limit を利用者ごとに設定し、リクエスト数・同時接続数の制限による拒否を確認できます。 公開サンプルの REQUEST / RESPONSE interceptor による費用計上を DynamoDB と CloudWatch で確認し、日次・月次予算の変更と、予算到達後の新しい呼び出しの拒否を試せます。 リージョン、モデル、料金、予算、利用量の上限は実行環境や設定ファイルから指定します。Runtime は ZIP による直接コードデプロイを使うため Docker は不要です。構築・検証・クリーンアップの手順は、README.md をご覧ください。 おわりに 本稿では、AgentCore Gateway を共通のエントリポイントとして、モデル利用の認証・認可、利用量の制限、費用・予算を管理する構成を紹介しました。それぞれの機能は、次のように役割を分担します。 管理すること 本稿で使う機能と役割 誰の呼び出しを受け付けるか Inbound auth で JWT と共通の利用資格を検証 どの API・モデルを使えるか AgentCore Policy で利用者ごとの操作とモデルを認可 どのペースで使えるか 必要に応じて rate limit を追加し、呼び出し頻度と同時処理数を制限 予算上、新しい呼び出しを受け付けられるか REQUEST interceptor が DynamoDB の計上済み費用と日次・月次予算を比較 誰がどれだけ使ったか RESPONSE interceptor が usage から費用を計上し、DynamoDB と CloudWatch に記録 認証・認可と rate limit には AgentCore Gateway の機能を使い、費用・予算管理には公開サンプルの Lambda と DynamoDB を組み合わせています。認可ルールや費用管理をエージェントの外側に置くことで、複数のアプリケーションから共通の管理を適用できます。 導入時には、機能の設定に加えて次の点を決めておくことが重要です。 管理の単位を決めます。本稿のサンプルは利用者単位ですが、部署・プロジェクト・AI 社員単位で管理する場合は、認証情報と権限・費用を対応付ける設計が必要です。 業務に必要なモデルの権限と利用ペースを決めます。モデルを使う権限、短時間の利用量、累積費用の予算は、別々の条件として設定します。 制限に達した場合や計上に失敗した場合の扱いを決めます。本稿は費用を応答後に計上するため、予算超過を厳密に防ぐ構成ではありません。許容できる超過の範囲と、待機・停止・復旧の方針を要件に合わせて設計します。 本稿が、AgentCore Gateway を使って AI 社員やコーディングエージェントのモデル利用を管理する際の一助となれば幸いです。 参考 Developer Guide: Amazon Bedrock AgentCore Gateway の概要 Inference targets によるモデルへの接続 AgentCore Gateway の inbound auth Amazon Bedrock AgentCore Policy REQUEST / RESPONSE interceptor AgentCore Gateway の rate limit AWS Blog: AWS AI セキュリティフレームワーク: レイヤーとフェーズに応じた適切なセキュリティコントロール How to customize access tokens in Amazon Cognito user pools Secure AI agents with Policy in Amazon Bedrock AgentCore Secure AI agents with Policy and Lambda interceptors in Amazon Bedrock AgentCore gateway Configure rate limits for AI traffic on AgentCore gateway サンプルリポジトリ: 費用・予算管理の AWS 公開サンプル 本稿のサンプルリポジトリ