agents-connect

接続

AgentCore Gateway を通じて、AgentCore エージェントが外部 API、ツール、サービスを利用できるようにし、Cedar ポリシーでアクセス可能な対象を制御します。

使用する場面

• エージェントから外部 API または MCP サーバーを呼び出したい場合
• Lambda 関数をエージェントツールとして公開したい場合
• OpenAPI 仕様をエージェントツールに変換したい場合
• エージェントが外部サービスの呼び出しに必要な認証情報を必要としている場合
• エージェントが呼び出せるツールを制限したい場合（Cedar ポリシー）
• ツール呼び出しにロールベースまたは金額ベースのアクセス制御を適用したい場合
• ゲートウェイ接続、ツール呼び出し、またはポリシー認可に失敗している場合

ツールアクセスを制御する Cedar ポリシーを追加するには、references/policy.md を読み込んでください。

入力

$ARGUMENTS は省略可能です。

/connect                    # interactive — asks what you're connecting to
/connect mcp                # MCP server setup
/connect lambda             # Lambda function as tools
/connect openapi            # OpenAPI schema as tools
/connect credential         # Add a credential for outbound auth

手順

ステップ 0：CLI のバージョンを確認する

agentcore --version を実行します。このスキルには v0.9.0 以降が必要です。バージョンが古い場合は、先に agentcore update を実行するよう開発者に伝えてください。

ステップ 1：プロジェクトを読み込む

agentcore/agentcore.json を読み、次の内容を確認します。

• プロジェクトで使用されているフレームワーク
• すでに設定されているゲートウェイとターゲット（agentCoreGateways 配列内）

プロジェクトのコンテキストがない場合： 何に接続しようとしているかを尋ね、適切なパターンで進めてください。

ステップ 2：接続先を特定する

（または $ARGUMENTS から推測して）次のように尋ねます。

「エージェントを何に接続しますか？

1. 外部 MCP サーバー（例：サードパーティのツールプロバイダー）
2. 作成した Lambda 関数
3. OpenAPI 仕様のある API
4. AWS API Gateway REST API
5. OpenAPI 仕様、MCP サーバー、または前段の Lambda がなく、追加もできない外部サービス」

オプション 1～4 では、サービスをゲートウェイターゲットとして公開します。 これがデフォルトの方法です。ゲートウェイは認証情報プロバイダーを介してアウトバウンド認証を処理するため、エージェントのコードがシークレットを参照することはありません。また、ツールは MCP 経由で検出可能になり、ポリシーエンジンはエッジで呼び出しを許可または拒否できます。サービスに適したターゲットタイプを選択してください。

オプション 5 はパス D です。認証情報を登録し、エージェントコードから API を直接呼び出します。前段にゲートウェイを置くのが現実的でない場合の代替手段です。このスキルでは、どのような場合に適切か、また適切でないかを説明します。

---

デフォルト：コードからの直接 API 呼び出しより Gateway ターゲットを優先します

パスを検討する前に、前提を明確にしましょう。「エージェントから X を呼び出したい」という要望のほとんどは、エントリーポイント内で httpx を使うのではなく、Gateway ターゲットを使うことになります。

Gateway をデフォルトにする理由：

• エッジでの認証情報の注入。 Gateway の認証情報プロバイダー（OAuth、API キー、IAM）は、アウトバウンドリクエストに認証情報を付与します。エージェントコードが呼び出すのは session.call_tool(...) だけで、シークレットには一切触れません。client = openai.OpenAI(api_key=...) のようなコードは、プロンプト、ログの一行、トレースバックのいずれかが漏れるだけで、キーが流出する可能性があります。
• 検出可能なツールカタログ。 ツールは MCP サーバーによって一覧表示され、フレームワーク（Strands、LangGraph など）が自動的にバインドします。ツールを追加するには、コードを変更するのではなく、agentcore add gateway-target を実行して再デプロイします。
• ポリシーの適用。 Cedar ポリシーでは、プリンシパル、ツール、引数値ごとにツール呼び出しを許可または拒否できます。ツール呼び出しがエージェントコード内の httpx.post(...) に埋め込まれている場合、これは不可能です。
• セマンティック検索。 カタログに 20 個以上のツールが登録されると、x_amz_bedrock_agentcore_search が各ターンで関連するツールを選択します。

エージェントコードからの直接 API 呼び出しが適切なケース：

