FastAPI para agentes de IA: rotas, validação e filas

FastAPI para agentes de IA: rotas, validação e filas

Para expor um agente de IA a WhatsApp, CRM e ERP com FastAPI, separe a API em três partes: rotas de entrada que só recebem e validam eventos, uma fila que executa o agente fora da requisição, e rotas de ferramentas que o agente usa para ler e escrever nos sistemas com permissão mínima. O agente nunca fala direto com o ERP ou o CRM. Ele passa por uma API sua, que valida, limita e registra cada ação.

Principais pontos

• A rota de webhook deve responder rápido e apenas enfileirar. O trabalho do agente acontece depois, em um worker.
• Cada ferramenta do agente é uma rota estreita, com nome de ação de negócio, esquema validado e permissão própria.
• Idempotência não é opcional: webhooks são reenviados e filas repetem tarefas, então toda escrita precisa ser segura contra duplicidade.
• Erros precisam de três destinos claros: tentar de novo, parar e registrar, ou transferir para uma pessoa.
• Comece por um fluxo real, com logs e uma métrica combinada, antes de ampliar o número de integrações.

Por que colocar uma API entre o agente e os sistemas da empresa?

É comum começar com o agente chamando direto a API do ERP ou do CRM, com uma credencial ampla. Funciona na demonstração e falha em produção, porque não há ponto único para validar, limitar, registrar e desligar.

Uma camada em FastAPI resolve isso por ser o lugar onde ficam as regras: quais ações existem, quais campos são aceitos, quem pode chamar o quê e o que acontece quando algo falha. O FastAPI ajuda porque usa Pydantic para validar dados de entrada e saída, gera documentação da API a partir dos esquemas e tem injeção de dependências, útil para autenticação e controle de acesso por rota. A documentação oficial do FastAPI cobre esses recursos.

Se a sua equipe ainda decide a linguagem, vale ler Python ou TypeScript para agentes de IA. Aqui assumimos Python, que é onde o FastAPI vive.

Que rotas a API de um agente precisa ter?

Uma divisão que costuma funcionar separa as rotas por responsabilidade, e não por sistema. Esta é uma proposta de estrutura (implementação sugerida, não uma norma):

• Rotas de entrada: GET e POST em /webhooks/whatsapp, POST em /webhooks/crm e POST em /webhooks/erp. Só verificam assinatura, validam o formato, gravam o evento e enfileiram.
• Rotas de ferramentas: por exemplo POST /tools/pedido/consultar, POST /tools/oportunidade/criar e POST /tools/atendimento/transferir. São o único caminho do agente até os sistemas.
• Rotas de operação: GET /health, GET /eventos/(id) para consultar o estado de um processamento e POST /eventos/(id)/reprocessar, protegida e restrita a pessoas autorizadas.
• Rotas de administração: pausar o agente, listar itens parados na fila e consultar o registro de decisões.

No WhatsApp Cloud API, a Meta usa uma chamada GET de verificação ao cadastrar o webhook e envia as mensagens por POST, com um cabeçalho de assinatura que você deve conferir. Os detalhes de configuração estão em como integrar IA no WhatsApp da empresa e, para quem prefere orquestrar por fluxo visual, em n8n com WhatsApp Cloud API.

O detalhe importante é o nome das ferramentas. Prefira consultar_pedido a uma rota genérica que repassa qualquer chamada ao ERP. Uma rota genérica transforma o agente em um usuário com poder total, e o modelo passa a decidir o que é permitido.

Como validar entrada e saída sem confiar no modelo?

Existem dois pontos de validação, e os dois importam.

Na entrada, o payload do webhook é validado com um modelo Pydantic. O que não bate com o esquema é rejeitado e registrado, sem chegar ao agente. Isso também reduz o risco de eventos malformados ou forjados dispararem trabalho.

Na saída do agente, antes de executar uma ferramenta, os parâmetros passam por outro modelo Pydantic, o da rota. Se o modelo de linguagem propõe um identificador de pedido em formato errado, uma quantidade negativa ou um campo que não existe, o FastAPI responde com erro de validação e a ferramenta não roda. Esse erro volta ao agente como informação estruturada, para que ele corrija ou peça o dado ao cliente.

Regras práticas:

• Use tipos restritos: enumerações para status e tipos de ação, limites de tamanho para texto, formatos para identificadores.
• Proíba campos extras nos modelos, para que parâmetros inventados falhem em vez de serem ignorados.
• Trate o texto do cliente como entrada não confiável. Uma mensagem pode tentar induzir o agente a chamar uma ferramenta com parâmetros indevidos. O artigo sobre prompt injection em agentes de IA detalha esse risco.
• Valide autorização no servidor, nunca no prompt. A regra de que o agente só pode consultar pedidos do telefone que está conversando precisa estar no código da rota.

