KI-Builder-Leitfäden

Die API-Oberfläche von Bird ist agentengerecht gestaltet — eine Operation pro Tool, JSON rein und raus, maschinenprüfbare Ergebnisse — aber ein zuverlässiger Agent braucht dennoch die richtigen Muster drumherum. Die folgenden fünf decken die Fehlermodi ab, die Agenten-Integrationen tatsächlich zum Scheitern bringen: Annahme als Zustellung behandeln, blind wiederholen und Prosa statt Struktur parsen. Jedes Muster funktioniert gleich, unabhängig davon, ob Ihr Agent den MCP-Server oder die bird CLI steuert.

Muster 1: Eine Operation pro Schleifendurchlauf

Die Tools von Bird sind bewusst granular — eine Nachricht senden, eine Nachricht abrufen, Domains auflisten, einen Webhook-Endpunkt erstellen — und jedes gibt strukturiertes JSON zurück, dessen Felder der nächste Schritt prüfen kann. Bauen Sie die Schleife so, dass die Abbruchbedingung jedes Schritts aus der Ausgabe des vorherigen Schritts gelesen wird, niemals abgeleitet:

Codebeispiel

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

Mit der CLI ist die Fehlerkategorie der Exit-Code (2 ungültige Eingabe, 3 nicht gefunden, 4 Authentifizierung, 1 sonstiges), sodass die Verzweigung kein Message-Parsing benötigt:

Codebeispiel

bird email get "$id" --format json > msg.json
case $? in
  0) jq .status msg.json ;;     # advance
  3) echo "wrong id — fix, don't retry" ;;
  4) bird auth login ;;          # recover, then re-run
esac

Die Granularität ist der Punkt: Ein Agent, der den Zustand zwischen Schritten prüfen kann, erholt sich von jedem einzelnen Fehler; ein Agent, der eine einzige Mega-Operation steuert, kann nur von vorne anfangen.

Muster 2: Ein Sendevorgang gibt 202 zurück — das Ergebnis kommt später

POST einen Sendevorgang und Sie erhalten 202 Accepted mit einer Nachrichten-ID. Accepted bedeutet, dass Bird die Nachricht angenommen hat, nicht dass sie zugestellt wurde — das endgültige Ergebnis kommt nie inline. Es kommt als Webhook-Events: email.delivered wenn der Server des Empfängers sie akzeptiert, email.bounced wenn die Zustellung dauerhaft fehlschlägt, email.complained und so weiter.

Ein Agent, der bei 202 Erfolg meldet, wird jeden Bounce stillschweigend übersehen. Strukturieren Sie die Aufgabe stattdessen als Senden-dann-Warten:

Codebeispiel

send → 202 + em_… id            # record the id, do NOT report "sent successfully"
await webhook event where data.email_id == em_… id:
  email.delivered → done
  email.bounced   → report failure with bounce_type / bounce_description

Korrelieren Sie über email_id — Webhook-Payloads geben Ihre Tags und Metadaten zusammen mit den Identitätsfeldern zurück, sodass Ihr eigener Kontext ohne zusätzlichen Lookup zurückkommt. Bedenken Sie, dass Zustellungen mindestens einmal (at-least-once) und ungeordnet erfolgen — deduplizieren Sie anhand des webhook-id-Headers und sortieren Sie nach dem timestamp im Payload. Wenn Ihr Agent keinen Webhook-Empfänger hat, pollen Sie die Nachricht mit GET (oder bird email get), bis sich der Status auflöst — langsamer, aber die gleiche Regel gilt: Der Rücklesevorgang ist die Quelle der Wahrheit, die 202 ist es nicht.

Muster 3: Die Sandbox als Test-Harness verwenden

Während Sie die Schleife entwickeln, senden Sie keine echten E-Mails — senden Sie an die Magic-Adressen der Mail-Sandbox auf messagebird.dev. Das Ergebnis wird durch die Adresse bestimmt (delivered@ wird immer zugestellt, bounce@ erzeugt immer einen Hard-Bounce, complaint@ erzeugt immer eine Beschwerde), aber alles andere ist die echte Produktions-Pipeline: dieselbe 202, dieselbe Event-Sequenz, dieselben signierten Webhook-Zustellungen, ohne Kennzeichnung als Test.

