Assistente de pedidos multimodal no WhatsApp com Amazon Bedrock AgentCore

Um assistente de pedidos direto no WhatsApp

A AWS publicou um guia técnico detalhado mostrando como implantar um assistente de pedidos multimodal no WhatsApp usando o Amazon Bedrock AgentCore e o Amazon Nova 2. A proposta resolve um problema real de redes de restaurantes e estabelecimentos de atendimento rápido: cada canal de pedido — app, site, telefone, balcão — é um sistema separado, com histórico fragmentado. O cliente parece um estranho em cada canal.

A solução apresentada pela AWS concentra tudo em um único número do WhatsApp Business. O cliente pode enviar mensagens de texto, mandar um áudio ou fazer uma ligação — tudo a partir da mesma conversa, sem instalar nada ou criar login. Os três canais compartilham o mesmo backend e a mesma memória entre canais. Quem fizer um pedido por texto hoje e ligar amanhã é reconhecido como a mesma pessoa.

Visão geral da arquitetura

O design separa três responsabilidades: a camada do WhatsApp gerencia a conversa, três runtimes de agentes processam cada canal, e o backend cuida do cardápio, carrinhos, pedidos e localização. O tráfego de entrada chega em um único webhook HTTPS, é confirmado imediatamente com um status 200 e depois processado de forma assíncrona — nenhuma requisição bloqueia a resposta.

A porta de entrada do cliente é a Meta WhatsApp Business Platform, que expõe o webhook da Cloud API, a Messages API, a Media API e a Calling API. Toda a infraestrutura AWS é provisionada pelo AWS Kit de Desenvolvimento em Nuvem (AWS CDK).

Os principais serviços AWS utilizados na solução são:

• Amazon API Gateway: duas APIs REST — um webhook HTTPS público e uma API de backend autorizada por Gerenciamento de Identidade e Acesso (IAM).
• AWS Lambda: executa a ingestão do webhook, o worker, o remetente de mensagens e a lógica de negócio dos pedidos.
• Amazon Serviço de Filas Simples (Amazon SQS): fila de entrada com fila de mensagens mortas (DLQ) para desacoplar o reconhecimento rápido do restante do processamento.
• AgentCore runtime: hospeda os três agentes, cada conversa rodando em sua própria microVM com sessões isoladas.
• Amazon Nova 2 Lite (texto via Amazon Bedrock Converse API) e Amazon Nova 2 Sonic (voz para voz em tempo real), invocados via Amazon Bedrock.
• AgentCore Gateway: servidor do Protocolo de Contexto de Modelo (MCP) gerenciado que expõe a API do backend como ferramentas MCP acessíveis pelos agentes por nome.
• AgentCore memory: registro compartilhado entre canais, indexado por um ID de cliente com hash.
• Amazon DynamoDB: armazena perfis de clientes, pedidos, itens do cardápio, carrinhos e localizações.
• Amazon Location Service: geocodificação e busca de localização mais próxima.
• Amazon Kinesis Video Streams (Amazon KVS): canal de sinalização para o relay TURN gerenciado que transporta a mídia das chamadas de voz.
• Amazon Nuvem Privada Virtual (Amazon VPC): caminho de saída para o runtime de chamadas de voz — o único runtime que precisa de VPC.
• AWS Secrets Manager e AWS Systems Manager Parameter Store: armazenam tokens e segredos da Meta e o pepper do ID do cliente.
• Amazon Registro de Contêiner Elástico (Amazon ECR), AWS CodeBuild e Amazon Simple Storage Service (Amazon S3): constroem e armazenam as imagens de contêiner ARM64 dos agentes.
• Amazon CloudWatch e AWS Serviço de Gerenciamento de Chaves (AWS KMS): monitoramento e criptografia em repouso.

Como cada canal funciona

Os três canais compartilham a mesma porta de entrada, as mesmas ferramentas de backend e a mesma memória. O que muda é o tipo de mídia e o runtime responsável por cada um.

Mensagem de texto

A mensagem chega pelo webhook. O worker deriva o customer_id, invoca o runtime de chat, que lê a memória, processa via Amazon Nova 2 Lite pela Converse API e chama as ferramentas do backend pelo gateway MCP. A resposta é enviada pelo Lambda remetente, e os eventos são gravados na memória ao final da sessão.

Nota de voz (voz para voz)

