Las etapas de la API REST de Amazon API Gateway como objetivos

Un objetivo de API REST de API Gateway conecta tu puerta de enlace a una etapa de tu API REST. La puerta de enlace traduce las solicitudes MCP entrantes en solicitudes HTTP a tu API REST y gestiona el formato de las respuestas. Cuando agregas o actualizas un objetivo de API Gateway, AgentCore Gateway llama a la API de GetExportAPI Gateway en tu nombre.

Puedes especificar filtros y sustituciones de herramientas en tu configuración de destino. Los filtros de herramientas le permiten hacer que combinaciones específicas de rutas de recursos y métodos HTTP estén disponibles como herramientas en su puerta de enlace. Estos filtros crean una lista de permitidos que expone solo las operaciones que especifique como herramientas.

También puede configurar la etapa de API REST de API Gateway como destino de puerta de enlace desde la consola de API Gateway. Para obtener más información, consulte Añadir una etapa a una AgentCore puerta de enlace en la documentación de Amazon API Gateway.

Consideraciones y limitaciones clave

Cuando utilices una etapa de API REST de API Gateway como destino, ten en cuenta los siguientes requisitos y limitaciones:

Configuración de la herramienta API Gateway

Cuando agregas una API REST de API Gateway como destino de puerta de enlace, debes proporcionar una configuración de la herramienta API Gateway. La configuración de la herramienta API Gateway define qué operaciones de su API REST se exponen como herramientas. Requiere una lista de filtros de herramientas para seleccionar las operaciones que se van a exponer y, de forma opcional, acepta sustituciones de herramientas para personalizar los metadatos de las herramientas, como los nombres y las descripciones de las herramientas.

Filtros de herramientas

Los filtros de herramientas le permiten seleccionar las operaciones de la API REST mediante combinaciones de rutas y métodos. Cada filtro admite dos estrategias de coincidencia de rutas:

Cada filtro especifica una ruta y una lista de métodos HTTP. El filtro se resuelve en combinaciones coincidentes que existen en tu API. Se pueden superponer varios filtros y los duplicados se deduplican automáticamente.

Anulación de herramientas

De forma predeterminada, el nombre de la herramienta MCP se toma de la combinación operationId de ruta y método que coincida con los filtros. Si no hay ningún filtro que coincida, necesitará una herramienta de reemplazo correspondiente que proporcione un nombre. operationId Si faltan tanto el operationId nombre como el nombre de anulación, la creación y las actualizaciones del destino no se validarán. Para obtener más información sobre los nombres de las herramientas en AgentCore Gateway, consulte Cómo se nombran las herramientas de AgentCore Gateway.

Las anulaciones de herramientas son opcionales. Permiten personalizar el nombre o la descripción de la herramienta para operaciones específicas después del filtrado. Cada anulación debe especificar una ruta explícita y un único método HTTP. No se admite el uso de comodines. La anulación debe coincidir con una operación que exista en tu API y debe corresponder a una de las operaciones resueltas por tus filtros. No puedes anular las operaciones que no se seleccionaron. Si se producen errores al importar debido a operaciones sin una, operationId puede utilizar una herramienta de anulación en su lugar.

Ejemplos de configuraciones de la herramienta API Gateway

En el siguiente ejemplo de configuraciones de la herramienta API Gateway, se muestra cómo usar filtros y anulaciones. Todos los ejemplos utilizan una API con las siguientes rutas y métodos:

/pets/{petId} - GET
/pets/{petId}  - POST
/pets/{petId}  - OPTIONS
/pets          - GET
/pets          - OPTIONS
/              - GET

Ruta comodín y lista de métodos

Configuración de la herramienta:

{
  "filterPath": "/pets/*",
  "methods": ["GET", "POST"]
}

Resultado

Ruta explícita y lista de métodos

Configuración de la herramienta:

{
  "filterPath": "/pets/{petId}",
  "methods": ["GET", "POST"]
}

Resultado

Ruta explícita y lista de métodos explícitos (los más específicos)

Configuración de la herramienta:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["POST"]
    },
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    }
  ]
}

Resultado

Mezcle y combine una ruta explícita y una ruta comodín:

Configuración de la herramienta:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    },
    {
        "filterPath": "/*",
        "methods": ["GET"]
    }
  ]
}

Resultado

Filtro de herramientas y anulación de herramientas

Puede proporcionar un filtro de herramientas y añadir una modificación. La anulación especifica una ruta de recursos en la API REST, como /pets, y un método HTTP que se debe exponer para la ruta especificada. La anulación debe coincidir de forma explícita con una ruta existente en la API REST.

Configuración de la herramienta

{
  "toolFilters": [
    {
      "filterPath": "/pets/*",
      "methods": ["GET", "POST"]
    },
    {
      "filterPath": "/",
      "methods": ["GET"]
    }
  ],
  "toolOverrides": [
    {
      "path": "/pets/{petId}",
      "method": "GET",
      "name": "GetPetById",
      "description": "Retrieve a specific pet by its ID"
    }
  ]
}

Resultado

Exportación de API Gateway

Para configurar su objetivo de API Gateway, AgentCore Gateway llama a la GetExportoperación API Gateway en su nombre para obtener una exportación con formato OpenAPI 3.0 de su definición de API. Esto ayuda a la puerta de enlace a convertir correctamente las solicitudes MCP entrantes en solicitudes HTTP y a gestionar la respuesta. Las siguientes son consideraciones para cuando AgentCore Gateway llama a la GetExport operación:

Actualización de OperationID en tu API REST

Puedes actualizar tu API REST para asegurarte de que se GetExporthaya operationId establecido la definición de OpenAPI devuelta por. Esta es una alternativa a proporcionar una herramienta de anulación. A continuación se explican dos formas de configurar eloperationId.

Configura el OperationID actualizando tu definición de OpenAPI

Exporte la definición de OpenAPI desde la fase de API implementada llamando GetExport, actualizando las operaciones que faltan operationId y volviendo a importar su API.

Configura el OperationID actualizando el método de tu API REST

Puede configurar su método API Gateway para añadir un operationName mediante el UpdateMethodcomando. Cuando se exporta tu API, se operationName convierte enoperationId.

Métodos de autorización de salida compatibles para una API API Gateway

Puedes configurar tu destino de AgentCore Gateway para realizar llamadas a tu API con autenticación saliente.

AgentCore Gateway admite los siguientes tipos de autorización de salida para los destinos de API Gateway:

Para obtener más información, consulta Configurar la autorización de salida para tu puerta de enlace.

Autorización saliente de IAM

API Gateway le permite proteger su API REST con IAM. Cuando la autorización de IAM está habilitada, los clientes deben usar la versión 4 de Signature (SigV4 o SigV4a) para firmar sus solicitudes con credenciales. AWS

Para configurar la autorización saliente de IAM

Políticas de recursos de API Gateway

Las políticas de recursos de API Gateway son documentos de política de JSON que se adjuntan a una API REST de API Gateway para controlar si un principal específico puede invocar la API. Para que AgentCore Gateway llame a tu API REST con una política de recursos, debes hacer lo siguiente:

El siguiente es un ejemplo de una política de recursos de API que otorga a AgentCore Gateway acceso a su API REST.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-west-2:111122223333:abcd123/*/*/*",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
        }
      }
    }
  ]
}

Autorización de salida por clave de API

Para configurar la autorización de salida con una clave de API, utilice el servicio de AgentCore identidad para crear un proveedor de credenciales y con una clave de API que haya configurado a través de API Gateway.

Para configurar la autorización de salida mediante clave de API