Bedrock AgentCore Gateway連携時、Amazon ConnectのInput SchemaにbasePathが表示される場合の対処法
困っていること
Amazon Connect (Amazon Q in Connect) のAIエージェント機能を利用し、REST API (API Gateway) を呼び出す構成を構築しています。
具体的には、Bedrock AgentCore Gateway のターゲット設定にて「Amazon API Gateway」を選択し、連携を行っています。
この構成で、Amazon Connect の「オーケストレーション」設定にてツールを追加した際、Input Schema（入力パラメータ）として basePath が表示されてしまいます。
basePath は API Gateway のステージ名（例: dev）を表す固定値であり、本来はAIエージェントが推論して入力すべきパラメータではありません。
検証したところ、AI エージェント 側で basePath がパラメータ利用されることはございませんでしたので、特に悪影響は及ぼさないと考えられます。
しかし、不要なパラメータが表示されることで管理上の混乱を招く恐れがあるため、Input Schema から除外（非表示に）したいと考えています。
回答
Bedrock AgentCore Gateway のターゲット設定を変更し、OpenAPI スキーマ内で URL を直接定義することで解決できます。
原因
Bedrock AgentCore Gateway のターゲットとして「Amazon API Gateway」を選択した場合、Gateway 側は API 定義を OpenAPI 3.0 形式でエクスポートして利用する仕様となっています。
この際、API Gateway のエクスポート仕様により「ステージ名（例: dev）」が basePath として変数化されます。
公式ドキュメントにも以下の記載があります。
API Gateway export
To set up your API Gateway target, AgentCore Gateway calls the GetExport operation for API Gateway on your behalf to get an OpenAPI 3.0 formatted export of your API definition.
(日本語訳: API Gateway ターゲットをセットアップするために、AgentCore Gateway はお客様に代わって API Gateway の GetExport 操作を呼び出し、API 定義の OpenAPI 3.0 形式のエクスポートを取得します。)
また、API Gateway (OpenAPI 3.0) の仕様として、basePath はサーバー変数として扱われるため、エクスポートされた定義には {basePath} という変数が含まれます。
OpenAPI basePath プロパティを設定
「OpenAPI 3.0」では、basePath は、最上位のプロパティではありません。代わりに、API Gateway は規則としてサーバー変数を使用します。
実際にエクスポートされた定義を確認すると、以下のように記述されています。
servers:
- url: "https://{api-id}.execute-api.{region}.amazonaws.com/{basePath}"
variables:
basePath:
default: "dev"
本来接続すべきステージ（環境）は固定であるべきで、AIエージェントが推論して動的に変更すべき値ではありません。
しかし、OpenAPI 3.0 の仕様上、これは「変数」として定義されているため、Amazon Connect の AI エージェント側はこれを「入力可能なパラメータ」として認識し、Input Schema に表示してしまいます。これが原因です。
対処方法
自動エクスポートされた定義をそのまま使うのではなく、手動で定義した OpenAPI スキーマを使用することで、この挙動を回避できます。
手順は以下の通りです。
- Bedrock AgentCore Gateway のターゲット設定にて、「Amazon API Gateway」ではなく「OpenAPI スキーマ (OpenAPI schemas)」を選択します。
- スキーマの入力元として「S3 バケット」または「インラインスキーマエディタ」を選択します。定義する OpenAPI スキーマ内の
servers記述においては変数は使用せず、ステージ名を含んだ URL を直接記述してください。
OpenAPI定義（例）
openapi: 3.0.0
info:
title: Example API
version: 1.0.0
servers:
# 変数を使用せず、ステージ名(/dev)まで含めたURLを直接記述する
- url: "https://xxx.execute-api.ap-northeast-1.amazonaws.com/dev"
paths:
/example:
get:
...
ドキュメントの「OpenAPI schema targets」セクションにあるセキュリティベストプラクティスの例でも、変数を避けて静的なURLを使用するパターンが紹介されています。
Recommended practices:
Use fully qualified, static URLs whenever possible: https://api.example.com/v1(日本語訳: 推奨されるプラクティス: 可能な限り、完全修飾された静的 URL を使用してください: https://api.example.com/v1)
https://docs.aws.amazon.com/ja_jp/bedrock-agentcore/latest/devguide/gateway-schema-openapi.html
このように URL を固定値として定義することで、basePath が変数として扱われなくなり、Amazon Connect の Input Schema にも表示されなくなります。