O áudio chega como mensagem de áudio no formato OGG Opus. O worker baixa os bytes e invoca o runtime de nota de voz. Após ler a memória, o áudio é decodificado para PCM a 16 kHz e alimentado em uma sessão de voz para voz do Amazon Nova 2 Sonic. Não há serviço de transcrição no caminho — é voz de entrada, voz de saída. A resposta falada é devolvida como mensagem de voz no WhatsApp.

Chamada de voz (WebRTC)

Quando o cliente inicia uma chamada, a Calling API da Meta entrega um webhook de conexão com a oferta de Protocolo de Descrição de Sessão (SDP) via Comunicação em Tempo Real pela Web (WebRTC). O worker repassa essa oferta para o runtime de chamada de voz, que opera em modo turnOnly por não ter IP público. As credenciais TURN vêm do Amazon KVS. A mídia flui via Segurança da Camada de Transporte de Datagrama e Protocolo de Transporte Seguro em Tempo Real (DTLS/SRTP) pelo relay TURN gerenciado do KVS. O Amazon Nova 2 Sonic conduz a conversa.

Reconhecimento rápido e processamento assíncrono

A Meta exige uma resposta HTTP 200 em poucos segundos. Como processar um pedido completo — buscar mídia, invocar um agente, retransmitir sinalização de chamada — leva mais tempo do que esse janela permite, o trabalho é dividido em duas etapas. O Lambda de ingestão do webhook faz apenas a parte rápida: verifica a assinatura, enfileira no Amazon SQS e retorna 200. O Lambda worker consome a fila e executa o restante. Se o worker falhar em uma mensagem, ela retorna à fila e é reprocessada. Após algumas tentativas, vai para a fila de mensagens mortas para inspeção posterior.

Memória única para todos os canais

O que faz a solução parecer um único assistente é a memória compartilhada. Um único recurso de AgentCore memory é indexado pelo customer_id com hash, e os três runtimes usam a mesma chave. Cada runtime lê os insights de longo prazo do cliente no início da sessão e grava os eventos ao final. Os insights incluem pedidos anteriores, itens favoritos e preferências mencionadas. Como todos os canais resolvem o mesmo cliente para a mesma memória, não há estado entre canais para reconciliar.

Conectando agentes ao backend com MCP

Nenhum runtime do AgentCore chama diretamente as funções Lambda do backend. O AgentCore Gateway é um servidor MCP gerenciado. Cada runtime se conecta a ele como cliente MCP via HTTPS, autenticado com o papel IAM do runtime, e descobre as ferramentas por nome. Cada runtime carrega seu próprio papel, então o gateway concede apenas o acesso que aquele runtime precisa. O gateway expõe a API REST do backend e gera uma ferramenta MCP por endpoint. Quando um agente chama uma ferramenta como PlaceOrder, o gateway traduz isso em uma requisição REST que o backend API Gateway roteia para o Lambda correspondente. Como os agentes falam com ferramentas nomeadas em vez de funções específicas, é possível alterar um handler ou adicionar uma ferramenta sem mudar nenhum agente.

Identificando o cliente sem login

Um cliente do WhatsApp não faz login, então o sistema usa o número de telefone como base de identidade. Ele aplica hash ao número no formato E.164 com um pepper secreto armazenado no AWS Systems Manager Parameter Store, e o resultado vira o customer_id ("wa-" + sha256(E164 || Pepper)[:16]). O número bruto não é armazenado na memória nem no estado da sessão, o que ajuda a atender requisitos de Informações de Identificação Pessoal (PII). Se o cliente for reconhecido, o agente o cumprimenta pelo nome e lembra suas preferências. Caso contrário, ele faz o pedido como novo cliente.

Exemplo de conversa

Não há interface web ou cliente de teste. A interação acontece diretamente no WhatsApp. Um exemplo típico de troca:

Cliente: What's on the menu near 75201?
Agente: [ferramentas: GeocodeAddress, GetNearestLocations, GetMenu]
Here's what's available at Amazing Burgers - Dallas:
- Burger Combo ($8.99)
- Chicken Tenders ($6.49)
...

Cliente: A burger combo and a milkshake, please.
Agente: [ferramentas: AddToCart, GetCart]
Added to your cart:
- 1x Burger Combo - $8.99
- 1x Milkshake - $3.49
Total: $12.48. Want me to place the order?

Cliente: Yes.
Agente: [ferramenta: PlaceOrder]
Your order is placed and is being prepared for pickup at Amazing Burgers - Dallas.