状況	Gateway が適切でない理由	対応方法
ストリーミング／双方向プロトコル（ライブ出力を伴う SSE、WebSockets、WebRTC、ロングポーリング）	Gateway の MCP トランスポートは、まだこれらをフロントエンドできません	直接呼び出し、パス D
MCP の中継による遅延を測定でき、そのトレードオフを受け入れる遅延が重要なホットパス	ネットワークホップが増えます	直接呼び出し、パス D。判断を裏付ける測定を実施します
ベンダー独自のプロトコル／バイナリ SDK	Gateway がフロントエンドできる HTTP インターフェイスがありません	ベンダー SDK を直接使用し、シークレットを扱う場合はパス D に従います
A2A 経由で別のエージェントを呼び出す場合	A2A は HTTP を前提に設計されており、独自の認証モデルがあります	agents-build/references/multi-agent.md を参照します。Gateway ターゲットは使用しません
ランタイムがすでに IAM を持つ AWS サービス SDK（S3、DynamoDB、SQS など）	フロントエンドしても認証上の利点はなく、ホップが増えます	ランタイムの実行ロールを使って boto3 から直接呼び出します

それ以外のすべてのケースでは、Gateway ターゲットを推奨します。開発者が直接呼び出すことを希望する場合は、上記 5 つの状況のどれに該当するかを尋ねてください。どれにも該当しない場合は、Gateway ターゲットを使うよう案内してください。

トリアージの目安：

• サービスに MCP サーバーがある → パス A
• サービスが自分で管理する Lambda 関数である → パス B
• サービスに OpenAPI 仕様がある（または生成できる — FastAPI、ASP.NET、Spring などは OpenAPI を自動生成します） → パス C
• サービスがすでに API Gateway の背後にある → パス C（--type api-gateway）
• 上記のどれにも該当せず、追加もできない → パス D

---

Gateway とは何か — 何ではないのか

ターゲットタイプを選ぶ前に、正しいメンタルモデルを理解してください。Gateway に関する混乱のほとんどは、このモデルを逆に捉えることから生じます。

Gateway は、エージェントが呼び出すツールをホストします。 呼び出しの流れは次のとおりです。

Your agent  ───→  Gateway  ───→  Lambda function / OpenAPI API / MCP server / Smithy model
             (agent calls tool)

エージェントがクライアントです。Gateway はツールのカタログをフロントエンドします。各ツールは Gateway ターゲット（Lambda、OpenAPI、MCP サーバー、API Gateway、Smithy）のいずれかです。

Gateway は、エージェントへのインバウンドのリバースプロキシではありません。 エージェントを呼び出す必要があるアプリを構築する場合、そのアプリは Gateway を経由しません。呼び出しの流れは次のとおりです。

Your app  ───→  AgentCore Runtime  (direct invoke_agent_runtime call)

アプリは IAM SigV4 で呼び出しに署名するか、JWT を提示します。アプリ側のパターンについては、agents-build/references/integrate.md を参照してください。

どちらの方向が必要なのか迷ったとき

誰が誰を呼び出しているのかを確認してください。

• 「エージェントが天気データを検索する必要がある」→ エージェントがツールを呼び出しています → Gateway のターゲット（このスキルのパス A／B／C）
• 「FastAPI アプリからエージェントを呼び出す必要がある」→ アプリがエージェントを呼び出しています → 直接呼び出し（Gateway ではありません。 agents-build/references/integrate.md を使用してください）
• 「エージェントが FastAPI アプリからデータを取得する必要がある」→ エージェントがアプリをツールとして呼び出しています → アプリを OpenAPI または REST のターゲットとして公開する Gateway のターゲット（FastAPI の /openapi.json を使うパス C）

エンドポイントが bedrock-agentcore.<region>.amazonaws.com の Gateway ターゲットを設定していたり、自分のランタイムの URL を指定していたりすることに気づいたら、そこで中断してください。フローの方向が逆になっています。

ツールに適したターゲットタイプ

ツールの種類	ターゲットタイプ	備考
MCP サーバー（サードパーティ製または独自のもの）	mcp-server	MCP ツールカタログで最も一般的です
自分で作成した AWS Lambda 関数	lambda-function-arn	IAM 認証が自動的に使用されます
OpenAPI 仕様を持つ HTTP API	open-api-schema	FastAPI に組み込まれた /openapi.json が使えます
AWS API Gateway REST API	api-gateway	すでに API Gateway の背後にある API 向けです
Smithy モデルを持つ AWS サービス	smithy-model	AWS サービスとの直接統合です

