授权方配置创建网关：基本示例（自定义 JWT 授权）创建网关：基本示例（IAM 授权）创建网关：基本示例（NONE 授权者）创建网关：基本示例（仅限身份验证授权）使用语义搜索创建网关使用调试消息创建网关使用拦截器配置创建网关使用策略引擎配置创建网关

使用 API 创建 AgentCore 网关

要使用 API 创建 AgentCore 网关，请向其中一个AgentCore 控制平面终端节点 CreateGateway发出请求。

您必须至少指定以下字段：

name— 网关的名称。
roleArn— 网关服务角色的 ARN。有关更多信息，请参阅AgentCore 网关服务角色权限。
authorizerType— 用于网关的授权者类型。取决于您设置的入站授权。有关更多信息，请参阅为您的网关设置入站授权。

以下可选字段将元数据添加到您的网关：

protocolType— 网关的协议类型。如果将其设置为MCP，则网关在聚合模式下运行，并且只能有 MCP 目标。如果省略此字段，则网关可以同时具有 MCP 和 HTTP 目标。
description— 网关的描述。
tags— 键值对的字典，指定可用于标记网关以进行监控的标签。

其余字段取决于您的网关配置以及您是否要切换网关的自定义功能：

clientToken— 用于确保请求不超过一次的客户端令牌值。如果您不包括此令牌，则会为您随机生成一个。如果不包含值，则会随机生成一个值。有关更多信息，请参阅确保幂等性。
authorizerConfiguration— 如果您的授权者类型为CUSTOM_JWT，则必须包含此字段以指定网关授权和身份验证参数。有关更多信息，请参阅授权方配置。
kmsKeyArn— 要使用 KMS 密钥加密网关，请在此字段中输入密钥的 ARN。有关更多信息，请参阅使用客户管理的 KMS 密钥加密 AgentCore 网关。
exceptionLevel— 要在调用网关时打开调试消息，请将此值设置为。DEBUG有关更多信息，请参阅开启调试消息。有关使用此设置创建网关的示例，请参阅使用调试消息创建网关。
interceptorConfigurations— 要开启在调用网关时运行的自定义代码，请包含此字段。有关更多信息，请参阅在 Gate way 中使用拦截器。有关使用拦截器创建网关的示例，请参阅使用拦截器配置创建网关。
protocolConfiguration— 要包括网关协议的自定义设置，请在此字段中配置设置。有关此配置中的选项，请参见GatewayProtocolConfiguration。
- 一个示例选项是在您的网关中添加工具搜索工具。有关更多信息，请参阅使用自然语言查询在 AgentCore 网关中搜索工具。有关使用此搜索工具创建网关的示例，请参阅使用语义搜索创建网关。

授权方配置

如果您的授权者类型是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— 定义要与索赔值相匹配的值。包含以下字段：
  - claimMatchOperator— 定义要在匹配值和索赔值之间寻找的关系。
  - claimMatchValue— 仅包含以下字段之一的对象：
    
    match ValueString — 用于以下情况：
    
    如果inboundTokenClaimValueType是STRING，则claimMatchOperator为EQUALS，请指定一个字符串，您希望声明值与之匹配以进行身份验证。
    
    如果 inboundTokenClaimValueType is STRING_ARRAY 和 claimMatchOperator isCONTAINS，则指定您希望声明值数组包含的字符串以进行身份验证。
    
    matchValueArray— 如果inboundTokenClaimValueType是STRING_ARRAY，则claimMatchOperator为CONTAINS_ANY，则指定要检查身份验证的值数组。如果索赔值数组中的任何值与中的任何值相匹配matchValueArray，则可以对索赔进行身份验证。

以下示例显示了您可以指定的 CustomClaimValidationsType 对象的结构：

例

要查看如何创建网关的示例，请展开与您的用例相对应的部分：

主题

创建网关：基本示例（自定义 JWT 授权）

本节提供创建网关的基本示例。

注意

请注意以下几点：* 授权配置的值来自您设置入站授权时的值。* 如果您选择的选项涉及指定公开网关服务角色 ARN，请确保指定已设置的现有网关服务角色 ARN。有关更多信息，请参阅AgentCore 网关服务角色权限。

选择以下方法之一：

例

AgentCore CLI

C AgentCore LI 提供了一种在命令行界面中创建网关的简单方法。

要创建网关，请使用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
```
部署后，agentcore gatewayUrl 显示的状态是您调用网关时要使用的终端节点。

Interactive

运行打开 agentcore TUI，然后选择添加并选择网关：
输入网关名称：
选择 “自定义 JWT” 作为授权者类型，然后按 Enter：
配置高级选项：
查看配置摘要，然后按 Enter 进行确认：

AWS CLI

在终端中运行以下代码， AWS 使用 CLI 创建基本网关：


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 代码展示了如何使用 P AWS ython 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 授权，您无需进行授权方配置。

注意

C AgentCore LI 不支持使用 IAM 授权创建网关。使用 AWS 命令行界面或 AWS Python 开发工具包 (Boto3) 创建具有 IAM 授权的网关。

选择以下方法之一：

例

创建网关：基本示例（NONE 授权者）

本节提供创建授权者类型为 NONE 的网关的基本示例。这表示网关不会对任何传入的请求进行身份验证或授权。

注意

* NONE 授权者类型表示不对任何传入请求执行身份验证或授权的网关。有关使用此配置的安全问题和详细信息，请参阅入站授权。* 如果您选择的选项涉及指定公开网关服务角色 ARN，请确保指定已设置的现有网关服务角色 ARN。有关更多信息，请参阅AgentCore 网关服务角色权限。

选择以下方法之一：

例

AgentCore CLI

AgentCore CLI 提供了一种在命令行界面中创建无授权者类型的网关的简单方法。

以下命令显示如何创建授权者类型为 NONE 的网关：
```
agentcore add gateway \
  --name my-gateway \
  --authorizer-type NONE
