AI-buildergidsen

Het API-oppervlak van Bird is agent-vormig: één operatie per tool, JSON in en uit, en machinaal controleerbare resultaten. Een betrouwbare agent heeft nog steeds de juiste patronen eromheen nodig. Deze vijf patronen behandelen de foutmodi die agentintegraties breken: acceptatie behandelen als aflevering, opnieuw proberen zonder context, en proza parsen in plaats van structuur. Elk patroon werkt hetzelfde, ongeacht of je agent de MCP server of de bird CLI aanstuurt. De voorbeelden hieronder gaan over e-mail, omdat daar de tooling rondom een verzending het diepst is, en de patronen zijn ongewijzigd van toepassing op SMS en WhatsApp: dezelfde 202 bij de verzending, dezelfde accepted-dan-terminal eventsequentie, dezelfde foutenvelop. De enige uitzondering is Patroon 3, waarvan de magische adressen een e-mailsandbox zijn.

Patroon 1: Voer één operatie per keer uit in een lus

De tools van Bird zijn bewust granulair: een bericht verzenden, een bericht ophalen, domeinen oplijsten, of een webhook-endpoint aanmaken. Elke tool retourneert gestructureerde JSON waarvan de volgende stap de velden kan controleren. Bouw de lus zo dat de exitconditie van elke stap afkomstig is uit de output van de vorige stap:

Codevoorbeeld

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

Met de CLI is de foutcategorie de exitcode, dus de vertakking vereist geen berichtparsing. Zie de volledige tabel in CLI:

Codevoorbeeld

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

De granulariteit is het hele punt: een agent die de status tussen stappen kan controleren, herstelt van elke individuele fout; een agent die één mega-operatie aanstuurt, kan alleen helemaal opnieuw beginnen.

Patroon 2: Een verzending retourneert 202; het resultaat komt later

POST een verzending en je krijgt 202 Accepted met een bericht-ID. Accepted betekent dat Bird het bericht heeft aangenomen en dat aflevering in behandeling is. Het uiteindelijke resultaat komt als webhook-events: email.delivered wanneer de server van de ontvanger het accepteert, email.bounced wanneer aflevering permanent mislukt, email.complained, enzovoort.

Een agent die succes declareert bij 202 mist stilzwijgend elke bounce. Structureer de taak als verzenden-dan-wachten:

Codevoorbeeld

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

Correleer op email_id. Webhook-payloads bevatten je tags en metadata naast de identiteitsvelden, zodat je eigen context terugkomt zonder een extra lookup. Afleveringen zijn at-least-once en ongeordend; dedupliceer op de webhook-id-header en sorteer op de payload timestamp. Als je agent geen webhook-ontvanger heeft, poll het bericht met GET (of bird email get) totdat de status is opgelost. Polling is langzamer, maar de teruggelezen status blijft de bron van waarheid.

Patroon 3: Gebruik de sandbox als je testharnas

Tijdens het ontwikkelen van de lus, gebruik de magische adressen van de e-mailsandbox op messagebird.dev in plaats van echte mailboxen. Het adres bepaalt het resultaat (delivered@ levert altijd af, bounce@ geeft altijd een hard bounce, en complaint@ geeft altijd een klacht). Al het andere gebruikt de productiepipeline: dezelfde 202, eventsequentie en ondertekende webhook-afleveringen, zonder markering dat het bericht een test is.

Codevoorbeeld

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)

De sandbox biedt deterministische resultaten, nul reputatierisico, geen schrijfacties naar suppressielijsten, en herbruikbare adressen bij elke run. Een agent die de sandboxmatrix doorstaat, heeft het volledige Patroon 2-pad doorlopen (verzenden, wachten en vertakken) voordat een echte inbox wordt aangeraakt.

Patroon 4: Herstel tegen de standaard foutenvelop

Elke Bird API-fout heeft dezelfde structuur, dus één foutherstelpad werkt over alle endpoints:

Codevoorbeeld

{
  "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"
  }
}

Elk veld heeft een taak in de lus. Vertak op type/code (stabiel en machineleesbaar), toon message aan de mens, en haal doc_url op wanneer de agent de pagina voor die exacte fout nodig heeft. De URL verwijst naar Markdown die de agent kan lezen. Log request_id zodat een mens het aan Bird-support kan overhandigen. Scheid vervolgens herhaalbare fouten van verzoekfouten:

Codevoorbeeld

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)

De volledige codecatalogus staat op de foutenpagina. Met de CLI komt de velop op stderr en de exitcode classificeert het vooraf (zie Patroon 1 en de volledige tabel in CLI). Een shell-aangestuurde agent kan daarom vertakken voordat er iets wordt geparsed.

Patroon 5: Veilig opnieuw proberen met Idempotency-Key en Retry-After

Retries kunnen werk dupliceren wanneer een verzending een timeout geeft en de agent het opnieuw probeert. De idempotentie-ondersteuning van Bird maakt retries veilig. Genereer één Idempotency-Key per logische operatie en hergebruik deze bij elke poging:

Codevoorbeeld

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

De Idempotency-Replay: true-responseheader markeert een replay van de oorspronkelijke response, zodat je agent "hersteld" kan loggen in plaats van "twee keer verzonden". De Bird SDK's injecteren automatisch een key bij elk muterend verzoek, dus SDK-gebaseerde agents krijgen dit gratis; met de CLI, geef --idempotency-key mee bij mutaties die mogelijk opnieuw worden geprobeerd.

Een 429 betekent dat de agent moet vertragen. De response bevat een Retry-After-header; gebruik deze als de minimale backoff in plaats van een apart schema te verzinnen:

Codevoorbeeld

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

Probeer andere 4xx-responses niet ongewijzigd opnieuw. Idempotentie cachet en herhaalt ze omdat hetzelfde verzoek dezelfde fout produceert. Repareer het verzoek (Patroon 4) en gebruik een nieuwe key; het hergebruiken van een key met een andere body retourneert 409 IdempotencyKeyReuse.

Volgende stappen

MCP server: het tooloppervlak dat door deze patronen wordt aangestuurd, gehost op mcp.bird.com of lokaal uitgevoerd met de CLI
CLI voor agents: dezelfde operaties voor shell-capabele agents
Webhooks & events: afleveringssemantiek, ondertekeningen en de eventcatalogus achter Patroon 2
Idempotentie: replaysemantiek en foutmodi achter Patroon 5
Fouten: de velop en de volledige foutcodecatalogus
E-mailsandbox: de magische-adresmatrix achter Patroon 3