ツールに OpenAPI 仕様がなく、MCP サーバーでも Lambda でもない場合は、Lambda でラップする（最も簡単です）、OpenAPI 仕様を生成する（FastAPI なら自動的に生成されます）、または API Gateway の背後に配置してください。

---

ステップ 3：認証マトリックスを確認する

これは最もよくあるエラーの原因です。 認証オプションは接続先の種類によって異なり、CLI で利用できるのは API／SDK がサポートする機能の一部だけです。

接続先	CLI --type	CLI 経由のアウトバウンド認証	API／SDK 経由で利用できる追加オプション
外部 MCP サーバー	mcp-server	none、oauth（2LO のみ）	OAuth 3LO（AUTHORIZATION_CODE）、IAM（SigV4）
Lambda 関数	lambda-function-arn	none（デフォルト。ゲートウェイロール経由で直接呼び出し）、OAuth で保護された下流サービスには oauth（2LO）	OAuth 3LO
OpenAPI 仕様	open-api-schema	oauth（2LO）、api-key（必須。none は不可）	OAuth 3LO
AWS API Gateway	api-gateway	none、api-key	IAM（GATEWAY_IAM_ROLE）
Smithy モデル	smithy-model	oauth（2LO）	IAM、OAuth 3LO

OAuth のグラントタイプは 2 種類あり、1 種類ではありません。 CLI の --outbound-auth oauth で設定できるのは、2-legged OAuth（クライアント認証情報／M2M）のみです。サービスで3-legged OAuth（AUTHORIZATION_CODE グラント、ユーザー委任アクセス）が必要な場合、CLI のフラグでは設定できません。boto3／AWS SDK を使って接続先を設定する必要があります。grantType: AUTHORIZATION_CODE と defaultReturnUrl を指定する OAuthCredentialProvider については、CreateGatewayTarget のドキュメントを参照してください。3LO は MCP、Lambda、OpenAPI、Smithy の各ターゲットに適用されます。この点は最初に明示してください。3LO が必要な開発者は、存在しない CLI フラグを試して時間を無駄にすることになります。

MCP サーバーの IAM（SigV4） は、CLI ではなく AWS SDK／API（GATEWAY_IAM_ROLE 認証情報プロバイダーと iamCredentialProvider.service を指定した CreateGatewayTarget）で設定します。MCP サーバーは、SigV4 をネイティブに検証する AWS サービスの背後でホストされている必要があります。対象となるのは、AgentCore Runtime、AgentCore Gateway、Amazon API Gateway、Lambda Function URLs です。ALB や EC2 への直接接続エンドポイントでは SigV4 は検証されません。その場合は代わりに OAuth を使用してください。（MCP サーバーのターゲット認証方式）

MCP サーバーターゲットでは、API キー認証は API レベルでサポートされていません。 CLI で利用できないだけではありません。MCP サーバーターゲットのドキュメントに記載されている、MCP ターゲットでサポートされる認証方式は「認証なし、OAuth、IAM」のみです。MCP サーバーで API キー（サードパーティの MCP プロバイダーで一般的な方式）が使われている場合は、Path D を使ってエージェントコード内で処理してください。

認証オプションは変更されることがあります。 上記のマトリックスと CLI で受け付けられるオプションが一致しない場合は、現在の CLI ヘルプ（agentcore add gateway-target --help）と AWS ドキュメントを確認してください。ターゲットの種類ごとの認証サポートは、リリースごとに変わることがあります。awsknowledge MCP サーバーが利用できる場合は、「AgentCore CreateGatewayTarget」を検索すると、現在の API パラメーターを確認できます。

ゲートウェイ認証における CLI と API の使い分け： CLI が対応しているのは、none、oauth（2LO）、api-key です。IAM（SigV4）と 3-legged OAuth には、boto3 を直接使用してください。例は以下の Path A セクションにあります。基本的な手順は、CLI でゲートウェイとターゲットを作成してデプロイし、CLI が対応していない場合は boto3 で高度な認証設定を適用することです。

コマンドを生成する前に、開発者のターゲットの種類に適用される認証オプションを伝えてください。

ゲートウェイに多くのツールがある場合は、モデルにツールを検索させます

