Cree una AgentCore puerta de enlace mediante la API

Para crear una AgentCore puerta de enlace mediante la API, realice una CreateGatewaysolicitud con uno de los puntos finales del plano de AgentCore control.

Como mínimo, debe especificar los siguientes campos:

name— El nombre de la puerta de enlace.
roleArn— El ARN de la función de servicio de puerta de enlace. Para obtener más información, consulte Permisos de rol de servicio de AgentCore puerta de enlace.
authorizerType— El tipo de autorizador que se va a utilizar para la puerta de enlace. Depende de la autorización de entrada que haya configurado. Para obtener más información, consulta Configurar la autorización de entrada para tu puerta de enlace.

Los siguientes campos opcionales añaden metadatos a la puerta de enlace:

protocolType— El tipo de protocolo de la puerta de enlace. Si lo establece enMCP, la puerta de enlace funciona en modo de agregación y solo puede tener destinos MCP. Si omite este campo, la puerta de enlace puede tener destinos MCP y HTTP.
description— Una descripción de la puerta de enlace.
tags— Un diccionario de pares clave-valor que especifica las etiquetas que puede utilizar para etiquetar su puerta de enlace con fines de supervisión.

Los campos restantes dependen de la configuración de la puerta de enlace y de si desea activar o no las funciones personalizadas de la puerta de enlace:

clientToken— Un valor de token de cliente para garantizar que una solicitud no se complete más de una vez. Si no incluyes este token, se generará uno de forma aleatoria para ti. Si no incluyes un valor, se generará uno de forma aleatoria para ti. Para obtener más información, consulte Ensuring idempotency.
authorizerConfiguration— Si su tipo de autorizador esCUSTOM_JWT, debe incluir este campo para especificar los parámetros de autorización y autenticación de la puerta de enlace. Para obtener más información, consulte La configuración del autorizador.
kmsKeyArn— Para cifrar su puerta de enlace con una clave KMS, incluya el ARN de la clave en este campo. Para obtener más información, consulte Cifrar la AgentCore puerta de enlace con una clave KMS administrada por el cliente.
exceptionLevel— Para activar los mensajes de depuración al invocar la puerta de enlace, defina este valor en. DEBUG Para obtener más información, consulte Activar los mensajes de depuración. Para ver ejemplos de cómo crear una puerta de enlace con esta configuración, consulta Crear una puerta de enlace con mensajes de depuración.
interceptorConfigurations— Para activar el código personalizado que se ejecuta al invocar la puerta de enlace, incluye este campo. Para obtener más información, consulte Uso de interceptores con Gateway. Para ver ejemplos de cómo crear una puerta de enlace con interceptores, consulte Crear una puerta de enlace con configuraciones de interceptores.
protocolConfiguration— Para incluir personalizaciones para el protocolo de puerta de enlace, configure los ajustes en este campo. Para ver las opciones de esta configuración, consulte GatewayProtocolConfiguration.
- Un ejemplo de opción es añadir una herramienta de búsqueda de herramientas en la puerta de enlace. Para obtener más información, consulte Buscar herramientas en su AgentCore portal con una consulta en lenguaje natural. Para ver ejemplos de cómo crear una puerta de enlace con esta herramienta de búsqueda, consulte Crear una puerta de enlace con búsqueda semántica.

La configuración del autorizador

Si su tipo de autorizador esCUSTOM_JWT, también debe incluir una configuración de autorizador en el campo. authorizerConfiguration La estructura básica de la configuración del autorizador es la siguiente:


{
  "customJWTAuthorizer": {
    "discoveryUrl": "string",
    "allowedAudience": ["string"],
    "allowedClients": ["string"],
    "allowedScopes": ["string"],
    "customClaims": see below
  }
}

Debe proporcionar la URL de descubrimiento del token de autenticación. Los campos restantes definen las restricciones para las notificaciones de autenticación:

