Amazon Bedrock AgentCore Gatewayをマネジメントコンソールで作成してみた

こんにちは。クラウド事業本部コンサルティング部の桑野です。

皆さんはAmazon Bedrock AgentCoreのGeteway機能をご存知でしょうか？
フルマネージドのサービスで、AIエージェントがツールを発見、アクセス、呼び出しを行うための統一されたインターフェースを提供するMCPサーバーとして機能します。
この機能を利用することによって、AIエージェントがアクセスできるツールを組織で一元的に管理することが可能になります。

https://aws.amazon.com/jp/blogs/news/transform-your-mcp-architecture-unite-mcp-servers-through-agentcore-gateway/

今回はマネジメントコンソールから AgentCore Gateway を作成し、Lambda 製の MCP ツール（IP情報取得）を1つ登録して、CloudShell + awscurl で動作確認するところまでをHow-to形式で共有します。

概要

本ブログでは、Amazon Bedrock AgentCore Gateway を東京リージョン（ap-northeast-1）のマネジメントコンソールから新規作成し、Lambda 関数 demo-get-ip-info を MCP ツールとして登録、CloudShell から SigV4 署名付きリクエストで動作確認するまでの手順を説明します。

各ステップでは、設定項目の値だけでなく その項目がどんな役割を持つのかも記載するようにしています。
とりあえず操作・作成して AgentCore Gateway の挙動を確認するもよし、じっくりと設定項目について1つずつ理解を深めるのもよし、という感じです。

初めて触る方でも抵抗なく進めてもらえるような作りを意識していますので、ご自身のペースに合わせて取り組んでもらえると良いかと思います。

なお、同じようにAmazon Bedrock GuardrailsについてHow-to形式での記事を投稿しておりますので、よければこちらもご覧ください。

https://dev.classmethod.jp/articles/bedrock-guardrails-management-console/

始める前に

AgentCore Gateway を作成する前に、以下を確認してください。

• Amazon Bedrock AgentCore が利用可能なリージョンがアカウント内で使用できる（本手順は東京リージョン ap-northeast-1 を使用）
• マネジメントコンソールから Bedrock AgentCore / Lambda / IAM / CloudWatch / X-Ray を操作できる IAM 権限がある
• CloudShell ログインユーザー（IAM プリンシパル）が AWS_IAM 認可方式の AgentCore Gateway を呼び出せること（管理者ロールであれば追加権限不要）

全体の作業順序

マネジメントコンソールでは、依存関係の都合で Lambda → Gateway → Gateway Target → Observability の順に作るとスムーズです。

1. Lambda 関数 demo-get-ip-info を作成する
2. AgentCore Gateway demo-gateway を作成する
3. Gateway Target GetIpInfo を作成する
4. Gateway Observability を設定する（CloudWatch Logs + X-Ray）
5. CloudShell + awscurl で動作確認する

Lambda 関数を作成する

AgentCore Gateway から呼び出される MCP ツール本体を先に作ります。

1. Lambda 一覧画面を開く

1.1. マネジメントコンソールで AWS Lambda を開き、「関数を作成」を押します。

2. 関数の基本情報を入力する

2.1. 「一から作成」を選び、以下のように入力します。

VPC 設定やその他の設定はスキップします（デモでは Lambda 標準の AWS マネージド NW から ipinfo.io へ到達できればよいため）。

2.2. 「関数の作成」を押します。

3. インラインエディタにコードを貼り付ける

3.1. 「コード」タブの lambda_function.py を以下のコードに置き換えます。

"""Get IP Info Gateway Target Lambda（デモ用 / 依存ライブラリなし）。

AgentCore Gateway 経由で呼び出され、ipinfo.io の Public API から
指定 IP アドレスの地理情報・ASN 情報を取得して返す。
標準ライブラリ urllib のみを使用。
"""

import json
import logging
import urllib.error
import urllib.request