ゲートウェイに数個を超えるツール（およそ20個以上）がある場合、毎回のターンですべてのツール定義をモデルに渡すと、トークンを無駄に消費し、精度も低下します。現在のリクエストに関連するツールだけをモデルに提示するほうが、より適切に動作します。

AgentCore Gatewayには、この用途にぴったりのセマンティック検索ツールが組み込まれています。エージェントは、自然言語のクエリを使って x_amz_bedrock_agentcore_search という単一のMCPツールを呼び出し、ゲートウェイはカタログから最も関連性の高いツールを返します。その後、エージェントは返されたツールを通常どおり呼び出します。

開発者がBedrock Knowledge Bases、ベクトルストア、またはカスタム埋め込みを使って独自のツール選択レイヤーを構築しようとしている場合は、思いとどまらせてください。ゲートウェイにはすでにこの機能があり、管理するインフラストラクチャも不要で、厳選された関連性の基準に照らして評価済みです。

使用パターン（エージェントは他のゲートウェイツールと同じ方法でこれを呼び出します）：

# Via the MCP client, as a tool call
result = await session.call_tool(
    "x_amz_bedrock_agentcore_search",
    arguments={"query": "find tools related to processing refunds"}
)
# result.content lists the most relevant tools — the agent then invokes them

この機能はすべてのターゲットタイプ（Lambda、OpenAPI、MCP、API Gateway、Smithy）で動作します。ゲートウェイごとに有効にしてください。正確なAPIの仕様とフレームワーク固有のクライアントコードについては、AgentCore ゲートウェイでツールを検索するドキュメントを参照してください。

経験則：ゲートウェイに20個を超えるツールがある場合は、セマンティック検索を有効にすることを推奨してください。カタログが小さい場合は、すべてのツールを直接渡しても問題ありません。

呼び出し元からエージェントにカスタムヘッダーを渡す

開発者が呼び出し元からカスタムHTTPヘッダー（テナントID、相関ID、A2A-Version などのプロトコル固有ヘッダー、トレースヘッダー、冪等性キー）を送信する必要がある場合、ランタイムのデフォルトでは、ほとんどのヘッダーはエージェントコードに届く前に削除されます。許可リストの設定とプレフィックスのパターンについては、agents-build/references/request-headers.md を読み込んでください。

これはエージェントへの受信呼び出しに関するものであり、ツールへの送信呼び出しに関するものではありません。ただし、開発者がよく遭遇する問題なので、ここで触れておく価値があります。

---

パスA：MCP サーバー

ゲートウェイを追加する（まだない場合）

警告

本番環境では、受信認証なしでゲートウェイをデプロイしないでください。オーソライザーのないゲートウェイは、URLを知っているすべての呼び出し元に、接続されたすべてのツール（Lambda、MCP、OpenAPI）を公開します。これは、ランタイムで --authorizer-type NONE を指定するのと実質的に同じです。 本番環境のゲートウェイでは、必ず --authorizer-type CUSTOM_JWT または AWS_IAM を使用してください。認証なしの形式（agentcore add gateway --name X）はローカルテスト専用です。

# Development (no inbound auth — for testing only)
agentcore add gateway --name MyGateway

# Production (JWT inbound auth)
agentcore add gateway \
  --name MyGateway \
  --authorizer-type CUSTOM_JWT \
  --discovery-url https://your-idp.example.com/.well-known/openid-configuration \
  --allowed-audience my-api \
  --allowed-clients my-client-id

MCP サーバーをターゲットとして追加する

# No outbound auth (public MCP server)
agentcore add gateway-target \
  --type mcp-server \
  --name WeatherTools \
  --endpoint https://mcp.example.com/mcp \
  --gateway MyGateway

# OAuth outbound auth (2-legged — client credentials / M2M)
agentcore add gateway-target \
  --type mcp-server \
  --name WeatherTools \
  --endpoint https://mcp.example.com/mcp \
  --gateway MyGateway \
  --outbound-auth oauth \
  --oauth-client-id your-client-id \
  --oauth-client-secret your-client-secret \
  --oauth-discovery-url https://auth.example.com/.well-known/openid-configuration \
  --oauth-scopes read,write

注：CLIの --outbound-auth フラグは、MCP サーバーに対して oauth（2LO／クライアント認証情報）または none をサポートしています。