Notas de voz e chamadas de voz seguem o mesmo fluxo via Amazon Nova 2 Sonic — o cliente fala o pedido e o agente responde com voz.

Pré-requisitos e implantação

Para implantar a solução, são necessários uma conta AWS ativa com acesso habilitado aos modelos Amazon Nova 2 Lite (amazon.nova-2-lite-v1:0) e Amazon Nova 2 Sonic (amazon.nova-2-sonic-v1:0) na região de implantação, além de permissões IAM para criar os recursos da solução, incluindo AgentCore runtime, Gateway e memory. Localmente, é preciso ter Node.js 24.x ou superior, AWS CLI 2.x configurado e git. O bootstrap do AWS CDK na conta e região alvo também é necessário. A região Leste dos EUA (Norte da Virgínia) — us-east-1 — é um bom ponto de partida. Para disponibilidade dos modelos por região, consulte os modelos suportados por região no Amazon Bedrock.

No lado da Meta, é preciso ter um App de Desenvolvedor Meta com o produto WhatsApp adicionado, vinculado a um portfólio de negócios. Para testes, o número de sandbox da Meta é suficiente, sem necessidade de verificação de negócio ou número de produção. Consulte como começar com a Cloud API para o procedimento completo. Para chamadas de voz, é necessário habilitar a WhatsApp Calling API no número.

A solução completa está no repositório de exemplo no GitHub. Para implantar:

git clone https://github.com/aws-samples/sample-multimodal-whatsapp-restaurant-agent.git
cd sample-multimodal-whatsapp-restaurant-agent
./scripts/preflight-check.sh
./scripts/deploy-all.sh --deploymentPrefix qsr-wa

O script provisiona todas as stacks em ordem de dependência: VPC compartilhada, backend (DynamoDB, Location Service, Lambdas e API REST), AgentCore Gateway e memória compartilhada, build das imagens ARM64 com CodeBuild, push para ECR, implantação dos três runtimes, webhook do WhatsApp e notificador de pedidos, e por fim a alimentação dos dados de cardápio e localização. O primeiro build de cada contêiner leva aproximadamente 8 a 12 minutos.

Os segredos da Meta (Access Token, App Secret e Verify Token) são armazenados em containers vazios do Secrets Manager criados pelo CDK e preenchidos fora de banda — nunca como parâmetros do CDK, o que evitá-los de aparecer no template sintetizado.

Custos e considerações para produção

Os custos escalam principalmente com o volume de conversas e a proporção de tráfego de voz, que consome mais recursos por sessão do que texto. Limitar a implantação a canais específicos pode reduzir o custo base. Para estimativas detalhadas por região, use a Calculadora de Preços da AWS e consulte a página de preços da Meta WhatsApp Business Platform.

Para implantações em produção, a AWS recomenda habilitar o Amazon Bedrock Guardrails para adicionar filtragem de conteúdo e validação de fundamentação, garantindo que as respostas do agente permaneçam dentro dos limites da política e reduzindo saídas alucinadas.

Vale notar que o WhatsApp também recebe imagens e documentos. Esta solução foca em pedidos e não processa esses anexos, mas o Amazon Nova 2 Lite já é multimodal — o agente poderia ler a foto de um cartão fidelidade ou um PDF de pedido de catering e transformá-lo em um pedido estruturado. O padrão também vai além de restaurantes: os mesmos blocos construtores se encaixam em suporte ao varejo, triagem de saúde, agendamento de serviços de campo e outros domínios, bastando trocar as ferramentas e dados do backend.

Limpeza dos recursos

Para evitar cobranças contínuas, a AWS disponibiliza um script de limpeza que destrói as stacks na ordem inversa:

./scripts/cleanup-all.sh --dry-run  # visualiza sem remover nada
./scripts/cleanup-all.sh            # exclui todas as stacks criadas

A limpeza é destrutiva: exclui o histórico de pedidos no DynamoDB, o pepper no Parameter Store, os segredos no Secrets Manager e as imagens no ECR. Faça backup do que quiser manter antes. O lado da Meta não é afetado — cancele a inscrição do webhook e revogue os tokens no console da Meta separadamente. Ao final, confirme no console do AWS CloudFormation que as stacks foram removidas.

Fonte

Deploy a multimodal WhatsApp ordering assistant with Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/deploy-a-multimodal-whatsapp-ordering-assistant-with-amazon-bedrock-agentcore/)