Agente de IA por email: como construir

Email é o canal para o qual os agentes estão mais bem preparados e o que quase nenhum deles chega a ter.

Mais bem preparados, porque é no email que moram as mensagens difíceis. Ninguém manda uma ordem de compra por WhatsApp. Pedidos de orçamento, notas fiscais, confirmações de fornecedor e threads de suporte com seis respostas e um PDF anexado chegam todos por email, e cada um deles é uma tarefa com contexto suficiente para um agente fazer o trabalho de verdade.

Quase nenhum chega a ter, porque dar uma caixa de entrada a um agente significa resolver deliverability, e deliverability é uma disciplina com a própria década de dor acumulada.

Este texto cobre o que é preciso.

O que um agente com caixa de entrada realmente precisa

Cinco coisas, e só uma delas é o modelo:

Requisito	Por que não é opcional
Um domínio de envio, autenticado	Email sem autenticação vai para spam ou é rejeitado direto
Roteamento de entrada	Um lugar onde as respostas caiam como eventos, não numa caixa que ninguém lê
Threading	Um agente que responde uma thread de cinco mensagens sem ler responde a pergunta errada
Anexos nos dois sentidos	O PDF costuma ser onde está o pedido de verdade
Uma lista de supressão	Enviar para um endereço que deu hard bounce queima a reputação que levou meses para construir

Sem o primeiro, nada chega. Sem o último, tudo para de chegar, três semanas depois, de uma vez.

Configurar o domínio

Autenticação de email são três registros com três funções. DKIM assina o seu email para que o destinatário verifique que veio de você. SPF diz quais servidores podem enviar como o seu domínio. DMARC diz ao destinatário o que fazer quando os dois primeiros discordam.

terminal
npx zavudev email-domains add example.com

Isso devolve os registros para publicar. DKIM é obrigatório para enviar qualquer coisa. SPF, DMARC e um MAIL FROM próprio aparecem como recomendados, o que é pouco: são eles que separam a caixa de entrada da aba de promoções.

Publique no seu provedor de DNS e depois:

terminal
npx zavudev email-domains verify example.com

Duas notas práticas. A verificação olha o que o provedor tem em cache, então registros corretos podem continuar aparecendo como pendentes por um tempo; rodar verify de novo não força um novo scan. E use um subdomínio que você possa queimar, tipo agent.example.com, em vez do domínio corporativo principal. Se o agente errar feio com volume, o estrago fica contido num domínio que dá para aposentar.

Receber email

Enviar é a metade fácil. Um agente precisa de respostas, o que significa um registro MX e receiving habilitado no sender.

A configuração que mais importa para agentes é o catch-all. Com ele ligado, o sender recebe email endereçado a qualquer local part daquele domínio, não só ao endereço dele. Ou seja, orders@, quotes@, support@ e ticket-4471@ chegam todos no mesmo agente, e o destinatário original vem no data.to do webhook para o agente saber qual foi usado.

É isso que torna possível o endereçamento por thread. Dê a cada conversa o próprio endereço de resposta e o threading vira exato em vez de um chute baseado no assunto:

quote-8842@agent.example.com  ->  a thread de orçamento do deal 8842
ticket-4471@agent.example.com ->  o ticket de suporte 4471

Sem parsear Re: Re: Enc:, sem casar por assunto, sem confusão quando dois clientes abrem threads sobre o mesmo produto no mesmo dia.

O agente

Email de entrada chega como um evento message.inbound igual a qualquer outro canal, então um agente que já responde no WhatsApp responde no email sem código novo.

Quando quiser comportamento específico de email, você descreve em vez de escrever. Com as skills instaladas, o prompt é:

> Adicione tratamento de email a este agente. Os endereços de resposta são quote-{dealId}@agent.example.com, então extraia o ID do deal do destinatário. Baixe os anexos e passe para answerQuotation. Responda na mesma thread com o PDF gerado anexado.

O que ele escreve:

TypeScript
import { defineFunction } from "@zavudev/functions"
import Zavudev from "@zavudev/sdk"

const zavu = new Zavudev({ apiKey: process.env.ZAVU_API_KEY })

export default defineFunction({
  on: ["message.inbound"],
  handler: async (event, ctx) => {
    if (event.data.channel !== "email") return

    const dealId = event.data.to.match(/quote-(\d+)@/)?.[1]

    // Listar anexos é só REST: a Stainless ainda não gerou isso no SDK,
    // então chame o endpoint direto em vez de um método que não existe.
    const res = await fetch(
      https://api.zavu.dev/v1/messages/${event.data.messageId}/attachments,
      { headers: { Authorization: Bearer ${process.env.ZAVU_API_KEY} } },
    )
    const { items } = await res.json()

    const reply = await answerQuotation({
      dealId,
      body: event.data.text,
      files: items.map((a: { downloadUrl: string }) => a.downloadUrl),
    })

    await zavu.messages.send({
      to: event.data.from,
      channel: "email",
      subject: Re: orçamento ${dealId},
      text: reply.text,
      htmlBody: reply.html,
      attachments: [{ filename: "quote.pdf", content: reply.pdfBase64 }],
    })
  },
})