allowedAudience— Las audiencias o los servicios que pueden gestionar el JWT.
allowedClients— Los clientes a los que se les permite crear un JWT.
allowedScopes— Sus alcances limitan el conjunto de reclamaciones.
customClaims— Un conjunto de objetos que permite definir campos y valores personalizados que limitan las solicitudes que se deben autenticar. Cada objeto es un CustomClaimValidationsType objeto que contiene los siguientes campos:
- inboundTokenClaimName— El nombre del campo de notificación personalizado que se va a comprobar.
- inboundTokenClaimValueType— El tipo de datos del valor de la reclamación que se va a comprobar.
- authorizingClaimMatchValue— Define el valor con el que debe coincidir el valor de la reclamación. Contiene los siguientes campos:
  - claimMatchOperator— Define la relación que se debe buscar entre el valor de coincidencia y el valor reclamado.
  - claimMatchValue— Un objeto que contiene solo uno de los siguientes campos:
    
    matchValueString : se utiliza en las siguientes situaciones:
    
    Si inboundTokenClaimValueType es STRING y claimMatchOperator esEQUALS, especifique una cadena con la que desee que coincida el valor de la reclamación para la autenticación.
    
    Si inboundTokenClaimValueType es STRING_ARRAY y claimMatchOperator esCONTAINS, especifique la cadena que desee que contenga la matriz de valores declarados para la autenticación.
    
    matchValueArray— Si inboundTokenClaimValueType es STRING_ARRAY y claimMatchOperator esCONTAINS_ANY, especifique una matriz de valores que desee comprobar para la autenticación. Si alguno de los valores de la matriz de valores de la afirmación coincide con alguno de los valores dematchValueArray, se puede autenticar la afirmación.

Los siguientes ejemplos muestran la estructura de los CustomClaimValidationsType objetos que puede especificar:

ejemplo

Para ver ejemplos de cómo crear una puerta de enlace, amplíe la sección que corresponda a su caso de uso:

Temas

Crear una puerta de enlace: ejemplo básico (autorización JWT personalizada)

En esta sección se proporcionan ejemplos básicos de la creación de una puerta de enlace.

nota

Tenga en cuenta lo siguiente: * Los valores de la configuración de autorización corresponden al momento en que se configuró la autorización entrante. * Si elige una opción que implique especificar un ARN de rol de servicio de puerta de enlace abierto, asegúrese de especificar uno existente que haya configurado. Para obtener más información, consulte Permisos de rol de servicio de AgentCore puerta de enlace.

Seleccione uno de los siguientes métodos:

ejemplo

AgentCore CLI

La AgentCore CLI proporciona una forma sencilla de crear una puerta de enlace en una interfaz de línea de comandos.

Para crear la puerta de enlace, utilice el agentcore add gateway comando. El rol del servicio de puerta de enlace y la autorización de Amazon Cognito se configuran automáticamente durante la implementación.

Uso de argumentos predeterminados

Ejecute el siguiente comando en una terminal para crear una puerta de enlace sin autorización (la opción predeterminada). Para añadir una autorización JWT personalizada, especifique los indicadores del autorizador, tal y como se muestra en el siguiente ejemplo:
```
agentcore add gateway --name my-gateway
```
Especificar argumentos

El siguiente comando muestra cómo crear una puerta de enlace con una autorización JWT personalizada y una configuración explícita:
```
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
```
Tras la implementación, el punto final que gatewayUrl se muestra en el estado de agentcore es el punto final que se debe utilizar al invocar la puerta de enlace.

Interactive

Ejecute agentcore para abrir la TUI, luego seleccione agregar y elija Gateway:
Introduzca el nombre de la puerta de enlace:
Seleccione Custom JWT como tipo de autorizador y pulse Entrar:
Configure las opciones avanzadas:
Revise el resumen de la configuración y pulse Entrar para confirmar:

AWS CLI

Ejecute el siguiente código en una terminal para crear una puerta de enlace básica con la 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"]
    }
  }'

El que gatewayUrl aparece en la respuesta es el punto final que se debe utilizar al invocar la puerta de enlace.

AWS Python SDK (Boto3)

