API を使用して AgentCore ゲートウェイを作成する
API を使用して AgentCore ゲートウェイを作成するには、AgentCore コントロールプレーンエンドポイントのいずれかを使用して CreateGateway リクエストを行います。
最低限、次のフィールドを指定する必要があります。
以下のオプションフィールドは、ゲートウェイにメタデータを追加します。
-
protocolType – ゲートウェイのプロトコルタイプ。これを に設定するとMCP、ゲートウェイは集約モードで動作し、MCP ターゲットのみを持つことができます。このフィールドを省略すると、ゲートウェイは MCP ターゲットと HTTP ターゲットの両方を持つことができます。
-
description – ゲートウェイの説明。
-
tags – モニタリング目的でゲートウェイにラベルを付けるために使用できるタグを指定するキーと値のペアのディクショナリ。
残りのフィールドは、ゲートウェイの設定と、ゲートウェイのカスタム機能を切り替えるかどうかによって異なります。
オーソライザー設定
オーソライザータイプが の場合CUSTOM_JWT、 authorizerConfigurationフィールドにオーソライザー設定も含める必要があります。オーソライザー設定の基本構造は次のとおりです。
{
"customJWTAuthorizer": {
"discoveryUrl": "string",
"allowedAudience": ["string"],
"allowedClients": ["string"],
"allowedScopes": ["string"],
"customClaims": see below
}
}
認証トークンの検出 URL を指定する必要があります。残りのフィールドは、認証クレームの制限を定義します。
-
allowedAudience – JWT を処理できる対象者またはサービス。
-
allowedClients – JWT の作成が許可されているクライアント。
-
allowedScopes – クレームのセットを制限する の範囲。
-
customClaims – 認証されるクレームを制限するカスタムフィールドと値を定義できるオブジェクトの配列。各オブジェクトは CustomClaimValidationsType オブジェクトであり、次のフィールドが含まれます。
-
inboundTokenClaimName – チェックするカスタムクレームフィールドの名前。
-
inboundTokenClaimValueType – チェックするクレーム値のデータ型。
-
authorizingClaimMatchValue – クレーム値と一致する値を定義します。以下のフィールドが含まれています。
次の例は、指定できる CustomClaimValidationsType オブジェクトの構造を示しています。
例
- String matches string
-
-
{
"inboundTokenClaimName": "string",
"inboundTokenClaimValueType": "STRING",
"authorizingClaimMatchValue": {
"claimMatchValue": {
"matchValueString": "string"
},
"claimMatchOperator": "EQUALS"
}
}
- Array contains string
-
-
{
"inboundTokenClaimName": "string",
"inboundTokenClaimValueType": "STRING_ARRAY",
"authorizingClaimMatchValue": {
"claimMatchValue": {
"matchValueString": "string"
},
"claimMatchOperator": "CONTAINS"
}
}
- Array contains any value in array
-
-
{
"inboundTokenClaimName": "string",
"inboundTokenClaimValueType": "STRING_ARRAY",
"authorizingClaimMatchValue": {
"claimMatchValue": {
"matchValueStringList": ["string"]
},
"claimMatchOperator": "CONTAINS_ANY"
}
}
ゲートウェイの作成方法の例を確認するには、ユースケースに対応するセクションを展開します。
ゲートウェイの作成: 基本的な例 (カスタム JWT 認可)
このセクションでは、ゲートウェイを作成する基本的な例を示します。
次のいずれかの方法を選択します。
例
- AgentCore CLI
-
-
AgentCore CLI は、コマンドラインインターフェイスでゲートウェイを作成する簡単な方法を提供します。
ゲートウェイを作成するには、 agentcore add gateway コマンドを使用します。ゲートウェイサービスロールと Amazon Cognito 認可は、デプロイ中に自動的に設定されます。
デフォルトの引数の使用
ターミナルで次のコマンドを実行して、認可なしでゲートウェイを作成します (デフォルト）。カスタム JWT 認可を追加するには、次の例に示すようにオーソライザーフラグを指定します。
agentcore add gateway --name my-gateway
引数の指定
次のコマンドは、カスタム JWT 認可と明示的な設定を使用してゲートウェイを作成する方法を示しています。
agentcore add gateway \
--name my-gateway \
--authorizer-type CUSTOM_JWT \
--discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
--allowed-audience "api.example.com"
agentcore deploy
デプロイ後、エージェントコアのステータスでgatewayUrl表示される は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- Interactive
-
-
agentcore を実行して TUI を開き、追加を選択してゲートウェイ を選択します。
-
ゲートウェイ名を入力します。
-
オーソライザータイプとしてカスタム JWT を選択し、Enter を押します。
-
詳細オプションを設定します。
-
設定の概要を確認し、Enter キーを押して以下を確認します。
- AWS CLI
-
-
ターミナルで次のコードを実行して、 CLI AWS で基本的なゲートウェイを作成します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}'
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- AWS Python SDK (Boto3)
-
-
次の Python コードは、Python SDK (Boto3) AWS を使用して基本的なゲートウェイを作成する方法を示しています。
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
protocolType="MCP",
authorizerType="CUSTOM_JWT",
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
ゲートウェイの作成: 基本的な例 (IAM 認可)
このセクションでは、IAM 認可を使用してゲートウェイを作成する基本的な例を示します。IAM 認可では、オーソライザー設定は必要ありません。
AgentCore CLI は、IAM 認可によるゲートウェイの作成をサポートしていません。 AWS コマンドラインインターフェイスまたは AWS Python SDK (Boto3) を使用して、IAM 認可を持つゲートウェイを作成します。
次のいずれかの方法を選択します。
例
- AWS CLI
-
-
ターミナルで以下を実行します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/MyAgentCoreServiceRole \
--protocol-type MCP \
--authorizer-type AWS_IAM
- Boto3
-
-
import boto3
# Create the AgentCore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = agentcore_client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/MyAgentCoreServiceRole",
protocolType="MCP",
authorizerType="AWS_IAM"
)
ゲートウェイの作成: 基本的な例 (NONE オーソライザー)
このセクションでは、NONE オーソライザータイプでゲートウェイを作成する基本的な例を示します。これは、受信リクエストに対して認証または認可を実行しないゲートウェイを表します。
* NONE オーソライザータイプは、受信リクエストに対して認証または認可を実行しないゲートウェイを表します。この設定の使用に関するセキュリティ上の懸念と詳細については、「インバウンド認可」を参照してください。* 明示的なゲートウェイサービスロール ARN の指定を伴うオプションを選択する場合は、設定した既存のロールを必ず指定してください。詳細については、AgentCore Gateway サービスロールのアクセス許可」を参照してください。
次のいずれかの方法を選択します。
例
- AgentCore CLI
-
-
AgentCore CLI を使用すると、コマンドラインインターフェイスで NONE オーソライザータイプを使用してゲートウェイを簡単に作成できます。
次のコマンドは、NONE オーソライザータイプでゲートウェイを作成する方法を示しています。
agentcore add gateway \
--name my-gateway \
--authorizer-type NONE
agentcore deploy
デプロイ後、エージェントコアのステータスでgatewayUrl表示される は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- Interactive
-
-
agentcore を実行して TUI を開き、追加を選択してゲートウェイ を選択します。
-
ゲートウェイ名を入力します。
-
オーソライザータイプとして NONE を選択し、Enter を押します。
-
詳細オプションを設定します。
-
設定の概要を確認し、Enter キーを押して以下を確認します。
- AWS CLI
-
-
ターミナルで次のコードを実行して、CLI AWS を使用して NONE オーソライザータイプのゲートウェイを作成します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::111122223333:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type NONE
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- AWS Python SDK (Boto3)
-
-
次の Python コードは、Python SDK (Boto3) を使用して NONE AWS オーソライザータイプでゲートウェイを作成する方法を示しています。
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::111122223333:role/my-gateway-service-role",
protocolType="MCP",
authorizerType="NONE"
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
ゲートウェイを作成する: 基本的な例 (AUTHENTICATE_ONLY 認可)
このセクションでは、AUTHENTICATE_ONLY認可付きゲートウェイを作成する例を示します。このオーソライザータイプでは、ゲートウェイはインバウンドトークンを検証しますが、完全な認可は実行しません。認証された ID またはトークンは、ダウンストリーム認可のためにターゲットに渡されます。これは、ゲートウェイで、認可の決定をターゲットサービスに委任する際に発信者が認証されていることを確認する場合に便利です。
AUTHENTICATE_ONLY オーソライザータイプには JWT オーソライザー設定が必要です。ゲートウェイはトークンを検証しますが、承認の範囲や対象者の制限は適用しません。明示的なゲートウェイサービスロール ARN の指定を伴うオプションを選択した場合は、設定した既存のロールを必ず指定してください。詳細については、AgentCore Gateway サービスロールのアクセス許可」を参照してください。
次のいずれかの方法を選択します。
例
- AWS CLI
-
-
次のコマンドを実行して、AUTHENTICATE_ONLY認可付きのゲートウェイを作成します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::111122223333:role/my-gateway-service-role \
--authorizer-type AUTHENTICATE_ONLY \
--authorizer-configuration '{
"jwtAuthenticationConfiguration": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}'
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- AWS Python SDK (Boto3)
-
-
次の Python コードは、AUTHENTICATE_ONLY認可を使用してゲートウェイを作成する方法を示しています。
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::111122223333:role/my-gateway-service-role",
authorizerType="AUTHENTICATE_ONLY",
authorizerConfiguration={
"jwtAuthenticationConfiguration": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}
)
print(f"Gateway URL: {gateway['gatewayUrl']}")
セマンティック検索を使用してゲートウェイを作成する
このセクションでは、関連するツールを意味的に検索できるツールを使用してゲートウェイを作成する基本的な例を示します。このツールの使用方法については、「自然言語クエリを使用して AgentCore ゲートウェイでツールを検索する」を参照してください。
次のいずれかの方法を選択します。
例
- AgentCore CLI
-
-
デフォルトでは、AgentCore CLI を使用してゲートウェイを作成すると、セマンティック検索が有効になります。無効にするには、 --no-semantic-searchフラグを使用します。デフォルトのセマンティック検索を有効にしてゲートウェイを作成するには:
agentcore add gateway --name my-gateway
agentcore deploy
- Interactive
-
-
agentcore を実行して TUI を開き、追加 を選択し、ゲートウェイ を選択します。セマンティック検索は、詳細オプションでデフォルトで有効になっています。
-
ゲートウェイ名を入力します。
-
オーソライザータイプを選択し、Enter キーを押します。
-
詳細オプションで、セマンティック検索が有効になっていることを確認します (これがデフォルトです）。
-
設定の概要を確認し、Enter キーを押して以下を確認します。
- AWS CLI
-
-
次の例のように、 --protocol-configuration オブジェクトSEMANTICで を searchTypeとして指定して、CLI AWS でゲートウェイを作成するときにセマンティック検索を有効にします。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--protocol-configuration '{
"mcp": {
"searchType": "SEMANTIC"
}
}'
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- AWS Python SDK (Boto3)
-
-
次の例のように、 protocolConfiguration オブジェクトSEMANTICで を searchTypeとして指定して、Python SDK (Boto3) AWS を使用してゲートウェイを作成するときにセマンティック検索を有効にします。
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
protocolType="MCP",
authorizerType="CUSTOM_JWT",
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
protocolConfiguration={
"mcp": {
"searchType": "SEMANTIC"
}
}
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
デバッグメッセージを使用してゲートウェイを作成する
exceptionLevel 値を として指定することで、メッセージをデバッグするゲートウェイを作成できますDEBUG。このセクションでは、デバッグメッセージを使用してゲートウェイを作成する例を示します。詳細については、「メッセージのデバッグを有効にする」を参照してください。
AgentCore CLI はDEBUG、デフォルトでは exceptionLevelに設定されません。ゲートウェイの作成時に --exception-level DEBUGフラグを渡す必要があります。UpdateGateway リクエストを送信し、 exceptionLevel引数を省略することで、メッセージのデバッグをオフにできます。
次のいずれかの方法を選択します。
例
- AgentCore CLI
-
-
AgentCore CLI を使用してゲートウェイを作成するときは、 --exception-levelフラグを渡してデバッグメッセージを有効にします。
agentcore add gateway --name my-gateway --exception-level DEBUG
agentcore deploy
- Interactive
-
-
agentcore を実行して TUI を開き、追加 を選択し、ゲートウェイ を選択します。詳細オプションでは、例外レベルを DEBUG に設定することで、メッセージのデバッグを有効にできます。
-
ゲートウェイ名を入力します。
-
オーソライザータイプを選択し、Enter キーを押します。
-
詳細オプションで、例外レベルを DEBUG に設定します。
-
設定の概要を確認し、Enter キーを押して以下を確認します。
- AWS CLI
-
-
ターミナルで次のコードを実行して、CLI AWS でデバッグメッセージを有効にしたゲートウェイを作成します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--exception-level DEBUG
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- AWS Python SDK (Boto3)
-
-
次の Python コードは、Python SDK (Boto3) AWS を使用して基本的なゲートウェイを作成する方法を示しています。
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
protocolType="MCP",
authorizerType="CUSTOM_JWT",
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
exceptionLevel="DEBUG"
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
インターセプター設定を使用してゲートウェイを作成する
このセクションでは、インターセプターが設定されたゲートウェイを作成する例を示します。インターセプターは、リクエストごとにゲートウェイの実行時に呼び出されます。
次のいずれかの方法を選択します。
例
- AgentCore CLI
-
-
AgentCore CLI で、まずゲートウェイを作成し、次に AWS CLI または Python SDK (Boto3) AWS を使用してインターセプターを設定します。
ゲートウェイを作成します。
agentcore add gateway \
--name my-gateway \
--authorizer-type CUSTOM_JWT \
--discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
--allowed-audience "api.example.com"
agentcore deploy
デプロイ後、他のタブに示すように、CLI update-gateway コマンドまたは AWS Python SDK (Boto3) AWS を使用してゲートウェイでインターセプターを設定します。
- Interactive
-
-
agentcore を実行して TUI を開き、追加 を選択し、ゲートウェイ を選択します。ゲートウェイを作成したら、CLI AWS または Python SDK (Boto3) AWS を使用してインターセプターを設定します。
-
ゲートウェイ名を入力します。
-
オーソライザータイプとしてカスタム JWT を選択し、Enter を押します。
-
詳細オプションを設定します。
-
設定の概要を確認し、Enter キーを押して以下を確認します。
ゲートウェイを作成してデプロイしたら、他のタブに示すように、CLI update-gateway コマンドまたは AWS Python SDK (Boto3) AWS を使用してインターセプターを設定します。
- AWS CLI
-
-
ターミナルで次のコードを実行して、CLI AWS を使用してインターセプター設定でゲートウェイを作成します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--interceptor-configurations '[{
"interceptor": {
"lambda": {
"arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
}
},
"interceptionPoints": ["REQUEST"]
}]'
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
- AWS Python SDK (Boto3)
-
-
次の Python コードは、Python SDK (Boto3) AWS を使用してインターセプター設定でゲートウェイを作成する方法を示しています。
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
protocolType="MCP",
authorizerType="CUSTOM_JWT",
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
interceptorConfigurations=[{
"interceptor": {
"lambda": {
"arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
}
},
"interceptionPoints": ["REQUEST"]
}]
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
ポリシーエンジン設定を使用してゲートウェイを作成する
ポリシーエンジン設定を使用してゲートウェイを作成できます。ポリシーエンジンは、エージェントツール呼び出しを評価および認可するポリシーのコレクションです。ゲートウェイに関連付けられている場合、ポリシーエンジンはすべてのエージェントリクエストを傍受し、定義されたポリシーに基づいて各アクションを許可するか拒否するかを決定します。強制は、ポリシーをテストするか ()LOG_ONLY、強制するか () ENFORCE modeを指定します。
例
- AgentCore CLI
-
-
まず、プロジェクトにポリシーエンジンを追加します。次に、ポリシーエンジンを参照するゲートウェイを作成します。
agentcore add policy-engine \
--name MyPolicyEngine
agentcore add gateway \
--name MyGateway \
--authorizer-type CUSTOM_JWT \
--discovery-url https://cognito-idp.us-west-2.amazonaws.com/pool-id/.well-known/openid-configuration \
--allowed-clients clientId \
--policy-engine MyPolicyEngine \
--policy-engine-mode LOG_ONLY
agentcore deploy
ログ記録の決定だけでなくポリシーを適用するには、 --policy-engine-modeを に変更しますENFORCE。
- AWS CLI
-
-
次のコマンドを実行して、 CLI AWS を使用してポリシーエンジン設定でゲートウェイを作成します。
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/pool-id/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--policy-engine-configuration '{
"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:policy-engine/policy-id",
"mode": "LOG_ONLY"
}' \
--exception-level DEBUG
レスポンスgatewayUrlの は、ゲートウェイを呼び出すときに使用するエンドポイントです。