logger = logging.getLogger()
logger.setLevel(logging.INFO)

_IPINFO_BASE_URL = "https://ipinfo.io"
_HTTP_TIMEOUT_SECONDS = 5

def _get_ip_info(ip: str) -> dict:
    """ipinfo.io から IP アドレスの情報を取得する。"""
    url = f"{_IPINFO_BASE_URL}/{ip}/json"

    try:
        with urllib.request.urlopen(url, timeout=_HTTP_TIMEOUT_SECONDS) as resp:
            data = json.loads(resp.read().decode("utf-8"))
    except urllib.error.URLError as e:
        return {"error": f"ipinfo.io への問い合わせに失敗しました: {e}"}

    # ipinfo.io はレートリミット時等にも 200 で error フィールドを返す
    if "error" in data:
        return {"error": f"ipinfo.io エラー: {data['error']}"}

    text = (
        f"IP: {data.get('ip', '')}\n"
        f"ホスト名: {data.get('hostname', '不明')}\n"
        f"都市: {data.get('city', '不明')}\n"
        f"地域: {data.get('region', '不明')}\n"
        f"国: {data.get('country', '不明')}\n"
        f"組織: {data.get('org', '不明')}"
    )
    return {"content": [{"type": "text", "text": text}]}

def lambda_handler(event, context):
    """Gateway ツール Lambda ハンドラー。

    INPUT: ツール引数が event に直接渡される
    OUTPUT: {"content": [{"type": "text", "text": result}]} または {"error": "..."}
    """
    logger.info(f"Received event: {event}")

    try:
        # ツール名を取得（target_name___tool_name 形式）
        tool_name = ""
        if hasattr(context, "client_context") and context.client_context:
            custom = getattr(context.client_context, "custom", {}) or {}
            raw = custom.get("bedrockAgentCoreToolName", "")
            delimiter = "___"
            tool_name = raw[raw.index(delimiter) + len(delimiter) :] if delimiter in raw else raw

        logger.info(f"Processing tool: {tool_name}")

        if tool_name == "get_ip_info":
            ip = event.get("ip", "")
            if not ip:
                return {"error": "ip は必須です"}
            return _get_ip_info(ip)

        return {"error": f"未知のツール: {tool_name}"}

    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": f"内部エラー: {e}"}

3.2. 「Deploy」を押して関数を保存します。

4. 一般設定を調整する

4.1. 「設定 > 一般設定」を開き、以下のように更新します。

AgentCore Gateway を作成する

Lambda が用意できたら、Gateway 本体を作成します。

5. AgentCore Gateway のコンソールに入る

5.1. マネジメントコンソールで Amazon Bedrock AgentCore を開きます。トップ画面に AgentCore の構成要素（組み込みツール / ゲートウェイ / アイデンティティ / ポリシー / Registry ほか）が並んでいるので、ここからゲートウェイへ進みます。
左サイドメニューから「ゲートウェイ」を選びます。

5.2. 「ゲートウェイを作成」を押します。

6. Step 1: Define gateway details — ゲートウェイの詳細を入力する

6.1. ゲートウェイ名と Permissions を以下のように入力します。

「IAM アクセス許可」で「デフォルトロールを作成」を選ぶと、画面下に自動生成される Role name が表示されます（このロールは後段の Gateway Target 作成時に Lambda Invoke 権限が自動付与されます）。

6.2. 「追加設定 - オプション」を展開し、以下のように設定します。

「指示」に入れる文字列:

This gateway provides a sample MCP tool for verification purposes.

Available tools:
- `get_ip_info`: Look up geographic location and ASN information for an IPv4 or IPv6 address via ipinfo.io.

Usage guidance:
- Use `get_ip_info` when the user asks about the origin, location, or network of an IP address.
- Present results in a clear, human-readable format (location, ISP, organization).