Codebeispiel

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)

Das macht die Sandbox zum idealen Agent-Test-Harness: deterministische Ergebnisse zum Assertieren, kein Reputationsrisiko, keine Einträge in Unterdrückungslisten und wiederverwendbare Adressen über alle Durchläufe hinweg. Ein Agent, der die Sandbox-Matrix besteht, hat seinen gesamten Muster-2-Pfad durchlaufen — Senden, Warten, Verzweigen — bevor er eine echte Inbox berührt.

Muster 4: Fehlerbehebung gegen den Standard-Fehlerumschlag

Jeder Bird-API-Fehler hat die gleiche Struktur, sodass die Fehlerbehebung ein einziger Codepfad ist, nicht einer pro Endpunkt:

Codebeispiel

{
  "error": {
    "type": "invalid_request",
    "code": "E01002",
    "name": "InvalidRequest",
    "message": "from address is not on a verified sending domain",
    "doc_url": "https://bird.com/docs/api/errors/E01002",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Jedes Feld hat eine Aufgabe in der Schleife: Verzweigen Sie auf type/code (stabil, maschinenlesbar), zeigen Sie message dem Menschen, rufen Sie doc_url ab, wenn der Agent die Dokumentationsseite für genau diesen Fehler braucht — sie löst sich zu Markdown auf, das der Agent lesen kann — und loggen Sie request_id, damit ein Mensch sie dem Bird-Support übergeben kann. Die entscheidende Unterscheidung ist wiederholbar versus nicht wiederholbar:

Codebeispiel

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)

Der vollständige Code-Katalog befindet sich auf der Fehlerseite. Mit der CLI kommt der Fehlerumschlag auf stderr und der Exit-Code klassifiziert ihn vor (2/3/4/1 — siehe Muster 1), sodass ein Shell-steuernder Agent verzweigen kann, bevor er irgendetwas parst.

Muster 5: Sicher wiederholen — Idempotency-Key und Retry-After bei 429

Wiederholungsversuche sind dort, wo Agenten Schaden anrichten: ein Timeout bei einem Sendevorgang, ein blindes Retry, und der Kunde bekommt zwei E-Mails. Die Idempotenz-Unterstützung von Bird macht den Wiederholungsversuch sicher — generieren Sie einen Idempotency-Key pro logischer Operation (nicht pro Versuch) und verwenden Sie ihn bei jedem Retry wieder:

Codebeispiel

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

Der Idempotency-Replay: true-Antwortheader markiert eine Wiedergabe der ursprünglichen Antwort, sodass Ihr Agent „wiederhergestellt" statt „zweimal gesendet" loggen kann. Die Bird SDKs injizieren automatisch einen Key bei jeder mutierenden Anfrage, sodass SDK-basierte Agenten dies kostenlos erhalten; mit der CLI übergeben Sie --idempotency-key bei Mutationen, die möglicherweise wiederholt werden.

Rate-Limiting erhält die gegenteilige Behandlung: Ein 429 bedeutet langsamer werden, nicht härter versuchen. Die Antwort enthält einen Retry-After-Header — respektieren Sie ihn als Untergrenze Ihres Backoffs, anstatt einen eigenen Zeitplan zu erfinden:

Codebeispiel

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

Wiederholen Sie niemals andere 4xx-Antworten unverändert — sie werden durch die Idempotenz zwischengespeichert und wiedergegeben, genau weil dieselbe Anfrage immer denselben Fehler erzeugt. Korrigieren Sie die Anfrage (Muster 4) und verwenden Sie einen neuen Key, da die Wiederverwendung eines Keys mit einem anderen Body 409 IdempotencyKeyReuse zurückgibt.

Nächste Schritte

MCP-Server — die Tool-Oberfläche, die diese Muster steuern, gehostet auf mcp.bird.com oder lokal mit der CLI ausgeführt
CLI für Agenten — dieselben Operationen für Shell-fähige Agenten
Webhooks & Events — Zustellsemantik, Signaturen und der Event-Katalog hinter Muster 2
Idempotenz — Wiedergabesemantik und Fehlermodi hinter Muster 5
Fehler — der Fehlerumschlag und der vollständige Fehlercode-Katalog
Mail-Sandbox — die Magic-Address-Matrix hinter Muster 3