Guias para construtores de IA

A superfície API de Bird é moldada para agentes: uma operação por ferramenta, JSON na entrada e na saída, e resultados verificáveis por máquina. Um agente confiável ainda precisa dos padrões certos ao redor. Esses cinco padrões cobrem os modos de falha que quebram integrações com agentes: tratar aceitação como entrega, tentar novamente sem contexto e interpretar texto em vez de estrutura. Cada padrão funciona da mesma forma, seja com o servidor MCP ou com o bird CLI. Os exemplos abaixo são de e-mail, porque é onde as ferramentas em torno de um envio são mais completas, e os padrões se aplicam a SMS e WhatsApp sem alteração: o mesmo 202 no envio, a mesma sequência de eventos aceitação-depois-terminal, a mesma resposta de erro. A única exceção é o Padrão 3, cujos endereços mágicos são um sandbox de e-mail.

Padrão 1: Execute uma operação por vez no loop

As ferramentas de Bird são deliberadamente granulares: enviar uma mensagem, obter uma mensagem, listar domínios ou criar um endpoint de webhook. Cada ferramenta retorna JSON estruturado cujos campos o próximo passo pode verificar. Construa o loop de modo que a condição de saída de cada passo venha da saída do passo anterior:

Exemplo de código

loop:
  result = run_tool(next_operation)        # one operation per call
  if result.ok: advance using result.data  # for example, the em_… ID or verified domain
  else: branch on the failure category     # see Pattern 4

Com o CLI, a categoria de falha é o código de saída, então a ramificação não precisa interpretar mensagens. Veja a tabela completa em CLI:

Exemplo de código

bird email get "$id" --format json > msg.json
case $? in
  0) jq .status msg.json ;;     # advance
  3) echo "wrong ID: fix the value instead of retrying" ;;
  4) bird auth login ;;          # recover, then re-run
esac

A granularidade é o ponto: um agente que pode verificar o estado entre passos se recupera de qualquer falha isolada; um agente que executa uma mega-operação só pode recomeçar do zero.

Padrão 2: Um envio retorna 202; o resultado chega depois

POST um envio e você recebe 202 Accepted com um ID de mensagem. Aceito significa que Bird recebeu a mensagem e a entrega está pendente. O resultado final chega como eventos de webhook: email.delivered quando o servidor do destinatário aceita, email.bounced quando a entrega falha permanentemente, email.complained, e assim por diante.

Um agente que declara sucesso em 202 perde silenciosamente cada bounce. Estruture a tarefa como enviar-e-aguardar:

Exemplo de código

send → 202 + em_… ID            # record the ID; delivery is still pending
await webhook event where data.email_id == em_… id:
  email.delivered → done
  email.bounced   → report failure with bounce_type / bounce_description

Correlacione por email_id. Os payloads de webhook ecoam suas tags e metadados junto com os campos de identidade, então seu próprio contexto retorna sem uma consulta extra. As entregas são at-least-once e sem ordem; deduplicar pelo header webhook-id e ordenar pelo timestamp do payload. Se seu agente não tem um receptor de webhook, consulte a mensagem com GET (ou bird email get) até o status ser resolvido. Polling é mais lento, mas a leitura continua sendo a fonte da verdade.

Padrão 3: Use o sandbox como seu ambiente de testes

Durante o desenvolvimento do loop, use os endereços mágicos do sandbox de e-mail em messagebird.dev em vez de caixas de correio reais. O endereço determina o resultado (delivered@ sempre entrega, bounce@ sempre retorna hard-bounce, e complaint@ sempre gera reclamação). Todo o resto usa o pipeline de produção: o mesmo 202, a mesma sequência de eventos e entregas de webhook assinadas, sem nenhum flag marcando a mensagem como teste.

Exemplo de código

for address in [delivered@, bounce@, suppressed@] @messagebird.dev:
  send to address+run42@…                  # +label correlates the test case
  assert the expected terminal event arrives (delivered / bounced / rejected)