Para o controle de acesso, o guia de autorização da OWASP (listado nas fontes) reforça princípios que cabem aqui: privilégio mínimo, negar por padrão e verificar permissão em toda requisição.

Por que o agente deve rodar em fila, e não dentro do webhook?

O motivo é prático. Um agente pode levar tempo para responder, porque chama o modelo, consulta ferramentas e às vezes repete passos. Se isso acontece dentro da requisição do webhook, o provedor pode considerar a entrega falha e reenviar o evento. O resultado é resposta duplicada para o cliente.

O padrão mais seguro é este, e o artigo da Stripe sobre webhooks (nas fontes) descreve a mesma ideia de confirmar a entrega rapidamente e processar depois:

• A rota recebe o evento e confere a assinatura.
• Grava o evento com o identificador original do provedor.
• Se o identificador já existe, responde com sucesso e não enfileira de novo.
• Enfileira a tarefa e responde de imediato.
• Um worker pega a tarefa, executa o agente e registra o resultado.

O BackgroundTasks do FastAPI roda no mesmo processo da API. Serve para tarefas leves e sem exigência de durabilidade, como gravar um log extra. Para o agente, use uma fila externa com workers separados, por exemplo Celery, ARQ ou RQ com Redis, ou o broker que sua equipe já opera. A razão é durabilidade: se o processo reinicia, a tarefa não pode sumir.

Outros cuidados de fila:

• Ordem por conversa: mensagens do mesmo cliente devem ser processadas em sequência, ou o agente responde a uma pergunta antiga.
• Limite de passos, tempo e gasto por tarefa, para evitar agente de IA em loop.
• Fila de itens parados (dead letter) para tarefas que esgotaram as tentativas, visível para uma pessoa da operação.

Como garantir idempotência nas escritas em CRM e ERP?

Idempotência significa que repetir a mesma operação não cria um segundo efeito. Em integrações com agente isso é essencial, porque há três fontes de repetição: o provedor reenviando o webhook, a fila repetindo a tarefa e o próprio agente chamando a ferramenta duas vezes.

A documentação da Stripe sobre requisições idempotentes é um bom exemplo de como um provedor define esse contrato com uma chave enviada pelo cliente. Você pode aplicar a mesma ideia internamente:

• Gere uma chave de idempotência por ação, derivada do evento de origem e do nome da ferramenta, por exemplo o identificador da mensagem somado à ação.
• Guarde a chave com o resultado. Se a mesma chave chegar de novo, devolva o resultado salvo em vez de executar.
• Quando o ERP ou o CRM não aceitam chave de idempotência, consulte antes de escrever: busque a oportunidade ou o pedido por um campo de referência e só crie se não existir.
• Separe ferramentas de leitura, que podem repetir à vontade, de ferramentas de escrita, que exigem a chave.

O que fazer quando WhatsApp, CRM ou ERP falham?

Sem uma política, cada falha vira improviso. Defina três destinos para qualquer erro, usando este guia de decisão:

• Falha temporária (tempo esgotado, limite de requisições, indisponibilidade do serviço): tentar de novo com espera crescente e um teto de tentativas. Respeite o cabeçalho de espera quando o provedor informar.
• Falha permanente (dado inválido, registro inexistente, permissão negada): não repetir. Registrar a causa, devolver ao agente um erro estruturado e, se não houver correção possível, encaminhar para uma pessoa.
• Falha de julgamento (o agente não tem informação suficiente, o pedido foge do escopo ou envolve decisão que ele não deve tomar): transferir para atendimento humano com o resumo da conversa.

Alguns detalhes que evitam problemas:

• Se o ERP está fora, o agente deve dizer ao cliente que vai verificar e retornar, em vez de inventar um status. A resposta ao cliente é uma decisão de produto, não deve ficar a critério do modelo.
• Mensagens ativas fora da janela de atendimento do WhatsApp exigem templates aprovados e consentimento. Veja mensagens ativas no WhatsApp: templates e opt-in antes de programar reenvios automáticos.
• Use um formato único de erro nas rotas, com código, mensagem e indicação de se vale tentar de novo. Isso facilita tanto o worker quanto o agente.
• Registre cada chamada com identificador de correlação, ferramenta, resultado e duração. O material introdutório de observabilidade do OpenTelemetry (nas fontes) ajuda a pensar em logs, métricas e rastros de forma consistente.

