
Primeiros Passos com o Amazon Bedrock AgentCore Gateway
Aprenda a criar um Gateway, conectar uma função Lambda como ferramenta e permitir que um agente de IA a descubra e invoque automaticamente via protocolo MCP.
Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (11 articles)
- …
- 3Primeiros Passos com o Amazon Bedrock AgentCore Gateway This article
Introdução
Agentes de IA precisam de ferramentas para serem úteis. Um chatbot que só consegue responder com base nos seus dados de treinamento é limitado. O verdadeiro poder surge quando um agente pode chamar APIs externas, consultar bancos de dados ou acionar workflows. O desafio está em conectar agentes a esses backends de forma segura, com autenticação adequada, tradução de protocolos e descoberta de serviços.
O Amazon Bedrock AgentCore Gateway é um serviço totalmente gerenciado que fornece um ponto de entrada único e seguro para conectar agentes a ferramentas. Ele transforma APIs existentes, funções Lambda e serviços em ferramentas compatíveis com MCP (Model Context Protocol) que qualquer framework de agentes pode descobrir e utilizar. Em vez de escrever código de integração personalizado para cada ferramenta, você configura um target no Gateway e o agente interage com ele através de um protocolo padrão.
Este artigo faz parte de uma série que estou escrevendo sobre diferentes aspectos do Amazon Bedrock AgentCore. Aqui, nos concentramos em entender o que é o Gateway e como conectar uma função Lambda simples como ferramenta para o Harness. Para uma compreensão mais ampla do AgentCore e seus componentes, confira os outros artigos desta série:
O que é o AgentCore Gateway?
O AgentCore Gateway atua como uma camada de tradução e roteamento entre seus agentes e seus serviços de backend. Em vez de servir apenas como um conector de ferramentas, ele roteia e protege qualquer tráfego de agentes através de um único endpoint.
Principais Capacidades
- Tradução de protocolo — Converte requisições de agentes usando MCP em chamadas de API, invocações Lambda ou requisições HTTP. Seus backends não precisam entender MCP.
- Composição — Combina múltiplas APIs, funções e ferramentas em um único endpoint MCP. Um agente se conecta a um Gateway e descobre todas as ferramentas disponíveis.
- Segurança — Gerencia autorização OAuth e autenticação IAM para que apenas usuários e agentes válidos possam acessar ferramentas. Suporta autenticação tanto de entrada quanto de saída.
- Seleção semântica de ferramentas — Quando você tem centenas de ferramentas, o Gateway oferece descoberta inteligente através de uma ferramenta de busca integrada (
x_amz_bedrock_agentcore_search) que ajuda agentes a encontrar a ferramenta certa sem ficarem sobrecarregados.
- Conectores integrados — Integração com um clique para serviços populares como Salesforce, Slack, Jira, Asana, Zendesk e Web Search.
Tipos de Target Suportados
Um Gateway pode ter múltiplos targets, cada um representando uma ferramenta ou conjunto de ferramentas diferente:
- Funções Lambda — Conecte funções serverless como ferramentas com schemas definidos
- Especificações OpenAPI — Transforme APIs REST descritas por OpenAPI (Swagger) em ferramentas MCP
- Modelos Smithy — Use definições de modelos Smithy para expor APIs
- Servidores MCP existentes — Faça proxy de servidores MCP existentes através do Gateway
- Conectores — Integrações pré-construídas (Web Search, Salesforce, Slack, Jira, etc.)
- Targets passthrough — Para roteamento de tráfego Agent-to-Agent (A2A)
Como Funciona
O fluxo é direto:
- Você cria um Gateway (endpoint com protocolo MCP)
- Você adiciona um ou mais targets (Lambda, API, conector)
- Seu agente se conecta à URL do Gateway via MCP
- O agente descobre as ferramentas disponíveis automaticamente
- Quando o agente chama uma ferramenta, o Gateway traduz a requisição e a encaminha para o target correto
Neste artigo, vamos criar uma função Lambda simples, expô-la através do Gateway e conectá-la ao nosso Harness de concessionária de carros para que o agente possa usá-la como ferramenta.
Pré-requisitos
- Conta AWS com credenciais configuradas
- Usuário ou role IAM com permissões para criar funções Lambda e usar o Amazon Bedrock AgentCore Gateway
- Região AWS onde o AgentCore está disponível (us-east-1, us-west-2, ap-southeast-2 ou eu-central-1)
- Um Harness já criado (a partir do primeiro artigo desta série )
Step 1: Criar Roles IAM
Antes de criar a função Lambda e o Gateway, precisamos de duas roles IAM: uma para a execução da Lambda e outra para o Gateway invocar a Lambda.
1.1 Criar a Role de Execução da Lambda
1.1.1. Navegue até IAM > Roles no Console AWS
1.1.2. Clique em Create role
1.1.3. Selecione AWS service como tipo de entidade confiável, depois selecione Lambda como caso de uso. Clique em Next.
1.1.4. Pesquise e selecione a política gerenciada AWSLambdaBasicExecutionRole. Isso concede à função Lambda permissão para gravar logs no CloudWatch. Clique em Next.
1.1.5. No campo Role name, insira
AgentCoreLambdaLuckyNumber 1.1.6. Clique em Create role
1.2 Criar a Role de Execução do Gateway
1.2.1. Navegue até IAM > Roles no Console AWS
1.2.2. Clique em Create role
1.2.3. Selecione Custom trust policy e insira a seguinte política de confiança que permite ao serviço AgentCore Gateway assumir esta role:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "bedrock-agentcore.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}
1.2.4. Clique em Next
1.2.5. Pule as políticas gerenciadas (não selecione nenhuma). Clique em Next.
1.2.6. No campo Role name, insira
AgentCoreGatewayLuckyNumber 1.2.7. Clique em Create role
1.2.8. Após a criação, abra a role e clique em Add permissions > Create inline policy
1.2.9. Selecione a aba JSON e insira a seguinte política:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "GetGateway", "Effect": "Allow", "Action": [ "bedrock-agentcore:GetGateway" ], "Resource": [ "arn:aws:bedrock-agentcore:<your-region>:<your-account-id>:gateway/*" ] }, { "Sid": "LambdaInvoke", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:<your-region>:<your-account-id>:function:agentcore-lucky-number*" } ]}
Por exemplo, na conta
123456789012 em us-east-1 :{ "Version": "2012-10-17", "Statement": [ { "Sid": "GetGateway", "Effect": "Allow", "Action": [ "bedrock-agentcore:GetGateway" ], "Resource": [ "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*" ] }, { "Sid": "LambdaInvoke", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:agentcore-lucky-number*" } ]}
1.2.10. Clique em Next, nomeie a política como
GatewayLambdaAccess e clique em Create policyStep 2: Criar uma Função Lambda Simples
Vamos criar uma função Lambda mínima que gera um "número da sorte" aleatório para um cliente. Isso é intencionalmente simples para que possamos focar na mecânica do Gateway em vez da lógica da Lambda em si.
2.1 Criar a Função
2.1.1. Navegue até AWS Lambda > Functions no Console AWS
2.1.2. Clique em Create function
2.1.3. Selecione Author from scratch
2.1.4. Configure a função:
- Function name:
agentcore-lucky-number
- Runtime: Selecione a versão mais recente disponível do Python. No momento da escrita, era Python 3.14. A versão específica pode variar dependendo de quando você está seguindo este tutorial.
- Architecture: arm64
- Execution role: Selecione Use an existing role e escolha
AgentCoreLambdaLuckyNumber(criada no Step 1.1)
2.1.5. Clique em Create function
2.2 Adicionar o Código da Função
2.2.1. Na aba Code da função, substitua o código padrão pelo seguinte:
import jsonimport random
def lambda_handler(event, context): """Generate a lucky number for a customer.""" body = event.get("body", {}) if isinstance(body, str): body = json.loads(body) if body else {}
customer_name = body.get("customer_name", "valued customer") lucky_number = random.randint(1, 100)
return { "statusCode": 200, "body": json.dumps({ "message": f"Hello {customer_name}! Your lucky number today is {lucky_number}.", "lucky_number": lucky_number, "customer_name": customer_name }) }
2.2.2. Clique em Deploy
2.3 Testar a Função
2.3.1. Clique na aba Test
2.3.2. Crie um evento de teste com o seguinte payload:
{ "body": { "customer_name": "Carlos" }}
2.3.3. Clique em Test e verifique a saída:
{ "statusCode": 200, "body": "{\"message\": \"Hello Carlos! Your lucky number today is 42.\", \"lucky_number\": 42, \"customer_name\": \"Carlos\"}"}
Step 3: Criar um Gateway com um Target Lambda
O assistente de criação do Gateway tem quatro etapas que guiam você pela configuração do gateway e adição de targets em um único fluxo.
3.1 Navegar até o Console do Gateway
3.1.2. No painel de navegação à esquerda, em Build, clique em Gateways
3.1.3. Clique no botão Create Gateway

3.2 Etapa 1 — Definir Detalhes do Gateway
3.2.1. No campo Gateway name, insira
LuckyNumberGateway 3.2.2. Em Permissions, selecione Use another role e escolha a role
AgentCoreGatewayLuckyNumber criada no Step 1.2.3.2.3. Deixe todas as seções opcionais recolhidas (Additional configurations, Policy, KMS key, WAF). Clique em Next.

3.3 Etapa 2 — Configurar Identidade de Entrada
3.3.1. Em Inbound Auth type, selecione No authorization. Isso simplifica o tutorial removendo requisitos de autenticação. Para ambientes de produção, use IAM permissions ou JWT para controlar o acesso.
3.3.2. Clique em Next

3.4 Etapa 3 — Adicionar Targets
Aqui é onde você conecta sua função Lambda como ferramenta. Um target representa um serviço de backend exposto através do Gateway.
3.4.1. Clique em Add target
3.4.2. Selecione Lambda como tipo de target
3.4.3. No campo Target name, insira
LuckyNumber 3.4.4. No campo Target description, insira
Generates a lucky number for a customer 3.4.5. No campo Lambda ARN, insira:
arn:aws:lambda:<your-region>:<your-account-id>:function:agentcore-lucky-number:$LATEST
3.4.6. Para o Tool schema, selecione Inline e insira a seguinte definição JSON que descreve o que a ferramenta faz e seus parâmetros de entrada:
[ { "name": "get_lucky_number", "description": "Generates a lucky number for a customer. Use this when a customer asks for their lucky number or wants a fun random number.", "inputSchema": { "type": "object", "properties": { "customer_name": { "type": "string", "description": "The name of the customer requesting the lucky number" } }, "required": [] } }]
O campo
description é crítico. Ele informa ao modelo quando e por que usar esta ferramenta. Uma descrição bem escrita leva a uma seleção de ferramentas mais precisa pelo agente.3.4.7. Clique em Next

3.5 Etapa 4 — Revisar e Criar
3.5.1. Revise sua configuração (nome do gateway, identidade de entrada, target)
3.5.2. Clique em Create
3.5.3. Aguarde até que o status do Gateway e do target alcancem Ready
3.6 Anotar o ARN do Gateway
Após a criação, abra a página de detalhes do Gateway e anote o Gateway ARN. Você precisará dele ao conectar ao Harness.
Step 4: Acessar o Gateway Programaticamente
Você pode acessar o Gateway programaticamente usando o Strands Agents SDK. Isso é útil para testes, automação ou integração de ferramentas do Gateway em suas próprias aplicações.
Clone o repositório complementar:
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreGateway.gitcd PythonAwsBedrockAgentCoreGatewaypython3.12 -m venv .venvsource .venv/bin/activatepip install -r requirements.txt
Configure o ambiente com o ID do seu Gateway:
cp .env.example .env
Edite o
.env :AWS_REGION=us-east-1GATEWAY_ID=<your-gateway-id>
Execute o script:
python gateway_agent.py
O script se conecta ao Gateway via protocolo MCP, descobre as ferramentas disponíveis (incluindo o target
LuckyNumber que você criou no Step 3) e permite que o agente interaja com elas. Isso demonstra que qualquer cliente compatível com MCP pode consumir o mesmo endpoint do Gateway.Step 5: Conectar o Gateway ao Harness
Agora vamos anexar o Gateway ao nosso Harness de concessionária de carros para que o agente possa descobrir e usar a ferramenta de número da sorte.
5.1 Editar o Harness
5.1.1. Navegue até Amazon Bedrock AgentCore > Harness
5.1.2. Selecione o Harness
car_agent na lista5.1.3. Selecione o Harness
car_agent na lista e clique no botão Edit
5.1.4. Na seção Tools, clique em Add Gateway
5.1.5. Selecione o
LuckyNumberGateway no dropdown5.1.6. Clique em Save Harness e aguarde o status retornar para Ready
5.2 Testar com o Harness
5.2.1. Quando o Harness estiver Ready, clique no botão Test Harness
5.2.2. Insira um prompt que deve acionar a ferramenta:
Hi! My name is Maria. Can you give me a lucky number for today?
5.2.3. O agente reconhecerá que possui uma ferramenta para gerar números da sorte, irá invocá-la com o nome do cliente e apresentará o resultado de forma amigável. A interface de teste mostrará um indicador como "LuckyNumber Get Lucky Number" confirmando que a ferramenta foi utilizada.

5.2.4. Tente um prompt que NÃO deve acionar a ferramenta para verificar que o agente a utiliza seletivamente:
Do you have any SUVs under $25,000?
O agente deve responder com base no seu conhecimento geral e system prompt sem invocar a ferramenta de número da sorte. Isso confirma que o agente toma decisões inteligentes sobre quando usar cada ferramenta.
Step 6: Limpeza
Se você não planeja continuar usando os recursos criados neste tutorial, é uma boa prática removê-los da sua conta. Para detalhes de preços, consulte a página de preços do AgentCore .
Para remover os recursos:
- Remova o Gateway do Harness (edite o Harness e remova a ferramenta Gateway)
- Delete o Gateway em si
- Delete a função Lambda
- Delete as roles IAM criadas no Step 1
Conclusão
Neste artigo, você aprendeu como o Amazon Bedrock AgentCore Gateway conecta agentes a ferramentas externas através de uma interface gerenciada e segura:
- Gateway é um endpoint MCP gerenciado que transforma seus backends existentes (APIs, funções Lambda, serviços) em ferramentas que qualquer agente pode descobrir e usar.
- Targets representam backends individuais conectados a um Gateway. Você pode ter múltiplos targets (Lambda, REST API, conectores) em um único Gateway.
- O agente decide quando usar ferramentas com base na conversa. Ele não precisa ser explicitamente instruído sobre qual ferramenta chamar. A descrição no schema da ferramenta ajuda o modelo a entender quando cada ferramenta é apropriada.
- Nenhum código de integração personalizado é necessário. Você define um schema, conecta sua Lambda, e o Gateway cuida da tradução de protocolo, roteamento e autenticação.
Os principais aprendizados são:
- O Gateway fornece uma interface padrão (MCP) entre agentes e qualquer backend. O backend não precisa saber sobre MCP.
- Schemas de ferramentas são críticos. O campo de descrição informa ao modelo quando e por que usar a ferramenta. Uma descrição bem escrita leva a uma melhor seleção de ferramentas.
- O Gateway suporta muito mais do que Lambda. Em artigos futuros, exploraremos targets OpenAPI, conectores integrados (Web Search, Salesforce) e comunicação Agent-to-Agent através da mesma infraestrutura do Gateway.
Referências
Fique Conectado
Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura cloud, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos futuros e tutoriais:
- LinkedIn: https://www.linkedin.com/in/biagolini
- Medium: https://medium.com/@biagolini
- GitHub: https://github.com/biagolini
- YouTube (PT-BR): https://www.youtube.com/@BiagoliniTech
- AWS Builder Center (PT-BR): https://builder.aws.com/community/@cbiagolini
Fique ligado para mais walkthroughs práticos e soluções para desafios de infraestrutura cloud e DevOps.
Happy building on AWS! 🚀☁️
Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (11 articles)
- …
- 3Primeiros Passos com o Amazon Bedrock AgentCore Gateway This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article