Estágios da API REST do Amazon API Gateway como alvos

Um destino de API REST do API Gateway conecta seu gateway a um estágio da sua API REST. O gateway converte as solicitações MCP recebidas em solicitações HTTP para sua API REST e gerencia a formatação das respostas. Quando você adiciona ou atualiza um alvo do API Gateway, o AgentCore Gateway chama a API do GetExportAPI Gateway em seu nome.

Você pode especificar filtros e substituições de ferramentas em sua configuração de destino. Os filtros de ferramentas permitem que você disponibilize combinações específicas de caminhos de recursos e métodos HTTP como ferramentas em seu gateway. Esses filtros criam uma lista de permissões que expõe somente as operações que você especifica como ferramentas.

Você também pode configurar seu estágio de API REST do API Gateway como um destino de gateway a partir do console do API Gateway. Para saber mais, consulte Adicionar um estágio a um AgentCore gateway na documentação do Amazon API Gateway.

Principais considerações e limitações

Ao usar um estágio da API REST API Gateway como destino, tenha em mente os seguintes requisitos e limitações:

Configuração da ferramenta API Gateway

Ao adicionar uma API REST do API Gateway como destino do gateway, você precisa fornecer uma configuração da ferramenta do API Gateway. A configuração da ferramenta API Gateway define quais operações da sua API REST são expostas como ferramentas. Ele exige uma lista de filtros de ferramentas para selecionar as operações a serem expostas e, opcionalmente, aceita substituições de ferramentas para personalizar os metadados da ferramenta, como nomes e descrições das ferramentas.

Filtros de ferramentas

Os filtros de ferramentas permitem que você selecione operações da API REST usando combinações de caminhos e métodos. Cada filtro oferece suporte a duas estratégias de correspondência de caminhos:

Cada filtro especifica um caminho e uma lista de métodos HTTP. O filtro resolve combinações correspondentes que existem na sua API. Vários filtros podem se sobrepor e as duplicações são automaticamente desduplicadas.

Substituições de ferramentas

Por padrão, o nome da ferramenta MCP é retirado de operationId para cada combinação de caminho e método que corresponda aos seus filtros. Se não houver uma correspondência de operationId for a filter, você precisará de uma substituição de ferramenta correspondente que forneça um nome. Se o nome operationId e o nome de substituição estiverem ausentes, a criação e as atualizações do destino falharão na validação. Para obter mais informações sobre nomes de ferramentas no AgentCore Gateway, consulte Compreender como as ferramentas do AgentCore Gateway são nomeadas.

As substituições de ferramentas são opcionais. Eles permitem que você personalize o nome ou a descrição da ferramenta para operações específicas após a filtragem. Cada substituição deve especificar um caminho explícito e um único método HTTP. Curingas não são compatíveis. A substituição deve corresponder a uma operação que existe na sua API e deve corresponder a uma das operações resolvidas pelos seus filtros. Você não pode substituir operações que não foram selecionadas. Se você estiver enfrentando erros com importações de operações sem um, operationId você pode usar uma substituição de ferramenta em vez disso.

Exemplo de configurações da ferramenta API Gateway

Os exemplos de configurações da ferramenta API Gateway a seguir mostram como usar filtros e substituições. Todos os exemplos usam uma API com os seguintes caminhos e métodos:

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

Caminho curinga e lista de métodos

Configuração da ferramenta:

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

Resultado

Caminho explícito e lista de métodos

Configuração da ferramenta:

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

Resultado

Caminho explícito e lista de métodos explícitos (mais específicos)

Configuração da ferramenta:

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

Resultado

Misture e combine um caminho explícito e curinga:

Configuração da ferramenta:

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

Resultado

Filtro de ferramentas e substituição de ferramentas

Você pode fornecer um filtro de ferramentas e adicionar uma substituição. A substituição especifica um caminho de recurso na API REST, como /pets, e um método HTTP a ser exposto para o caminho especificado. A substituição deve corresponder explicitamente a um caminho existente na API REST.

Configuração da ferramenta

{
  "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

Exportação do API Gateway

Para configurar seu destino do API Gateway, o AgentCore Gateway chama a GetExportoperação do API Gateway em seu nome para obter uma exportação formatada em OpenAPI 3.0 da sua definição de API. Isso ajuda o gateway a traduzir adequadamente as solicitações MCP recebidas em solicitações HTTP e a lidar com a resposta. A seguir estão as considerações sobre quando o AgentCore Gateway chama a GetExport operação:

Atualizando o OperationID na sua API REST

Você pode atualizar sua API REST para garantir que a definição de OpenAPI retornada por GetExporttenha sido operationId definida. Essa é uma alternativa para fornecer uma substituição de ferramenta. A seguir, explicamos duas maneiras de definir operationId o.

Defina o OperationID atualizando sua definição de OpenAPI

Exporte a definição de OpenAPI do seu estágio de API implantado chamando GetExport, atualizando as operações que estão faltando operationId e reimportando sua API.

Defina o OperationId atualizando o método da sua API REST

Você pode configurar seu método API Gateway para adicionar um operationName usando o UpdateMethodcomando. Quando sua API é exportada, ela operationName se transforma em. operationId

Métodos de autorização de saída compatíveis com uma API do API Gateway

Você pode configurar seu destino do AgentCore Gateway para fazer chamadas para sua API com autenticação de saída.

AgentCore O Gateway suporta os seguintes tipos de autorização de saída para destinos do API Gateway:

Para saber mais, consulte Configurar a autorização de saída para seu gateway.

Autorização de saída do IAM

O API Gateway permite que você proteja sua API REST com o IAM. Quando a autorização do IAM está habilitada, os clientes devem usar o Signature Version 4 (SigV4 ou SigV4a) para assinar suas solicitações com credenciais. AWS

Para configurar a autorização de saída do IAM

Políticas de recursos do API Gateway

As políticas de recursos do API Gateway são documentos de política JSON que você anexa a uma API REST do API Gateway para controlar se um principal especificado pode invocar a API. Para que o AgentCore Gateway chame sua API REST com uma política de recursos, você deve fazer o seguinte:

Veja a seguir um exemplo de uma política de recursos de API que concede ao AgentCore Gateway acesso à sua 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"
        }
      }
    }
  ]
}

Autorização de saída da chave de API

Para configurar a autorização de saída com uma chave de API, você usa o serviço de AgentCore identidade para criar um provedor de credenciais e com uma chave de API que você configurou por meio do API Gateway.

Para configurar a autorização de saída da chave de API