Integração entre AgentCore Gateway e API Gateway
O desafio de levar dados corporativos para contexto de requisições a modelos de linguagem grandes (LLMs) mantém organizações atentas à segurança e conformidade com políticas empresariais. Para padronizar e proteger essas interações, muitas empresas adotam o Model Context Protocol (MCP), uma especificação que define como aplicações agentic se conectam seguramente a fontes de dados e ferramentas.
Embora o MCP tenha se mostrado vantajoso para novos casos de uso, organizações enfrentam desafios ao trazer seus ecossistemas de API existentes para a era agentic. Enquanto o MCP consegue envolver APIs existentes, isso exige trabalho adicional: tradução de requisições de MCP para REST, garantia de segurança em todo o fluxo e aplicação de observabilidade necessária para ambientes de produção.
A AWS anunciou que o Amazon Bedrock AgentCore Gateway agora suporta o Amazon API Gateway como alvo, traduzindo requisições MCP para o AgentCore Gateway em chamadas REST para o API Gateway. Isso permite expor endpoints de API novos e existentes a aplicações agentic usando MCP, com segurança e observabilidade já integradas.
O que mudou: Suporte a API Gateway no AgentCore Gateway
O AgentCore Gateway agora suporta tipos de alvo existentes ampliados com API Gateway, além de funções Lambda, esquemas OpenAPI, modelos Smithy e servidores MCP. Muitos clientes AWS construíram ecossistemas extensos de APIs usando API Gateway, conectando backends em diversas aplicações. Conforme as empresas evoluem para aplicações agentic de próxima geração, a evolução natural é expor essas APIs existentes e ferramentas de backend para sistemas alimentados por inteligência artificial, permitindo integração perfeita entre infraestrutura estabelecida e agentes inteligentes modernos.
Essa integração entre AgentCore Gateway e API Gateway simplifica a conexão entre os dois serviços. Permite direcionar diretamente o API Gateway, sem necessidade de exportar APIs do API Gateway como especificação OpenAPI 3 e depois adicioná-las ao AgentCore Gateway como alvo OpenAPI. Com essa integração, um novo tipo de alvo API_GATEWAY é adicionado ao AgentCore Gateway, eliminando o processo manual de exportação e importação.
Proprietários de APIs REST podem adicionar sua API como alvo do AgentCore Gateway com poucas interações no console ou um único comando CLI, expondo sua API REST existente como ferramentas MCP através do AgentCore Gateway. Consumidores de API podem então conectar agentes de IA a essas APIs REST via Model Context Protocol (MCP) e potencializar seus fluxos de trabalho com integração de IA.
Segurança e observabilidade
A integração entre AgentCore Gateway e API Gateway oferece suporte a autorização por IAM e chave de API. Tanto AgentCore Gateway quanto API Gateway possuem integrações com Amazon CloudWatch Logs, AWS CloudTrail e AWS X-Ray para observabilidade. Desenvolvedores de agentes que usam essa nova capacidade entre AgentCore Gateway e API Gateway podem aproveitar essas ferramentas de observabilidade.
Configuração e implementação
Este tópico apresenta como configurar uma API REST existente no API Gateway como alvo para AgentCore Gateway, permitindo usar APIs REST existentes como ferramentas para aplicações agentic expostas através do AgentCore Gateway.
Pré-requisitos
Para este exemplo, você precisa de:
- Uma conta AWS com uma API REST existente no API Gateway
- Uma função ou usuário Identity and Access Management (IAM) com permissões suficientes para criar um AgentCore Gateway e configurar um alvo API Gateway
Gateways e alvos podem ser criados de múltiplas formas:
- Console de Gerenciamento AWS
- AWS SDK para Python (Boto3)
- Interface de Linha de Comando AWS (AWS CLI)
- Kit de ferramentas AgentCore starter para configuração rápida e direta
Este artigo utiliza Boto3 para configurar a integração entre AgentCore Gateway e API Gateway. Para um guia interativo, você pode usar o exemplo de Jupyter Notebook no GitHub.
Configuração de autorização de entrada e saída
Configure os pré-requisitos para autorização de entrada e saída. Autorização de entrada autentica requisições de usuários recebidas. Autorização de saída ajuda AgentCore Gateway a conectar-se seguramente a alvos de gateway, como API Gateway, em nome do usuário autenticado.
Para API Gateway como alvo, AgentCore Gateway oferece suporte aos seguintes tipos de autorização de saída:
- Sem autorização (não recomendado) — Alguns tipos de alvo oferecem a opção de contornar autorização de saída. Essa opção menos segura não é recomendada.
- Autorização baseada em IAM — Use a função de serviço do gateway para autorizar acesso ao alvo de gateway com AWS Signature Version 4 (Sig V4).
- Chave de API — Use a chave de API configurada usando AgentCore Identity para autorizar acesso ao alvo API Gateway. Chaves de API criadas usando um API Gateway mapeado com planos de uso API Gateway ajudam a monitorar e controlar o uso da API.
Criar um papel IAM
Crie uma função IAM com a política de confiança da documentação. Para autorização de saída com autorização baseada em IAM, a política deve incluir a permissão execute-api:Invoke.
Exemplo de política inline:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:{AWS_Region}:{AWS_Account_ID}:api-id/stage/METHOD_HTTP_VERB/resource-path",
"Effect": "Allow"
}
]
}Para autorização por chave de API, crie uma chave de API e associe-a ao seu plano de uso API Gateway. Depois, crie um provedor de credencial de chave de API com AgentCore Identity. Uma vez feito isso, atualize a política conforme descrito na documentação do AgentCore Gateway.
Criar um AgentCore Gateway
Ao usar o kit de ferramentas AgentCore starter, você pode criar um gateway com uma configuração de autorização padrão usando Amazon Cognito para autorização de entrada baseada em JWT.
import boto3
gateway_client = boto3.client('bedrock-agentcore-control')
auth_config = {
"customJWTAuthorizer": {
"allowedClients": [''],
"discoveryUrl":
}
}
create_response = gateway_client.create_gateway(
name='sample-ac-gateway',
roleArn='',
protocolType='MCP',
protocolConfiguration={
'mcp': {
'supportedVersions': ['2025-03-26'],
'searchType': 'SEMANTIC'
}
},
authorizerType='CUSTOM_JWT',
authorizerConfiguration=auth_config,
description='AgentCore Gateway with API Gateway target'
)
print(create_response)
gatewayID = create_response["gatewayId"]
gatewayURL = create_response["gatewayUrl"]
print(gatewayID) Isso retorna um GATEWAY_ID que você precisará para criar o alvo do gateway.
Criar um alvo do AgentCore Gateway
Para criar um alvo API Gateway, você precisa especificar o seguinte como parte da configuração de alvo:
- toolFilters — Use para determinar quais recursos da API REST serão expostos como ferramenta no gateway. Os filtros também suportam wildcards no caminho de filtro.
- toolOverrides (opcional) — Permite que usuários substituam nomes e descrições de ferramentas. Você deve especificar caminhos e métodos explícitos.
- restApiId — Use para passar a ID do API Gateway.
Abaixo estão exemplos de configurações de alvo:
Exemplo 1 — Expõe GET e POST em /pets, GET em /pets/{petId} para o gateway e substitui seus nomes e descrições de ferramentas:
{
"mcp": {
"apiGateway": {
"restApiId": "",
"stage": "",
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/pets",
"methods": ["GET","POST"]
},
{
"filterPath": "/pets/{petId}",
"methods": ["GET"]
}
],
"toolOverrides" : [
{
"name": "ListPets",
"path": "/pets",
"method": "GET",
"description":"Retrieves all the available Pets."
},
{
"name": "AddPet",
"path": "/pets",
"method": "POST",
"description":"Add a new pet to the available Pets."
},
{
"path": "/pets/{petId}",
"method": "GET",
"name": "GetPetById",
"description": "Retrieve a specific pet by its ID"
}
]
}
}
}
} Exemplo 2 — Expõe GET em /pets e também GET em /pets/{petId} ou qualquer coisa sob /pets. Como toolOverrides não está especificado, usará a descrição de recurso do API Gateway:
{
"mcp": {
"apiGateway": {
"restApiId": "",
"stage": "",
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/pets/*",
"methods": ["GET"]
}
]
}
}
}
} Configuração do provedor de credencial
Ao criar um alvo, você também precisa especificar a autorização de saída do alvo usando uma configuração de provedor de credencial. Existem três tipos de provedores de credencial:
GATEWAY_IAM_ROLE — Usa a ROLE_ARN especificada ao criar o gateway:
[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]API_KEY — Requer a criação de um provedor de credencial de chave de API com AgentCore Identity:
[
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "",
"credentialParameterName": "x-api-key",
"credentialPrefix": "abc",
"credentialLocation": "HEADER"
}
}
}
] NO_AUTH — Configure não especificando uma configuração de provedor de credencial ao criar o alvo do AgentCore Gateway. Essa opção não é recomendada.
Criar um alvo AgentCore Gateway
Agora configure sua API REST como um alvo de gateway:
import boto3
gateway_client = boto3.client('bedrock-agentcore-control')
create_gateway_target_response = gateway_client.create_gateway_target(
name='api-gateway-target',
gatewayIdentifier='',
targetConfiguration=[< sua_configuracao_de_alvo>],
credentialProviderConfigurations=[]
)
print(create_gateway_target_response)
gateway_target_id = create_gateway_target_response['targetId'] Testando o gateway
Teste o gateway com o framework Strands Agents para listar e chamar as ferramentas disponíveis do servidor MCP. Você também pode usar outros agentes compatíveis com MCP construídos com diferentes frameworks agentic.
def create_streamable_http_transport():
return streamablehttp_client(
gatewayURL,
headers={"Authorization": f"Bearer {}"}
)
client = MCPClient(create_streamable_http_transport)
with client:
tools = client.list_tools_sync()
agent = Agent(model=yourModel, tools=tools)
agent("Hi, can you list all tools available to you")
agent("List all the available pets")
agent("Tell me about the pet with petId 3")
agent("When my order will be delivered? My order id is 2") Você observará uma saída como a seguinte:
I have access to the following tools:
1. **x_amz_bedrock_agentcore_search** - A search tool that returns a trimmed down list of tools based on a provided context/query
2. **api-gateway-target-1___Add_Pet** - Add a new pet to the available Pets
3. **api-gateway-target-1___GetPetById** - Retrieve a specific pet by its ID (requires petId parameter)
4. **api-gateway-target-1___List_Pets** - Retrieves all the available Pets (optional parameters: page, type)
5. **api-gateway-target-2___GetOrderById** - Retrieve a specific order by its ID (requires orderId parameter)
I'll retrieve all the available pets for you.
Tool #1: api-gateway-target-1___List_Pets
"HTTP/1.1 200 OK"
Here are all the available pets:
1. **Pet ID 1** - Dog - $249.99
2. **Pet ID 2** - Cat - $124.99
3. **Pet ID 3** - Fish - $0.99
I'll retrieve the details for pet ID 3.
Tool #2: api-gateway-target-1___GetPetById
"HTTP/1.1 200 OK"
Here are the details for pet ID 3:
- **Pet ID**: 3
- **Type**: Fish
- **Price**: $0.99
I'll check the details of your order with ID 2 to see the delivery information.
Tool #3: api-gateway-target-2___GetOrderById
"HTTP/1.1 200 OK"
Based on your order details:
- **Order ID**: 2
- **Pet Category**: Cat
- **Price**: $124.99
- **Delivery Date**: 02-12-2025 (December 2nd, 2025)
Your cat order will be delivered on **December 2nd, 2025**.Observabilidade
Ative logs de aplicação e rastreamento para seu recurso AgentCore Gateway. Você verá logs detalhados que ajudam a monitorar e solucionar problemas do seu recurso AgentCore Gateway. Isso inclui as chamadas de ferramenta realizadas pela sua aplicação agentic, parâmetros de requisição, respostas e erros, se houver.
Exemplo de logs:
{
"resource_arn": "arn:aws:bedrock-agentcore:us-west-2::gateway/sample-ac-gateway2-mgtqozexct",
"event_timestamp": 1763621922275,
"body": {
"isError": false,
"log": "Executing tool api-gateway-target-1___GetPetById from target W8BCF5VEAZ",
"id": "3"
},
"account_id": "",
"request_id": "8a70f423-79ee-4168-9d68-b76ad3*****",
"trace_id": "324a2ecc08631a55a02bb8f74104****",
"span_id": "f58914982450ad9b",
"timestamp": "1763621922275",
"gateway_id": "sample-ac-gateway2-mgtqozexct"
}
{
"resource_arn": "arn:aws:bedrock-agentcore:us-west-2::gateway/sample-ac-gateway2-mgtqozexct",
"event_timestamp": 1763621922348,
"body": {
"isError": false,
"responseBody": "{jsonrpc=2.0, id=3, result={isError=false, content=[{type=text, text={\"id\":3,\"type\":\"fish\",\"price\":0.99}}]}}",
"log": "Successfully processed request",
"id": "3"
},
"account_id": "",
"request_id": "8a70f423-79ee-4168-9d68-b76ad3ef****",
"trace_id": "324a2ecc08631a55a02bb8f7410****",
"span_id": "f58914982450ad9b",
"timestamp": "1763621922348",
"gateway_id": "sample-ac-gateway2-mgtqozexct"
} O AgentCore Gateway oferece métricas detalhadas do CloudWatch incluindo métricas de uso (TargetType, IngressAuthType, EgressAuthType, RequestsPerSession), métricas de invocação (Invocations, ConcurrentExecutions, Sessions), métricas de desempenho (Latency, Duration, TargetExecutionTime) e taxas de erro (Throttles, SystemErrors, UserErrors).
O AgentCore Gateway também suporta AWS X-Ray e spans conformes a OTEL que clientes podem usar para rastrear invocações em diferentes primitivas sendo utilizadas. Para saber mais, consulte a documentação de observabilidade do AgentCore Gateway.
Limpeza de recursos
Para evitar cobranças recorrentes, certifique-se de deletar os recursos criados executando o código a seguir:
import boto3
gateway_client = boto3.client('bedrock-agentcore-control')
response = gateway_client.delete_gateway_target(
gatewayIdentifier='',
targetId='')
print(response)
response = gateway_client.delete_gateway(
gatewayIdentifier='')
print(response) Próximos passos
O AgentCore Gateway agora oferece suporte ao Amazon API Gateway como alvo, expondo APIs REST como endpoints compatíveis com MCP. Você pode trazer sua infraestrutura de API existente para casos de uso agentic enquanto utiliza suas ferramentas de segurança e observabilidade atuais.
Visite a documentação do desenvolvedor e workshop para saber mais e começar hoje mesmo.
Fonte
Streamline AI agent tool interactions: Connect API Gateway to AgentCore Gateway with MCP (https://aws.amazon.com/blogs/machine-learning/streamline-ai-agent-tool-interactions-connect-api-gateway-to-agentcore-gateway-with-mcp/)
Leave a Reply