• 3者間OAuth（AUTHORIZATION_CODE グラント） — ユーザー委任アクセス — はAPIでサポートされていますが、CLIからの設定方法はありません。boto3の create_gateway_target を使い、OAuthCredentialProvider.grantType = "AUTHORIZATION_CODE" と defaultReturnUrl を設定してください。Authorization Codeフローを使用してOAuthで保護されたMCPサーバーに接続するを参照してください。
• AgentCore Runtime、別のAgentCore Gateway、API Gateway、またはLambda Function URLsでホストされているMCP サーバー向けの IAM（SigV4） は、AWS SDK/APIで設定します（CLIでは設定できません）。GATEWAY_IAM_ROLE クレデンシャルプロバイダーと iamCredentialProvider.service の値を指定して、CreateGatewayTarget を使用してください。
• APIキー認証は、APIレベルでMCPサーバーのターゲットに対してサポートされていません（MCPターゲットのドキュメントに記載されている方式は、認証なし、OAuth、IAMのみです）。MCP サーバーがAPIキーを使用する場合は、エージェントコードで直接処理してください（パスDを参照）。

デプロイしてゲートウェイURLを取得する

agentcore deploy -y
agentcore fetch access --name MyGateway

デプロイ後、ゲートウェイURLは AGENTCORE_GATEWAY_<NAME>_URL として注入されます。

ゲートウェイのクライアントコードを生成する

フレームワークに依存しない MCP クライアント：

import os
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

# Injected by AgentCore after deploy. Format: AGENTCORE_GATEWAY_<UPPERCASENAME>_URL
GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_MYGATEWAY_URL")

async def get_gateway_tools():
    """Discover tools from the gateway. Returns empty list if not deployed."""
    if not GATEWAY_URL:
        return []
    async with streamablehttp_client(GATEWAY_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.list_tools()
            return result.tools

async def call_gateway_tool(tool_name: str, arguments: dict):
    """Call a specific tool through the gateway."""
    if not GATEWAY_URL:
        raise RuntimeError("Gateway not available in local dev — deploy first")
    async with streamablehttp_client(GATEWAY_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            return await session.call_tool(tool_name, arguments)

Strands の場合、ゲートウェイのツールをエージェントに直接渡します：

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from model.load import load_model  # scaffolded by `agentcore create`

app = BedrockAgentCoreApp()
GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_MYGATEWAY_URL")

@app.entrypoint
def invoke(payload, context):
    if not GATEWAY_URL:
        # Local dev — run without gateway tools
        agent = Agent(model=load_model())
        return {"response": str(agent(payload.get("prompt", "")))}

    # Deployed — discover and use gateway tools
    tools = asyncio.run(get_gateway_tools())
    agent = Agent(
        model=load_model(),
        tools=tools,
    )
    return {"response": str(agent(payload.get("prompt", "")))}

if __name__ == "__main__":
    app.run()

LangGraph の場合、ゲートウェイのツールをツールノードに追加します：

from langchain_mcp_adapters.client import MultiServerMCPClient

@app.entrypoint
def agent_invocation(payload, context):
    if not GATEWAY_URL:
        tools = []
    else:
        # Use LangChain MCP adapter to get tools as LangChain-compatible tools
        client = MultiServerMCPClient({"gateway": {"url": GATEWAY_URL, "transport": "streamable_http"}})
        tools = asyncio.run(client.get_tools())

    llm_with_tools = llm.bind_tools(tools)
    # ... rest of your LangGraph graph ...

---

パス B：ツールとしての Lambda 関数

agentcore add gateway-target \
  --type lambda-function-arn \
  --name MyTools \
  --lambda-arn arn:aws:lambda:us-east-1:123456789012:function:my-tools \
  --tool-schema-file tools.json \
  --gateway MyGateway

tools.json でツールのスキーマを定義します：

{
  "inlinePayload": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "City name"}
        },
        "required": ["city"]
      }
    }
  ]
}

認証： Lambda ターゲットでは IAM ロール認証が自動的に使用されるため、--outbound-auth フラグは不要です。ゲートウェイの実行ロールには、Lambda ARN に対する lambda:InvokeFunction が必要です。

パス A と同じ MCP クライアントコードを使って、ツールを呼び出します。

---

パス C：ツールとしての OpenAPI 仕様

# From a local file (api-key auth)
agentcore add credential --name MyAPIKey --api-key sk-...

agentcore add gateway-target \
  --type open-api-schema \
  --name MyAPI \
  --schema specs/api.json \
  --gateway MyGateway \
  --outbound-auth api-key \
  --credential-name MyAPIKey

