Guias para construtores de IA

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

Padrão 1: Executar uma operação de cada vez no loop

As ferramentas do 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 forma 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 de análise de mensagens. Consulte 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 central: um agente que pode verificar o estado entre passos recupera de qualquer falha individual; um agente que conduz uma mega-operação só pode recomeçar do zero.

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

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

Um agente que declara sucesso no 202 silenciosamente perde todos os bounces. 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 pelo email_id. Os payloads de webhook ecoam as suas tags e metadados juntamente com os campos de identidade, de modo que o seu próprio contexto retorna sem uma consulta extra. As entregas são at-least-once e desordenadas; desduplique pelo cabeçalho webhook-id e ordene pelo timestamp do payload. Se o seu agente não tem um receptor de webhook, consulte a mensagem com GET (ou bird email get) até que o seu status seja resolvido. A consulta por polling é mais lenta, mas a leitura de volta continua a ser a fonte da verdade.

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

Enquanto desenvolve o loop, use os endereços mágicos do sandbox de email em messagebird.dev em vez de caixas de correio reais. O endereço determina o resultado (delivered@ sempre entrega, bounce@ sempre resulta em hard-bounce e complaint@ sempre gera reclamação). Todo o resto usa o pipeline de produção: o mesmo 202, sequência de eventos e entregas de webhook assinadas, sem nenhuma flag a marcar 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, sem escritas na lista de supressão e endereços reutilizáveis em cada execução. Um agente que passa na matriz do sandbox exercitou o caminho completo do Padrão 2 (enviar, aguardar e ramificar) antes de tocar numa caixa de entrada real.

Padrão 4: Recuperar usando o envelope de erro padrão

Cada erro da API do Bird tem a mesma estrutura, então um único caminho de recuperação de erros 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 aceda a doc_url quando o agente precisar da página para esse erro exato. O URL resolve para Markdown que o agente pode ler. Registe request_id para que um humano possa passá-lo ao suporte do Bird. Depois separe os erros retentáveis dos erros de pedido:

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, o envelope chega no stderr e o código de saída pré-classifica (ver Padrão 1 e a tabela completa em CLI). Um agente que conduz o shell pode, portanto, ramificar antes de analisar qualquer coisa.

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

As retentativas podem duplicar trabalho quando um envio expira e o agente tenta novamente. O suporte de idempotência do Bird torna as 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 cabeçalho de resposta Idempotency-Replay: true marca uma reprodução da resposta original, para que o seu agente possa registar "recuperado" em vez de "enviado duas vezes". Os SDKs do Bird injetam uma chave automaticamente em cada pedido mutável, então agentes baseados em SDK obtêm isto gratuitamente; com o CLI, passe --idempotency-key em mutações que possam ser retentadas.

Um 429 significa que o agente deve abrandar. A resposta inclui um cabeçalho Retry-After; use-o como o backoff mínimo em vez de inventar um calendário 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 armazena-as em cache e reproduz-as porque o mesmo pedido produz o mesmo erro. Corrija o pedido (Padrão 4) e use uma nova chave; reutilizar uma chave com um corpo diferente retorna 409 IdempotencyKeyReuse.

Próximos passos

Servidor MCP: a superfície de ferramentas que estes padrões conduzem, alojada em mcp.bird.com ou executada localmente com o CLI
CLI para agentes: as mesmas operações para agentes com capacidade de 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 reprodução e modos de falha por trás do Padrão 5
Erros: o envelope e o catálogo completo de códigos de erro
Sandbox de email: a matriz de endereços mágicos por trás do Padrão 3

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptHow do I use Bird from a low-code tool like n8n or Zapier?Explore the capabilityWorkflow automation Follow the learning pathBuild with AI agents

Get an implementation brief