KI-Builder-Leitfäden

Die API-Oberfläche von Bird ist agentengerecht gestaltet: eine Operation pro Tool, JSON rein und raus, und maschinenprüfbare Ergebnisse. Ein zuverlässiger Agent braucht dennoch die richtigen Muster drumherum. Die folgenden fünf Muster decken die Fehlermodi ab, die Agenten-Integrationen zum Scheitern bringen: Annahme als Zustellung behandeln, ohne Kontext wiederholen und Prosa statt Struktur parsen. Jedes Muster funktioniert gleich, unabhängig davon, ob Ihr Agent den MCP-Server oder die bird CLI steuert. Die Beispiele unten beziehen sich auf E-Mail, da dort das Tooling rund um einen Sendevorgang am umfangreichsten ist, und die Muster übertragen sich unverändert auf SMS und WhatsApp: dieselbe 202 beim Senden, dieselbe Accepted-dann-Terminal-Event-Sequenz, derselbe Fehlerumschlag. Die einzige Ausnahme ist Muster 3, dessen Magic-Adressen eine E-Mail-Sandbox sind.

Muster 1: Eine Operation pro Schleifendurchlauf

Die Tools von Bird sind bewusst granular: eine Nachricht senden, eine Nachricht abrufen, Domains auflisten oder einen Webhook-Endpunkt erstellen. Jedes Tool 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 kommt:

Codebeispiel

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

Mit der CLI ist die Fehlerkategorie der Exit-Code, sodass die Verzweigung kein Message-Parsing benötigt. Die vollständige Tabelle finden Sie unter CLI:

Codebeispiel

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

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 und die Zustellung aussteht. Das endgültige Ergebnis 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, übersieht stillschweigend jeden Bounce. Strukturieren Sie die Aufgabe stattdessen als Senden-dann-Warten:

Codebeispiel

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

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. Zustellungen erfolgen mindestens einmal (at-least-once) und ungeordnet; 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. Polling ist langsamer, aber der Rücklesevorgang bleibt die Quelle der Wahrheit.

Muster 3: Die Sandbox als Test-Harness verwenden

Während Sie die Schleife entwickeln, verwenden Sie die Magic-Adressen der Mail-Sandbox auf messagebird.dev anstelle echter Postfächer. Die Adresse bestimmt das Ergebnis (delivered@ wird immer zugestellt, bounce@ erzeugt immer einen Hard-Bounce und complaint@ erzeugt immer eine Beschwerde). Alles andere nutzt die Produktions-Pipeline: dieselbe 202, Event-Sequenz und signierten Webhook-Zustellungen, ohne Kennzeichnung der Nachricht 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)

Die Sandbox bietet deterministische Ergebnisse, kein Reputationsrisiko, keine Einträge in Unterdrückungslisten und wiederverwendbare Adressen über alle Durchläufe hinweg. Ein Agent, der die Sandbox-Matrix besteht, hat den gesamten Muster-2-Pfad durchlaufen (Senden, Warten und Verzweigen), bevor er eine echte Inbox berührt.

Muster 4: Fehlerbehebung gegen den Standard-Fehlerumschlag

Jeder Bird-API-Fehler hat die gleiche Struktur, sodass ein einziger Fehlerbehebungspfad über alle Endpunkte hinweg funktioniert:

Codebeispiel

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

Jedes Feld hat eine Aufgabe in der Schleife. Verzweigen Sie auf type/code (stabil und maschinenlesbar), zeigen Sie message dem Menschen und rufen Sie doc_url ab, wenn der Agent die Seite für genau diesen Fehler braucht. Die URL löst sich zu Markdown auf, das der Agent lesen kann. Loggen Sie request_id, damit ein Mensch sie dem Bird-Support übergeben kann. Unterscheiden Sie dann wiederholbare Fehler von Anfragefehlern:

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 (siehe Muster 1 und die vollständige Tabelle unter CLI). Ein Shell-steuernder Agent kann daher verzweigen, bevor er irgendetwas parst.

Muster 5: Sicher wiederholen mit Idempotency-Key und Retry-After

Wiederholungsversuche können Arbeit duplizieren, wenn ein Sendevorgang ein Timeout hat und der Agent es erneut versucht. Die Idempotenz-Unterstützung von Bird macht Wiederholungsversuche sicher. Generieren Sie einen Idempotency-Key pro logischer Operation und verwenden Sie ihn bei jedem Versuch 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.

Ein 429 bedeutet, dass der Agent langsamer werden muss. Die Antwort enthält einen Retry-After-Header; verwenden Sie ihn als minimales Backoff, anstatt einen eigenen Zeitplan zu erfinden:

Codebeispiel

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

Wiederholen Sie keine anderen 4xx-Antworten unverändert. Die Idempotenz speichert und gibt sie wieder, weil dieselbe Anfrage denselben Fehler erzeugt. Korrigieren Sie die Anfrage (Muster 4) und verwenden Sie einen neuen Key; die Wiederverwendung eines Keys mit einem anderen Body gibt 409 IdempotencyKeyReuse zurück.

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