OpenAPI ターゲットでは認証が必要です。oauth（クライアント認証情報または認可コード）か api-key のいずれかを使用します。

⚠️ セキュリティに関する注意： --api-key はシェルの履歴に残ります。より安全な方法が 2 つあります：

1. 対話型プロンプト（推奨）： --api-key を付けずに agentcore add credential --name MyAPIKey --type api-key を実行します。CLI が値の入力を求め、シェルの履歴に残ることなく、値がそのまま認証情報プロバイダー（Secrets Manager を基盤とする）に渡されます。
2. ローカル開発に限り、agentcore.json と .env.local を編集する： agentcore dev で認証情報を使う必要がある場合は、値を agentcore/.env.local（Git の追跡対象外）に記述します。このファイルはローカル開発サーバーだけが読み込み、デプロイ時にランタイムへはアップロードされません。デプロイされたランタイムは、認証情報プロバイダーから値を取得します。

環境変数を使って、デプロイされたランタイムに認証情報を渡そうとしないでください。AgentCore Runtime の環境変数はボールトで保護されていません。agentcore add credential で認証情報を一度登録し、ゲートウェイターゲットまたはコード内（パス D）で名前を指定してください。

---

パス D：エージェントコードで使用する認証情報

ゲートウェイターゲットを介さず、エージェントコードから API を直接呼び出す場合に使用します。

パス D を選ぶ前に、本当に適切な方法か確認してください

パス D は最後の手段であり、出発点ではありません。ほとんどの外部サービスでは、ゲートウェイターゲット（パス A～C）のほうが安全で、コードも少なくて済みます。パス D のコードを生成する前に、次のいずれかに該当することを確認してください。

• サービスが、ゲートウェイではフロントエンドとして扱えないストリーミング／双方向プロトコル（ライブ出力を伴う SSE、WebSockets、WebRTC）を使用している
• 測定可能なほどレイテンシーが重要なホットパスであり、チームがそのトレードオフを受け入れている
• クライアントがベンダー提供のバイナリー SDK であり、HTTP インターフェースを持たない
• AWS サービス SDK であり、ランタイムの実行ロールにすでに IAM 権限がある（この場合は SDK を直接使用します。認証情報の登録は不要です）
• 開発者が具体的な障害に直面している（例：サービスが OpenAI 形式の API を提供し、ベンダーの SDK がそれをラップしているため、SDK 呼び出しをゲートウェイターゲットとして組み直すと機能が後退する）

これらのいずれにも該当しない場合は、パス A／B／C に戻してください。

「エージェントコードから直接使う認証情報を設定する前に、代わりにこれをゲートウェイターゲットとしてフロントエンドに置けないか確認できますか？ゲートウェイはエッジで認証情報を注入するため、エージェントコードがシークレットに触れることはなく、ツールにはポリシーを適用できます。SERVICE の前段に OpenAPI 仕様、MCP サーバー、または Lambda 関数がある場合は、パス C／A／B のほうが適しています。どれが当てはまりますか？」

ゲートウェイが使えない正当な理由を開発者が確認した場合に限り、パス D の続きに進んでください。

認証情報を登録する

# API key
agentcore add credential --name OpenAI --api-key sk-...

# OAuth (machine-to-machine)
agentcore add credential \
  --name MyOAuthProvider \
  --type oauth \
  --discovery-url https://idp.example.com/.well-known/openid-configuration \
  --client-id my-client-id \
  --client-secret my-client-secret \
  --scopes read,write

⚠️ セキュリティに関する注意： --api-key と --client-secret はシェルの履歴に残ります。これらのフラグを付けずにコマンドを実行すると、対話型プロンプトが表示され、シェルの履歴に残ることなく、値がそのまま認証情報プロバイダーに渡されます。

ローカル開発に限り、同じ値を agentcore/.env.local（Git の追跡対象外）に記述すると、agentcore dev でデコレーターをローカルに解決できます。デプロイされたランタイムは .env.local を無視し、呼び出し時に認証情報プロバイダーからシークレットを取得します。シークレットをランタイム環境変数として渡すことは絶対にしないでください。

エージェントコードで認証情報を使用する

@requires_api_key または @requires_access_token デコレーターを使用してください。これらはトークンのキャッシュと更新を自動的に処理します。デコレーターは同期関数と非同期関数の両方で動作します。

from bedrock_agentcore.identity.auth import requires_api_key, requires_access_token

