AWS Builder Center
Primeiros Passos com o Amazon Bedrock AgentCore Gateway

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)

  1. …
  2. 3
    Primeiros Passos com o Amazon Bedrock AgentCore Gateway This article
AWS Solutions Architect

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:
  1. Você cria um Gateway (endpoint com protocolo MCP)
  1. Você adiciona um ou mais targets (Lambda, API, conector)
  1. Seu agente se conecta à URL do Gateway via MCP
  1. O agente descobre as ferramentas disponíveis automaticamente
  1. 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)

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 policy

Step 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 json
import 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
Tela do console Amazon Bedrock AgentCore exibindo o painel de navegação à esquerda com a opção Gateways selecionada e o botão Create Gateway em destaque


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.
Tela da etapa 1 do assistente de criação do Gateway mostrando o campo Gateway name preenchido com LuckyNumberGateway e a role AgentCoreGatewayLuckyNumber selecionada em Permissions


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
Tela da etapa 2 do assistente de criação do Gateway exibindo as opções de autenticação de entrada com a opção No authorization marcada


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
Tela da etapa 3 do assistente de criação do Gateway mostrando o target Lambda configurado com nome LuckyNumber, descrição, ARN da função e schema de ferramenta inline em formato JSON


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.git
cd PythonAwsBedrockAgentCoreGateway
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure o ambiente com o ID do seu Gateway:
cp .env.example .env

Edite o  .env :
AWS_REGION=us-east-1
GATEWAY_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 lista
5.1.3. Selecione o Harness  car_agent  na lista e clique no botão Edit
Tela do console Amazon Bedrock AgentCore na seção Harness exibindo a lista de Harnesses disponíveis com o Harness car_agent selecionado e o botão Edit visível

5.1.4. Na seção Tools, clique em Add Gateway
5.1.5. Selecione o  LuckyNumberGateway  no dropdown
5.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.
Interface de teste do Harness exibindo o prompt da usuária Maria solicitando um número da sorte, o indicador de invocação da ferramenta LuckyNumber Get Lucky Number e a resposta gerada pelo agente

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:
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)

  1. …
  2. 3
    Primeiros Passos com o Amazon Bedrock AgentCore Gateway This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article