El siguiente código de Python muestra cómo crear una puerta de enlace básica con el SDK de AWS Python (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']}")

Crear una puerta de enlace: ejemplo básico (autorización de IAM)

En esta sección se proporcionan ejemplos básicos de cómo crear una puerta de enlace mediante la autorización de IAM. Con la autorización de IAM, no necesita una configuración de autorizador.

nota

La AgentCore CLI no admite la creación de puertas de enlace con autorización de IAM. Utilice la interfaz de línea de AWS comandos o el SDK de AWS Python (Boto3) para crear una puerta de enlace con autorización de IAM.

Seleccione uno de los siguientes métodos:

ejemplo

Crear una puerta de enlace: ejemplo básico (NONE authorizer)

En esta sección se proporcionan ejemplos básicos de cómo crear una puerta de enlace con un tipo de autorizador NONE. Esto representa una puerta de enlace que no autenticará ni autorizará ninguna solicitud entrante.

nota

* El tipo de autorizador NONE representa una puerta de enlace que no autenticará ni autorizará ninguna solicitud entrante. Consulte la autorización entrante para conocer los problemas de seguridad y los detalles sobre el uso de esta configuración. * Si elige una opción que implique especificar un ARN de rol de servicio de puerta de enlace abierto, asegúrese de especificar uno existente que haya configurado. Para obtener más información, consulte Permisos de rol de servicio de AgentCore puerta de enlace.

Seleccione uno de los siguientes métodos:

ejemplo

AgentCore CLI

La AgentCore CLI proporciona una forma sencilla de crear una puerta de enlace con el tipo de autorizador NONE en una interfaz de línea de comandos.

El siguiente comando muestra cómo crear una puerta de enlace con el tipo de autorizador NONE:
```
agentcore add gateway \
  --name my-gateway \
  --authorizer-type NONE
agentcore deploy
```
Tras la implementación, el punto final que gatewayUrl se muestra en el estado de agentcore es el punto final que se debe utilizar al invocar la puerta de enlace.

Interactive

Ejecute agentcore para abrir la TUI, luego seleccione agregar y elija Gateway:
Introduzca el nombre de la puerta de enlace:
Seleccione NINGUNO como tipo de autorizador y pulse Entrar:
Configure las opciones avanzadas:
Revise el resumen de la configuración y pulse Entrar para confirmar:

AWS CLI

Ejecute el siguiente código en una terminal para crear una puerta de enlace con el tipo de autorizador NONE mediante la AWS CLI:
```
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
```
El que gatewayUrl aparece en la respuesta es el punto final que se debe utilizar al invocar la puerta de enlace.

AWS Python SDK (Boto3)

El siguiente código de Python muestra cómo crear una puerta de enlace con el tipo de autorizador NONE mediante el SDK de AWS Python (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']}")

Crear una puerta de enlace: ejemplo básico (autorización AUTHENTICATE_ONLY)

En esta sección se proporcionan ejemplos de cómo crear una puerta de enlace con autorización. AUTHENTICATE_ONLY Con este tipo de autorizador, la puerta de enlace valida el token entrante pero no realiza una autorización completa. A continuación, la identidad o el token autenticados se transmiten al destino para su autorización posterior. Esto resulta útil cuando se quiere que la puerta de enlace compruebe que la persona que llama está autenticada y, al mismo tiempo, delegue las decisiones de autorización en el servicio de destino.

nota

El tipo de AUTHENTICATE_ONLY autorizador requiere una configuración de autorizador JWT. La puerta de enlace valida el token, pero no impone restricciones de alcance o audiencia para la autorización. Si elige una opción que implique especificar un ARN de rol de servicio de puerta de enlace abierto, asegúrese de especificar uno existente que haya configurado. Para obtener más información, consulte Permisos de rol de servicio de AgentCore puerta de enlace.

Seleccione uno de los siguientes métodos:

ejemplo

Cree una puerta de enlace con búsqueda semántica

En esta sección se proporcionan ejemplos básicos de cómo crear una puerta de enlace con una herramienta que permite buscar semánticamente las herramientas relevantes. Para obtener información sobre cómo usar esta herramienta, consulte Buscar herramientas en su AgentCore puerta de enlace con una consulta en lenguaje natural.

Seleccione uno de los métodos siguientes:

ejemplo

AgentCore CLI

De forma predeterminada, la búsqueda semántica está habilitada al crear una puerta de enlace mediante la AgentCore CLI. Para deshabilitarla, usa la --no-semantic-search marca. Para crear una puerta de enlace con la búsqueda semántica por defecto habilitada:
```
agentcore add gateway --name my-gateway
agentcore deploy
```

Interactive

Ejecute agentcore para abrir la TUI, luego seleccione agregar y elija Gateway. La búsqueda semántica está habilitada de forma predeterminada en las opciones avanzadas:
Introduzca el nombre de la puerta de enlace:
Seleccione el tipo de autorizador y pulse Entrar:
En las opciones avanzadas, compruebe que la búsqueda semántica esté habilitada (es la opción predeterminada):
Revise el resumen de la configuración y pulse Entrar para confirmar:

AWS CLI

Active la búsqueda semántica al crear una puerta de enlace en la AWS CLI especificando searchType como SEMANTIC en el --protocol-configuration objeto, como en el siguiente ejemplo:


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"
    }
  }'

El de gatewayUrl la respuesta es el punto final que se debe utilizar al invocar la puerta de enlace.

AWS Python SDK (Boto3)

Active la búsqueda semántica al crear una puerta de enlace mediante el SDK de AWS Python (Boto3) especificando searchType como SEMANTIC en el protocolConfiguration objeto, como en el siguiente ejemplo:


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']}")