6.3. さらに下にスクロールし、Request / Response Interceptor Lambda ARN は空のままにします。Permissions セクションで Role name が自動生成されていることを確認したら、「Next」を押します。

7. Step 2: Configure Inbound Identity — 認可方式を選ぶ

7.1. Inbound Auth type で IAM 許可を使用 を選択します。

7.2. 「Next」を押します。

8. Step 3: Add targets — Gateway Target の基本設定を入力する

8.1. ターゲットの基本設定を入力します。

9. Step 3: Add targets — ツールスキーマを入力する

ツールスキーマは、この Lambda Target が どんなツール（関数）として MCP クライアントに見えるか を宣言するための JSON です。AgentCore Gateway はここに書いた name / description / inputSchema をそのまま MCP の tools/list レスポンスに変換して返すため、AI エージェント側はこの内容を見てツールを呼び出すかどうかを判断します。

公式の Lambda function tool schema では、各ツールは以下の構造を持つ ToolDefinition の配列として定義します。

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-lambda.html

inputSchema.properties の各プロパティは型ごとに以下のように書きます（string / number / integer / boolean / array / object をサポート）。

{ "type": "string", "description": "..." }
{ "type": "integer", "description": "..." }
{ "type": "array", "description": "...", "items": { "type": "string" } }
{ "type": "object", "properties": { ... }, "required": [ ... ] }

array / object は再帰的に SchemaDefinition をネストできるので、複雑な構造のツールも表現できます。

9.1. 「ターゲットスキーマ」で インラインスキーマを定義 を選び、エディタに以下の JSON を貼り付けます。

[
  {
    "name": "get_ip_info",
    "description": "Look up geographic and ASN information for a given IP address via ipinfo.io",
    "inputSchema": {
      "type": "object",
      "properties": {
        "ip": {
          "type": "string",
          "description": "IPv4 or IPv6 address to look up"
        }
      },
      "required": ["ip"]
    }
  }
]

このスキーマは、API 上の toolSchema.inlinePayload フィールドに対応しています（マネコンの「インラインスキーマを定義」を選ぶとここに展開される）。スキーマファイルを別管理したい場合は S3 オブジェクトとして配置して S3 リソースとして定義 側を選ぶ運用も可能です。

9.2. アウトバウンド認証設定で IAM ロール を選択します。

9.3. 「Next」を押します。

10. Step 4: Review and create — 内容を確認して作成する

10.1. 確認画面でゲートウェイの詳細・Inbound identity・ターゲットの内容を確認し、「ゲートウェイを作成」を押します。

ここで 「Gateway は作成成功したが Target 作成に失敗した」 というエラーバナーが出る場合があります。Gateway execution role lacks permission to invoke Lambda function ... というメッセージが代表的です。これは Gateway デフォルトロールの IAM 権限が IAM 全体に伝播するまでのラグが原因で、後段の「トラブルシューティング」で対応方法をまとめます。

10.2. Gateway 詳細画面に遷移し、ステータスが Ready になっていることを確認します。

上記スクリーンショットでは画面上部に Target 作成失敗のバナーが残っています。今回の検証ではこのあと Target を改めて追加し直すことで Target 込みで作成成功させました。次節「Target 作成エラーが出たときの対処」で記録しておきます。

Target 作成エラーが出たときの対処

Step 4 の Review and create で Target 作成エラーが出ることがあります。原因は Gateway のデフォルトロールに自動付与された Lambda Invoke 権限が IAM 全体に伝播するまでのラグなので、少し時間を置いてから Target だけを追加し直すと正常に登録できるかと思います。

11. Gateway デフォルトロールに Lambda Invoke 権限が入っていることを確認する（任意）

待ち時間の間に念のため、Gateway デフォルトロールの中身を見ておくと安心です。

11.1. ゲートウェイ詳細画面の「IAM ロール」リンクから IAM コンソールに飛び、許可ポリシーを開きます。AmazonBedrockAgentCoreGatewayLambdaProd_xxxxxx ポリシーで対象 Lambda ARN が lambda:InvokeFunction 許可対象になっていれば OK です。