Dois detalhes ali dentro são a razão inteira de o email ser diferente de todos os outros canais.

Anexos chegam como arquivos guardados, não como bytes no webhook. GET /v1/messages/{messageId}/attachments devolve um downloadUrl assinado e de vida curta por arquivo, gerado na hora a cada request. Baixe rápido, não faça cache da URL. É ali que costuma estar o pedido de verdade: a especificação, a ordem de compra, a foto do produto danificado. Atenção: hoje esse endpoint é só REST. O SDK de TypeScript cobre enviar anexos mas não listar, então chame com fetch como acima.

Enviar anexos aceita base64 ou uma URL. Ou content com os bytes em base64, ou path com uma URL que o servidor baixa, até 40MB no total. E content_id permite embutir uma imagem inline, referenciada do HTML como cid:seu_content_id, que é como um agente manda um gráfico em vez de descrever um.

As falhas que só acontecem no email

O loop de responder a todos. Seu agente responde a um endereço que por sua vez é um autorresposta. Ele responde. Seu agente responde. De manhã você tem quatro mil mensagens e um problema de reputação de domínio. Nunca responda a um endereço que já foi respondido nos últimos minutos, e nunca a noreply@ ou mailer-daemon@.

Responder a pergunta errada. Threads de email carregam histórico, e a mensagem mais nova costuma ser "beleza, pode seguir" com o pedido real quatro respostas acima. Dê a thread ao agente, não a última mensagem. O endereçamento por thread acima é o que torna confiável recuperar a thread certa.

Deliverability que apaga aos poucos. Nada falha de forma visível. As taxas de abertura só caem, depois as respostas param, e quando alguém vai investigar o domínio já está há um mês na caixa de spam. Os controles que importam: enviar só para quem pediu, honrar descadastros na hora, e validar listas antes de envios grandes.

terminal
curl -X POST https://api.zavu.dev/v1/introspect/email \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -d '{"emails": ["maria@example.com", "info@deaddomain.example"]}'

Isso devolve deliverable, risky ou undeliverable por endereço, com o motivo: sintaxe inválida, um domínio sem registro MX, uma caixa descartável, um endereço de função, ou um endereço que já está na sua lista de supressão por um bounce anterior. Descarte os undeliverable antes de enviar, e uma taxa de bounce que teria derrubado o seu domínio fica plana.

Nos envios individuais, endereços que seriam um hard bounce garantido são marcados como falha antes do despacho em vez de enviados, com errorCode em EMAIL_INVALID_RECIPIENT, EMAIL_DOMAIN_NOT_FOUND ou EMAIL_RECIPIENT_SUPPRESSED. Sinais de alerta como endereço de função não bloqueiam o envio, e é por isso que vale rodar a checagem em lote acima antes de qualquer coisa grande.

O agente que responde tudo. No email chegam prospecção fria, newsletters, boletos e clientes de verdade. Um agente que trata tudo isso como tarefa a cumprir vai negociar alegremente com um bot de spam. Classifique primeiro, aja depois.

Quanto custa

Email na Zavu é cobrado do saldo pré-pago em blocos de 1.000: USD 0,40 por 1.000 emails transacionais e USD 0,80 por 1.000 emails de marketing ou broadcast. O bloco é cobrado quando a sua contagem mensal cruza cada marca de 1.000. Times no Free começam com USD 2 de crédito e têm teto de 3.000 emails por mês e 100 por dia, o que dá para construir e testar um agente e não dá para rodar uma campanha.

Para um agente que atende algumas centenas de conversas por mês, a linha de email é erro de arredondamento perto dos tokens do modelo. O custo que importa nesse canal é um domínio queimado, e por isso o passo de validação vale mais do que parece.

Quando o email é o canal errado

Se a resposta tem uma linha e é para agora, o email é o lugar errado. Ninguém olha a caixa de entrada como olha o WhatsApp, e uma resposta em duas horas que tecnicamente é rápida soa lenta.

Se você precisa de uma decisão dentro de uma conversa, use um canal com turnos. Threads de email são assíncronas por desenho, e um agente que precisa de três esclarecimentos vai levar três dias para consegui-los.

Se quem recebe é um consumidor no Brasil, LATAM, Índia ou sudeste asiático, ele está no WhatsApp e o seu email vai para uma aba que ele abre nas terças.

Email ganha em contexto longo, anexos, B2B e tudo o que precisa ficar registrado. O que é bastante coisa, e é justamente a parte em que agentes são melhores.

Continue lendo

Como criar um agente de IA: o loop e depois deployado num canal.
Frameworks de agentes de IA comparados: onde o email fica no stack.
Exemplos de newsletter: o lado marketing do mesmo setup de domínio.
Agentes de IA para WhatsApp, SMS e email: um agente, todos os canais.

Agente de IA por email: dar a um agente uma caixa que funciona