Sobre LGPD, a regra de projeto é enviar ao modelo só o necessário. Mascare documentos e dados que a tarefa não exige, defina por quanto tempo os logs são guardados e quem acessa. Para dúvidas sobre o tratamento, a ANPD é a referência oficial.

Cenário ilustrativo: consulta de status de pedido

Imagine uma distribuidora fictícia cujo cliente pergunta no WhatsApp onde está o pedido. O fluxo na API fica assim:

• A Meta envia o webhook. A rota confere a assinatura, valida o payload, grava o evento com o identificador da mensagem e enfileira.
• O worker abre a conversa, carrega o contexto mínimo e roda o agente com limite de passos.
• O agente chama consultar_pedido. A rota verifica que o telefone da conversa está vinculado ao cliente do pedido e devolve apenas os campos de status e previsão.
• O ERP demora a responder. O worker tenta de novo com espera crescente. Se esgotar as tentativas, o agente avisa o cliente que vai confirmar e o evento vai para a fila de parados, com aviso à operação.
• Se o cliente pede alteração de endereço, a ferramenta de escrita não existe nesse piloto. O agente chama transferir, com resumo, e uma pessoa assume.

Nesse desenho, o agente nunca vê a credencial do ERP, nunca acessa pedido de outro cliente e nunca executa uma ação que não esteja na lista de rotas.

Como aplicar mapear, limitar, pilotar e transferir

O método de trabalho do Juan Carlo segue quatro movimentos, e eles se traduzem bem para a API.

Mapear: levante o fluxo atual, quem faz o quê, em quais sistemas e qual é o ponto de partida de tempo e erro. Sem essa linha de base, não há como saber se o piloto ajudou.

Limitar: defina quais dados o agente vê e quais ações pode executar. Cada ação vira uma rota com esquema, permissão e registro. O que não está na lista não existe para o agente.

Pilotar: escolha um fluxo real, como status de pedido ou criação de oportunidade, com logs e uma métrica combinada antes de começar. A fila de itens parados e o registro de decisões fazem parte do piloto, não são extras.

Transferir: ao final, entregue documentação, rotas, painel de operação e responsáveis, e decida com a equipe se vale expandir, ajustar ou parar. Parar é um resultado legítimo de um piloto bem conduzido.

Checklist antes de colocar em produção

• Webhooks com verificação de assinatura e resposta rápida.
• Evento gravado com identificador do provedor e proteção contra duplicidade.
• Fila externa durável, com worker separado e ordem por conversa.
• Rotas de ferramentas nomeadas por ação de negócio, com Pydantic restrito.
• Autorização verificada no servidor, com credenciais separadas por sistema e por escopo.
• Chave de idempotência em toda escrita.
• Política de erro com três destinos: repetir, parar ou transferir.
• Limites de passos, tempo e gasto por tarefa.
• Logs com identificador de correlação, retenção definida e dados sensíveis mascarados.
• Botão para pausar o agente e rota de transferência para humano testada.

Perguntas frequentes

Preciso de fila se o volume de mensagens é pequeno? Recomendamos sim, mesmo com pouco volume. O motivo não é escala, e sim durabilidade e proteção contra reenvio: o provedor pode repetir o webhook e o agente pode demorar. Uma fila simples já separa receber de processar e evita respostas duplicadas.

Posso usar o BackgroundTasks do FastAPI para rodar o agente? Para protótipos e tarefas leves, pode. Em produção, ele roda no mesmo processo da API, então uma reinicialização pode perder a tarefa e não há controle de tentativas. Para agentes que chamam modelos e sistemas externos, uma fila com workers separados é mais segura.

O agente pode ter acesso direto de escrita ao ERP? Nossa recomendação é que não tenha, pelo menos no início. Exponha ações específicas por rotas da sua API, com validação, chave de idempotência e permissão mínima, e comece com leitura. Escritas entram aos poucos, com aprovação humana quando o impacto for alto.

Como saber se a integração está funcionando bem? Defina antes do piloto uma métrica simples ligada ao processo, como conversas resolvidas sem transferência indevida ou tempo até a primeira resposta útil, e compare com a linha de base mapeada. Acompanhe também a fila de itens parados e os erros por ferramenta, porque eles mostram onde o desenho precisa de ajuste.

Fontes

• FastAPI: documentação oficial
• Stripe: webhook delivery and verification
• Stripe: idempotent requests
• OWASP: Authorization Cheat Sheet