Cree una puerta de enlace con mensajes de depuración

Puede crear una puerta de enlace con mensajes de depuración especificando el exceptionLevel valor como. DEBUG En esta sección se proporcionan ejemplos de cómo crear una puerta de enlace con mensajes de depuración. Para obtener más información, consulta Cómo activar los mensajes de depuración.

nota

La AgentCore CLI no está configurada exceptionLevel en de forma DEBUG predeterminada. Debe pasar la --exception-level DEBUG bandera al crear la puerta de enlace. Puede desactivar los mensajes de depuración enviando una UpdateGatewaysolicitud y omitiendo el exceptionLevel argumento.

Seleccione uno de los métodos siguientes:

ejemplo

AgentCore CLI

Cuando cree una puerta de enlace mediante la AgentCore CLI, pase la --exception-level marca para habilitar los mensajes de depuración:
```
agentcore add gateway --name my-gateway --exception-level DEBUG
agentcore deploy
```

Interactive

Ejecute agentcore para abrir la TUI, luego seleccione agregar y elija Gateway. En las opciones avanzadas, puede habilitar la depuración de los mensajes configurando el nivel de excepción en: DEBUG
Introduzca el nombre de la puerta de enlace:
Seleccione el tipo de autorizador y pulse Entrar:
En las opciones avanzadas, defina el nivel de excepción enDEBUG:
Revise el resumen de la configuración y pulse Entrar para confirmar:

AWS CLI

Ejecute el siguiente código en una terminal para crear una puerta de enlace con los mensajes de depuración activados en la 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

gatewayUrlEn la respuesta aparece el punto final que se debe utilizar al invocar la puerta de enlace.

AWS Python SDK (Boto3)

El siguiente código de Python muestra cómo crear una puerta de enlace básica con el SDK de AWS Python (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']}")

Cree una puerta de enlace con configuraciones de interceptores

En esta sección se proporcionan ejemplos de cómo crear una puerta de enlace con interceptores configurados. Los interceptores se invocarán en el tiempo de ejecución de la puerta de enlace para cada solicitud.

nota

* Los interceptores se invocarán en el tiempo de ejecución de la puerta de enlace para cada solicitud. * Si elige una opción que implique especificar un ARN de rol de servicio de puerta de enlace abierto, asegúrese de especificar uno existente que haya configurado. Para obtener más información, consulte Permisos de rol de servicio de AgentCore puerta de enlace.

Seleccione uno de los siguientes métodos:

ejemplo

AgentCore CLI

Con la AgentCore CLI, primero cree la puerta de enlace y, a continuación, configure los interceptores mediante la AWS CLI o el SDK de AWS Python (Boto3).

Cree la puerta de enlace:
```
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
```
Tras la implementación, configure los interceptores en la puerta de enlace mediante el update-gateway comando AWS CLI o el SDK de AWS Python (Boto3), como se muestra en las demás pestañas.

Interactive

Ejecute agentcore para abrir la TUI, luego seleccione agregar y elija Gateway. Después de crear la puerta de enlace, configure los interceptores mediante la AWS CLI o el SDK de AWS Python (Boto3):
Introduzca el nombre de la puerta de enlace:
Seleccione Custom JWT como tipo de autorizador y pulse Entrar:
Configure las opciones avanzadas:
Revise el resumen de la configuración y pulse Entrar para confirmar:

Una vez creada e implementada la puerta de enlace, configure los interceptores mediante el update-gateway comando AWS CLI o el SDK de AWS Python (Boto3), como se muestra en las demás pestañas.

AWS CLI

Ejecute el siguiente código en una terminal para crear una puerta de enlace con configuraciones de interceptor mediante la 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"]
  }]'

gatewayUrlEn la respuesta aparece el punto final que se debe utilizar al invocar la puerta de enlace.

AWS Python SDK (Boto3)

El siguiente código de Python muestra cómo crear una puerta de enlace con configuraciones de interceptores mediante el SDK de AWS Python (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']}")

Cree una puerta de enlace con una configuración de motor de políticas

Puede crear una puerta de enlace con una configuración de motor de políticas. Un motor de políticas es un conjunto de políticas que evalúa y autoriza las llamadas de los agentes a las herramientas. Cuando se asocia a una puerta de enlace, el motor de políticas intercepta todas las solicitudes de los agentes y determina si permite o deniega cada acción en función de las políticas definidas. La aplicación mode especifica si se deben probar las políticas (LOG_ONLY) o hacerlas cumplir (ENFORCE).

ejemplo

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Crear una puerta de enlace (CLI)

Agregue objetivos a una puerta de enlace