権限自体は Target 作成時に自動付与されているので、ここで何か手を入れる必要は基本ありません。
※添付のスクリーンショットのarnはマスクしています。

12. 改めて Target を追加し直す

12.1. ゲートウェイ詳細画面の「Targets」タブを開き、「Add target」（または「ターゲットを追加」）を押します。

12.2. 手順 8〜9 と同じ設定値（GetIpInfo / Lambda ARN / インラインスキーマ / IAM ロール）で Target を入力します。

12.3. 「Add target」を押します。今回はエラーなしで Target が追加され、ゲートウェイ詳細画面のバナーも消えます。

Gateway の Observability を設定する

検証フェーズでは Gateway 内部の挙動を追えるよう、CloudWatch Logs と X-Ray を有効化します。

14. ロググループを事前作成する

ログ配信先のロググループは事前に作成しておく必要があります。

14.1. CloudWatch コンソールを開きます。

14.2. 「ログ > ロググループ」を開き、「ロググループを作成」を押します。

14.3. ロググループ情報を入力します。

15. Gateway 側でログ配信を追加する

15.1. Gateway 詳細画面の「監視 / Observability」タブを開きます。最初はログ配信が未設定の状態です。

15.2. 「ログ配信を追加」を押し、配信モーダルで設定します。

15.3. 「追加」を押すと、ログ配信が1件追加された状態になります。

16. X-Ray トレースを有効化する

16.1. Tracing セクションには「Transaction Search required for trace delivery」というバナーが出ています。「Configure」を押して CloudWatch の Transaction Search 設定画面に飛びます。

16.2. CloudWatch の Transaction Search を有効化します。

16.3. Gateway 詳細画面に戻り、Tracing の「Edit」から有効化します。

「Save」を押すと、Gateway → Lambda の連結トレースが X-Ray サービスマップに描画されるようになります。

動作確認をする

AgentCore Gateway のマネコン画面には テスト用 UI（Test タブ / Playground）が用意されていない ため、Gateway の MCP エンドポイントに対して SigV4 署名付きで JSON-RPC POST をリクエストする必要があります。CloudShell から awscurl を使うのが最も手軽です。

17. CloudShell で awscurl をインストールする

17.1. Gateway と同じリージョンの CloudShell を起動します。

17.2. awscurl をインストールします。

pip install awscurl

18. Gateway URL を環境変数にセットする

18.1. マネジメントコンソールの AgentCore > ゲートウェイ > demo-gateway 詳細画面 から「ゲートウェイリソース URL」をコピーします。

18.2. CloudShell で環境変数にセットします。

export GW_URL="https://demo-gateway-XXXXXXXXXX.gateway.bedrock-agentcore.ap-northeast-1.amazonaws.com/mcp"
echo "$GW_URL"

19. tools/list でツール一覧を取得する

19.1. tools/list リクエストを送信します。

awscurl --service bedrock-agentcore --region ap-northeast-1 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  "$GW_URL"

19.2. レスポンスに GetIpInfo___get_ip_info と x_amz_bedrock_agentcore_search が含まれることを確認します。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "inputSchema": {
          "type": "object",
          "properties": { "query": { "type": "string" } },
          "required": ["query"]
        },
        "name": "x_amz_bedrock_agentcore_search",
        "description": "A special tool that returns a trimmed down list of tools given a context. Use this tool only when there are many tools available and you want to get a subset that matches the provided context."
      },
      {
        "inputSchema": {
          "type": "object",
          "properties": {
            "ip": {
              "description": "IPv4 or IPv6 address to look up",
              "type": "string"
            }
          },
          "required": ["ip"]
        },
        "name": "GetIpInfo___get_ip_info",
        "description": "Look up geographic and ASN information for a given IP address via ipinfo.io"
      }
    ]
  }
}