# Sync function — decorator injects the fetched key via keyword arg
@requires_api_key(provider_name="OpenAI")
def call_openai(prompt: str, *, api_key: str) -> str:
    import openai
    client = openai.OpenAI(api_key=api_key)
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# Async function — same decorator, async def
@requires_access_token(
    provider_name="MyOAuthProvider",
    scopes=["read", "write"],
    auth_flow="M2M",
)
async def call_my_api(data: dict, *, access_token: str) -> dict:
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/endpoint",
            headers={"Authorization": f"Bearer {access_token}"},
            json=data,
        )
        return response.json()

デコレーター自体がトークンのライフサイクルを処理するため、使用するためだけに関数を非同期にする必要はありません。パラメータはキーワード専用（*, api_key: str または *, access_token: str）で、デコレーターがそれらを注入します。

ローカル開発: agentcore dev では、認証情報は agentcore/.env.local から読み込まれます。デコレーターパターンはローカルでもデプロイ後も同じように動作します。

---

ローカル開発のギャップ

警告

ゲートウェイ URL（AGENTCORE_GATEWAY_*_URL）はデプロイ後にのみ利用可能です。 agentcore dev では、これらの環境変数は設定されません。使用する前に必ず確認してください：

GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_MYGATEWAY_URL")
if not GATEWAY_URL:
    # run without gateway tools in local dev

ローカルでゲートウェイが利用可能であると決して仮定しないでください。

---

トラブルシューティング

「mcp-server ターゲットは api-key 認証をサポートしていません」 そのとおりです。API キー認証は API レベルで MCP サーバーターゲットに対してサポートされていません（MCP ターゲット認証戦略）。選択肢：OAuth（2LO または 3LO）、IAM（AgentCore Runtime、API Gateway、または Lambda Function URL でホストされる MCP サーバー向け）、または Path D — 認証情報をエージェントコードで管理し、MCP サーバーを直接呼び出します。

「3LO / authorization-code OAuth が必要だが、--outbound-auth oauth がリターン URL を求めない」 CLI は 2LO（クライアント認証情報）のみを設定します。3-legged OAuth には boto3 が必要です — create_gateway_target を credentialProviderType: OAUTH、grantType: AUTHORIZATION_CODE、defaultReturnUrl を指定して呼び出してください。Authorization Code フローを使用した OAuth 保護された MCP サーバーへの接続を参照してください。

「api-gateway ターゲットは oauth をサポートしていません」 API Gateway ターゲットには api-key または none を使用してください。

デプロイ後にゲートウェイ URL が設定されない agentcore fetch access --name MyGateway を実行して URL を取得してください。agentcore status --type gateway を確認して、ゲートウェイがデプロイされていることを検証してください。

ツール呼び出しが認証エラーで失敗する 具体的なエラーについては agentcore logs --runtime MyAgent --since 1h --level error を確認してください。一般的な原因：OAuth トークンの期限切れ、認証情報名の誤り、IAM 権限の不足。

「既存のエージェントにゲートウェイを追加する」ワークアラウンド CLI は、ゲートウェイクライアントコードをコピーするために使い捨てのエージェントを作成することを推奨しています。このスキルはコードを直接生成します — ワークアラウンドは不要です。

MCP クライアント（Claude Desktop、claude.ai）がゲートウェイに自動接続できない AgentCore Gateway は現在、MCP OAuth 仕様のエンドポイント（RFC 8414 OAuth Authorization Server Metadata、RFC 7591 Dynamic Client Registration）を実装していません。OAuth 設定を自動検出して自身を登録することを期待する MCP クライアント — Claude Desktop や claude.ai など — は、手動で認証情報を設定しない限り接続できません。ワークアラウンドは、Cognito の client_id と client_secret を手動で取得し、MCP クライアントの詳細設定に入力することです。これはプラットフォームの制限であり、設定エラーではありません。

出力

• ゲートウェイターゲット vs 直接 API 呼び出しに関する明確な推奨事項。直接呼び出しが正当化される 5 つのケースに基づく
• ゲートウェイとターゲットをセットアップするための CLI コマンド（または Path D が適切な場合は認証情報を登録するためのコマンド）
• フレームワーク固有のゲートウェイクライアントコード
• 認証情報のセットアップ（シェル履歴への露出を回避し、ランタイム環境変数に決して保存しない）
• ローカル開発のギャップの処理