使用 API 建立 AgentCore 閘道
若要使用 API 建立 AgentCore 閘道，請使用其中一個 AgentCore 控制平面端點提出 CreateGateway 請求。
您至少必須指定下列欄位：
下列選用欄位會將中繼資料新增至您的閘道：
其餘欄位取決於您的閘道組態，以及是否要切換閘道的自訂功能：
-
clientToken – 用戶端字符值，以確保請求完成不超過一次。如果您未包含此字符，則會隨機為您產生一個字符。如果您未包含值，則會隨機為您產生一個值。如需詳細資訊，請參閱確保冪等性。
-
authorizerConfiguration – 如果您的授權方類型為 CUSTOM_JWT ，您必須包含此欄位來指定閘道授權和身分驗證參數。如需詳細資訊，請參閱 授權方組態。
-
kmsKeyArn – 若要使用 KMS 金鑰加密閘道，請在此欄位中包含金鑰的 ARN。如需詳細資訊，請參閱使用客戶管理的 KMS 金鑰加密 AgentCore 閘道。
-
exceptionLevel – 若要在叫用閘道時開啟偵錯訊息，請將此值設定為 DEBUG 。如需詳細資訊，請參閱開啟偵錯訊息。如需使用此設定建立閘道的範例，請參閱使用偵錯訊息建立閘道。
-
interceptorConfigurations – 若要開啟叫用閘道時執行的自訂程式碼，請包含此欄位。如需詳細資訊，請參閱搭配閘道使用攔截器。如需使用攔截器建立閘道的範例，請參閱使用攔截器組態建立閘道。
-
protocolConfiguration – 若要包含閘道通訊協定的自訂，請在此欄位中設定 設定。如需此組態中的選項，請參閱 GatewayProtocolConfiguration。
授權方組態
如果您的授權方類型為 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 程式碼說明如何使用 AWS Python SDK (Boto3) 建立基本閘道：
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 的選項，請確定您已指定現有的閘道服務角色 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 建立具有 NONE AWS 授權方類型的閘道：
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 程式碼示範如何使用 AWS Python SDK (Boto3) 建立具有 NONE 授權方類型的閘道：
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 授權建立閘道的範例。使用此授權方類型時，閘道會驗證傳入字符，但不會執行完整授權。然後，驗證的身分或字符會傳遞到目標以進行下游授權。當您希望閘道在將授權決策委派給目標服務時，驗證發起人是否通過身分驗證時，這會很有用。
AUTHENTICATE_ONLY 授權方類型需要 JWT 授權方組態。閘道會驗證權杖，但不會強制執行授權的範圍或對象限制。如果您選擇涉及指定明顯閘道服務角色 ARN 的選項，請確定您已指定現有的閘道服務角色 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
-
-
在 CLI 中建立閘道時，透過在 --protocol-configuration 物件SEMANTIC中指定 searchType 為 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)
-
-
使用 AWS Python SDK (Boto3) 建立閘道時，請在 protocolConfiguration 物件SEMANTIC中指定 searchType 為 ，以開啟語意搜尋，如下列範例所示：
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 程式碼說明如何使用 AWS Python SDK (Boto3) 建立基本閘道：
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，首先建立閘道，然後使用 CLI 或 AWS 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 AWS update-gateway命令或 AWS Python SDK (Boto3) 在閘道上設定攔截器，如其他索引標籤所示。
- Interactive
-
-
執行 agentcore以開啟 TUI，然後選取新增，然後選擇閘道 。建立閘道之後，請使用 CLI AWS 或 AWS Python SDK (Boto3) 設定攔截器：
-
輸入閘道名稱：
-
選取自訂 JWT 做為授權方類型，然後按 Enter ：
-
設定進階選項：
-
檢閱組態摘要，然後按 Enter 鍵確認：
建立並部署閘道之後，請使用 AWS CLI update-gateway命令或 AWS Python SDK (Boto3) 設定攔截器，如其他索引標籤所示。
- 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 程式碼說明如何使用 AWS Python SDK (Boto3) 建立具有攔截器組態的閘道：
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']}")
使用政策引擎組態建立閘道
您可以使用政策引擎組態建立閘道。政策引擎是評估和授權客服人員工具呼叫的政策集合。與閘道建立關聯時，政策引擎會攔截所有代理程式請求，並根據定義的政策決定是否允許或拒絕每個動作。強制執行會mode指定要測試政策 ( ) LOG_ONLY 還是強制執行政策 ( ENFORCE )。
範例
- 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中的 是呼叫閘道時要使用的端點。