agentcore deploy
```
部署后，agentcore gatewayUrl 显示的状态是您调用网关时要使用的终端节点。

Interactive

运行打开 agentcore TUI，然后选择添加并选择网关：
输入网关名称：
选择 “无” 作为授权者类型，然后按 Enter：
配置高级选项：
查看配置摘要，然后按 Enter 进行确认：

AWS CLI

在终端中运行以下代码，使用 AWS CLI 创建授权方类型为 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 代码演示了如何使用 Pyt AWS hon 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::111122223333:role/my-gateway-service-role",
  protocolType="MCP",
  authorizerType="NONE"
)

print(f"MCP Endpoint: {gateway['gatewayUrl']}")

创建网关：基本示例（仅限身份验证授权）

本节提供创建具有AUTHENTICATE_ONLY授权的网关的示例。使用此授权者类型，网关会验证入站令牌，但不执行完全授权。然后将经过身份验证的身份或令牌传递给目标进行下游授权。当您希望网关在将授权决策委托给目标服务时验证调用方是否经过身份验证时，这很有用。

注意

AUTHENTICATE_ONLY授权方类型需要 JWT 授权方配置。网关会验证令牌，但不强制执行授权范围或受众限制。如果您选择的选项涉及指定公开网关服务角色 ARN，请确保指定已设置的现有网关服务角色 ARN。有关更多信息，请参阅AgentCore 网关服务角色权限。

选择以下方法之一：

例

使用语义搜索创建网关

本节提供了使用工具创建网关的基本示例，该工具允许您在语义上搜索相关工具。要了解如何使用此工具，请参阅使用自然语言查询在 AgentCore 网关中搜索工具。

选择以下方法之一：

例

AgentCore CLI

默认情况下，当您使用 AgentCore CLI 创建网关时，语义搜索处于启用状态。要将其禁用，请使用标--no-semantic-search志。要创建启用默认语义搜索的网关，请执行以下操作：
```
agentcore add gateway --name my-gateway
agentcore deploy
```

Interactive

运行打开 agentcore TUI，然后选择添加并选择网关。默认情况下，语义搜索在高级选项中处于启用状态：
输入网关名称：
选择授权者类型，然后按 E nter：
在高级选项中，验证语义搜索是否已启用（这是默认设置）：
查看配置摘要，然后按 Enter 进行确认：

AWS CLI

在 AWS CLI 中创建网关时，通过在--protocol-configuration对象中指定 a searchType s SEMANTIC 来启用语义搜索，如以下示例所示：


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中指定 a searchType s 来开启语义搜索，如以下示例所示：


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 未设置exceptionLevelDEBUG为。创建网关时必须通过--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：
输入网关名称：
选择授权者类型，然后按 E nter：
在高级选项中，将异常级别设置为DEBUG：
查看配置摘要，然后按 Enter 进行确认：

AWS CLI

在终端中运行以下代码，创建在 AWS CLI 中开启调试消息的网关：


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 代码展示了如何使用 P AWS ython 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']}")

使用拦截器配置创建网关

本节提供创建配置了拦截器的网关的示例。拦截器将在网关运行时为每个请求调用。

注意

* 拦截器将在网关运行时为每个请求调用。* 如果您选择的选项涉及指定公开网关服务角色 ARN，请确保指定已设置的现有网关服务角色 ARN。有关更多信息，请参阅AgentCore 网关服务角色权限。

选择以下方法之一：

例

AgentCore CLI

使用 AgentCore CLI，首先创建网关，然后使用 CL AWS I 或 AWS Python SDK (Boto3) 配置拦截器。

创建网关：


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

部署后，使用 AWS CLI update-gateway 命令或 AWS Python SDK (Boto3) 在网关上配置拦截器，如其他选项卡所示。

Interactive

运行打开 agentcore TUI，然后选择添加并选择网关。创建网关后，使用 AWS CLI 或 AWS Python SDK (Boto3) 配置拦截器：
输入网关名称：
选择 “自定义 JWT” 作为授权者类型，然后按 Enter：
配置高级选项：
查看配置摘要，然后按 Enter 进行确认：

创建并部署网关后，使用 AWS CLI update-gateway 命令或 AWS Python SDK (Boto3) 配置拦截器，如其他选项卡所示。

AWS CLI

在终端中运行以下代码，使用 AWS CLI 创建具有拦截器配置的网关：


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 代码展示了如何使用 Pyth AWS on 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)。

例

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

创建网关 (CLI)

向网关添加目标