O sandbox fornece resultados determinísticos, zero risco de reputação, nenhuma gravação em lista de supressão e endereços reutilizáveis entre execuções. Um agente que passa pela matriz do sandbox exercitou o caminho completo do Padrão 2 (enviar, aguardar e ramificar) antes de tocar uma caixa de entrada real.

Padrão 4: Recupere-se usando a resposta de erro padrão

Todo erro API de Bird tem o mesmo formato, então um único caminho de recuperação de erro funciona em todos os endpoints:

Exemplo de código

{
  "error": {
    "type": "validation_error",
    "code": "E04006",
    "name": "DomainNotVerified",
    "message": "The from address uses a domain that is not verified in this workspace.",
    "doc_url": "https://bird.com/docs/api/errors/E04006",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Cada campo tem uma função no loop. Ramifique por type/code (estável e legível por máquina), mostre message ao humano, e busque doc_url quando o agente precisar da página daquele erro específico. A URL resolve para Markdown que o agente pode ler. Registre request_id para que um humano possa fornecê-lo ao suporte Bird. Depois separe erros que permitem retentativa de erros de requisição:

Exemplo de código

4xx (except 429) → a request bug: fix the input, never retry as-is
429              → back off, then retry (Pattern 5)
5xx / timeout    → retry with the same Idempotency-Key (Pattern 5)

O catálogo completo de códigos está na página de erros. Com o CLI, a resposta de erro chega em stderr e o código de saída a pré-classifica (veja Padrão 1 e a tabela completa em CLI). Um agente que controla o shell pode, portanto, ramificar antes de interpretar qualquer coisa.

Padrão 5: Retente com segurança usando Idempotency-Key e Retry-After

Retentativas podem duplicar trabalho quando um envio expira e o agente tenta de novo. O suporte a idempotência de Bird torna retentativas seguras. Gere um Idempotency-Key por operação lógica e reutilize-o em cada tentativa:

Exemplo de código

key = uuid()                                  # once per logical send
attempt with Idempotency-Key: key
on 5xx / timeout: backoff, retry with SAME key
on 2xx with Idempotency-Replay: true → the first attempt had succeeded; do not treat as a new send

O header de resposta Idempotency-Replay: true marca uma repetição da resposta original, então seu agente pode registrar "recovered" em vez de "sent twice". Os SDKs Bird injetam uma chave automaticamente em cada requisição mutante, então agentes baseados em SDK ganham isso de graça; com o CLI, passe --idempotency-key em mutações que possam ser retentadas.

Um 429 significa que o agente precisa desacelerar. A resposta traz um header Retry-After; use-o como backoff mínimo em vez de inventar um cronograma separado:

Exemplo de código

on 429: sleep max(Retry-After, backoff(attempt)); retry with the same key

Não retente outras respostas 4xx sem alteração. A idempotência as armazena em cache e as repete porque a mesma requisição produz o mesmo erro. Corrija a requisição (Padrão 4) e use uma chave nova; reutilizar uma chave com um corpo diferente retorna 409 IdempotencyKeyReuse.

Próximos passos

Servidor MCP: a superfície de ferramentas que esses padrões utilizam, hospedada em mcp.bird.com ou executada localmente com o CLI
CLI para agentes: as mesmas operações para agentes com acesso a shell
Webhooks e eventos: semântica de entrega, assinaturas e o catálogo de eventos por trás do Padrão 2
Idempotência: semântica de repetição e modos de falha por trás do Padrão 5
Erros: a resposta de erro e o catálogo completo de códigos de erro
Sandbox de e-mail: a matriz de endereços mágicos por trás do Padrão 3

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoHow do I use Bird from a low-code tool like n8n or Zapier?Explore a funcionalidadeWorkflow automation Siga o percurso de aprendizagemBuild with AI agents

Obtenha um resumo de implementação