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

使用 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— 要开启在调用网关时运行的自定义代码，请添加此字段。有关更多信息，请参阅在网关中使用拦截器。有关使用拦截器创建网关的示例，请参阅使用拦截器配置创建网关。
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是STRING_ARRAY，则claimMatchOperator指定一个字符串CONTAINS，您希望声明值数组包含该字符串以进行身份验证。
    
    matchValueArray— 如果inboundTokenClaimValueTypeclaimMatchOperator是 STRING_ARRAYCONTAINS_ANY，则指定要检查身份验证的值数组。如果声明值数组中的任何值与中的任何值相匹配matchValueArray，则可以对该声明进行身份验证。

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

例

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

主题

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

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

注意

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

选择以下方法之一：

例

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

Interactive

运行打开 agentcore TUI，然后选择添加并选择网关：
输入网关名称：
选择 “自定义 JWT” 作为授权者类型，然后按 En ter：
配置高级选项：
查看配置摘要并按 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 代码显示了如何使用 Py AWS thon 软件开发工具包 (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 软件开发工具包 (Boto3) 创建具有 IAM 授权的网关。

选择以下方法之一：

例

创建网关：基本示例（无授权方）

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

注意

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

选择以下方法之一：

例

AgentCore CLI

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

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

Interactive

运行打开 agentcore TUI，然后选择添加并选择网关：
输入网关名称：
选择 “无” 作为授权者类型，然后按 En ter：
配置高级选项：
查看配置摘要并按 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 代码显示了如何使用 Py AWS thon 软件开发工具包 (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授权创建网关的示例。使用这种授权方类型，网关会验证入站令牌，但不执行完全授权。然后将经过身份验证的身份或令牌传递给目标以进行下游授权。当您希望网关在将授权决策委托给目标服务时验证调用方是否经过身份验证时，这很有用。

注意

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

选择以下方法之一：

例

使用语义搜索创建网关

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

选择以下方法之一：

例

AgentCore CLI

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

Interactive

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

AWS CLI

在 AWS CLI 中创建网关时，通过在--protocol-configuration对象中指定 searchType as 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中指定 searchType as 来开启语义搜索，如以下示例所示：


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。本节提供使用调试消息创建网关的示例。要了解更多信息，请参阅开启调试消息。

注意

默认情况下，C AgentCore LI 未设置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：
输入网关名称：
选择授权者类型并按 En ter：
在高级选项中，将异常级别设置为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 代码显示了如何使用 Py AWS thon 软件开发工具包 (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']}")

使用拦截器配置创建网关

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

注意

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

选择以下方法之一：

例

AgentCore CLI

使用 AgentCore CLI，首先创建网关，然后使用 CL AWS I 或 AWS Python 软件开发工具包 (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 软件开发工具包 (Boto3) 配置拦截器：
输入网关名称：
选择自定义 JWT 作为授权者类型，然后按 En ter：
配置高级选项：
查看配置摘要并按 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 代码显示了如何使用 Py AWS thon 软件开发工具包 (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)

向网关添加目标