• x_amz_bedrock_agentcore_search は Semantic search を有効にしたことで自動追加された組み込みツール
• GetIpInfo___get_ip_info が自前で登録したツール（命名規則: <TargetName>___<ToolName>）

20. tools/call でツールを実行する

20.1. 8.8.8.8 を引数に tools/call を実行します。

awscurl --service bedrock-agentcore --region ap-northeast-1 \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"GetIpInfo___get_ip_info",
      "arguments":{"ip":"8.8.8.8"}
    }
  }' \
  "$GW_URL"

20.2. ipinfo.io からの地理情報が返ってくることを確認します。

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "IP: 8.8.8.8\nホスト名: dns.google\n都市: Mountain View\n地域: California\n国: US\n組織: AS15169 Google LLC"
      }
    ]
  }
}

21. CloudWatch Logs と X-Ray サービスマップを確認する

21.1. Lambda 側のログを確認します。

• ロググループ: /aws/lambda/demo-get-ip-info
• 確認ポイント: Received event: ... / Processing tool: get_ip_info が出力されているか

21.2. Gateway 側のログを確認します。

• ロググループ: /aws/bedrock-agentcore/gateway/demo-gateway
• 確認ポイント: method=tools/call のエントリが流れているか

21.3. X-Ray トレースを確認します。

CloudWatch コンソール左サイドメニューの「トレース」を開きます。

tools/call を打ったあとにトレースが表示されていれば成功です。クエリリファイナーの「ノード」欄に demo-gateway-xxxxxxxxxx (AWS::BedrockAgentCore::Gateway) と、Lambda から外部に出た呼び出しを表す UnknownRemoteService（= ipinfo.io）の2ノードが並びます。

21.4. トレース ID をクリックして個別トレースの中身を確認します。

クライアント → demo-gateway-xxxxxxxxxx (BedrockAgentCore.Gateway) → UnknownRemoteService のサービスマップが Trace 詳細画面の上部に表示されます。下の Spans タブには、Gateway 側のセグメントとして AgentCore.Gateway.InvokeTool と、その内訳の AgentCore.Gateway.InvokeTool.GetIpInfo___get_ip_info（ツール呼び出し本体）が並びます。

トレースの差分を見ると、たとえば Gateway 全体 1.1 秒のうち 902 ミリ秒が GetIpInfo___get_ip_info（ツール側）、残りが Gateway 側オーバーヘッド、というように内訳がわかります。遅いリクエストを引いたときに、Gateway なのか Lambda なのか外部 API なのかの切り分けがここでできるようになっています。
私は過去 Langfuse の Observability 機能について取り上げた記事を作成しましたが、考え方が近いため結構飲み込みやすかったなと感じています。

https://dev.classmethod.jp/articles/langfuse-observability-try/

トラブルシューティング

実際に検証する中で踏みやすいハマりどころをまとめておきます。

まとめ

いかがだったでしょうか？
AgentCore Gateway 自体はマネジメントコンソールから30分ぐらいで作成できました。
ただし、見たところテストUIがないため、今回のように awscurl での疎通確認を行なったり、Agentから実際に呼び出してみるという形でテストすることが大事かなと考えています。
また、Semantic search は AgentCore Gateway を作成する時のみ設定可能な点はしっかりと頭に入れておきたいですね。
今回、マネジメントコンソールから作成したことで、MCP Toolsとして登録されるLambda関数と AgentCore Gateway の繋ぎ込みのイメージが深まりました。IaCで作成する場合にどのようなAWSリソースが他に必要になってくるかも頭に入ったと思います。AgentCore Gateway が気になる、という方はぜひ試してみてください！

最後までご覧いただきありがとうございました。

参考情報

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-bedrockagentcore-gateway.html

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-bedrockagentcore-gatewaytarget.html

https://docs.aws.amazon.com/lambda/latest/dg/lambda-functions.html