Przewodniki dla twórców AI

Powierzchnia API Bird jest zaprojektowana z myślą o agentach: jedna operacja na narzędzie, JSON na wejściu i wyjściu, wyniki weryfikowalne maszynowo. Niezawodny agent wciąż potrzebuje odpowiednich wzorców wokół tego. Pięć poniższych wzorców obejmuje tryby awarii, które psują integracje agentów: traktowanie przyjęcia jako dostarczenia, ponawianie bez kontekstu oraz parsowanie prozy zamiast struktur. Każdy wzorzec działa tak samo, niezależnie od tego, czy agent steruje serwerem MCP, czy bird CLI. Poniższe przykłady dotyczą e-maila, ponieważ tam narzędzia wokół wysyłki są najgłębiej rozwinięte, a wzorce przenoszą się na SMS i WhatsApp bez zmian: to samo 202 przy wysyłce, ta sama sekwencja zdarzeń accepted-then-terminal, ta sama koperta błędów. Jedynym wyjątkiem jest Wzorzec 3, którego magiczne adresy dotyczą sandboxa e-mailowego.

Wzorzec 1: Wykonuj jedną operację na raz w pętli

Narzędzia Bird są celowo granularne: wyślij wiadomość, pobierz wiadomość, wylistuj domeny lub utwórz endpoint webhooka. Każde narzędzie zwraca ustrukturyzowany JSON, którego pola następny krok może sprawdzić. Zbuduj pętlę tak, aby warunek zakończenia każdego kroku pochodził z wyniku poprzedniego kroku:

Przykład kodu

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

W CLI kategoria błędu to kod wyjścia, więc rozgałęzienie nie wymaga parsowania komunikatów. Pełną tabelę znajdziesz w CLI:

Przykład kodu

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

Granularność jest kluczowa: agent, który może sprawdzić stan między krokami, odzyska się po każdej pojedynczej awarii; agent sterujący jedną mega-operacją może jedynie zacząć od nowa.

Wzorzec 2: Wysyłka zwraca 202; wynik przychodzi później

Wyślij POST i otrzymasz 202 Accepted z identyfikatorem wiadomości. Accepted oznacza, że Bird przyjął wiadomość, a dostarczenie jest w toku. Ostateczny wynik dociera jako zdarzenia webhookowe: email.delivered gdy serwer odbiorcy ją zaakceptuje, email.bounced gdy dostarczenie trwale się nie powiedzie, email.complained i tak dalej.

Agent, który deklaruje sukces przy 202, po cichu pominie każdy bounce. Zamiast tego ustrukturyzuj zadanie jako wyślij-i-czekaj:

Przykład kodu

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

Koreluj po email_id. Payloady webhooków zwracają twoje tagi i metadane obok pól identyfikacyjnych, więc twój kontekst wraca bez dodatkowego wyszukiwania. Dostarczenia są co-najmniej-jednokrotne (at-least-once) i nieuporządkowane; deduplikuj po nagłówku webhook-id i sortuj po timestamp z payloadu. Jeśli twój agent nie ma odbiornika webhooków, odpytuj wiadomość za pomocą GET (lub bird email get), aż jej status się wyklaruje. Odpytywanie jest wolniejsze, ale odczyt zwrotny pozostaje źródłem prawdy.

Wzorzec 3: Użyj sandboxa jako środowiska testowego

Podczas rozwijania pętli używaj magicznych adresów sandboxa mailowego w domenie messagebird.dev zamiast prawdziwych skrzynek pocztowych. Adres determinuje wynik (delivered@ zawsze dostarczy, bounce@ zawsze zwróci twardy bounce, a complaint@ zawsze zgłosi skargę). Wszystko inne wykorzystuje pipeline produkcyjny: to samo 202, sekwencja zdarzeń i podpisane dostarczenia webhooków, bez żadnej flagi oznaczającej wiadomość jako test.

Przykład kodu

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)

Sandbox zapewnia deterministyczne wyniki, zero ryzyka dla reputacji, brak zapisów na listach blokad i adresy wielokrotnego użytku w każdym uruchomieniu. Agent, który przejdzie matrycę sandboxa, przetestował całą ścieżkę Wzorca 2 (wyślij, czekaj i rozgałęź) zanim dotknie prawdziwej skrzynki odbiorczej.

Wzorzec 4: Obsługuj błędy w oparciu o standardową kopertę błędów

Każdy błąd API Bird ma tę samą strukturę, więc jedna ścieżka obsługi błędów działa dla wszystkich endpointów:

Przykład kodu

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

Każde pole ma swoją rolę w pętli. Rozgałęziaj na type/code (stabilne i czytelne maszynowo), pokazuj message człowiekowi i pobieraj doc_url gdy agent potrzebuje strony dokumentacji dla dokładnie tego błędu. URL rozwiązuje się do Markdown, który agent może odczytać. Loguj request_id, aby człowiek mógł go przekazać do wsparcia Bird. Następnie rozdziel błędy ponawialne od błędów żądania:

Przykład kodu

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)

Pełny katalog kodów znajduje się na stronie błędów. W CLI koperta błędu trafia na stderr, a kod wyjścia wstępnie ją klasyfikuje (patrz Wzorzec 1 i pełna tabela w CLI). Agent sterujący shellem może więc rozgałęzić się przed parsowaniem czegokolwiek.

Wzorzec 5: Ponawiaj bezpiecznie z Idempotency-Key i Retry-After

Ponowienia mogą zduplikować pracę, gdy wysyłka przekroczy timeout i agent spróbuje ponownie. Obsługa idempotentności Bird sprawia, że ponowienia są bezpieczne. Wygeneruj jeden Idempotency-Key na operację logiczną i używaj go ponownie przy każdej próbie:

Przykład kodu

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

Nagłówek odpowiedzi Idempotency-Replay: true oznacza powtórkę oryginalnej odpowiedzi, więc twój agent może zalogować „odzyskano" zamiast „wysłano dwa razy". SDK Bird automatycznie wstrzykują klucz przy każdym żądaniu mutującym, więc agenty oparte na SDK dostają to za darmo; w CLI przekaż --idempotency-key przy mutacjach, które mogą być ponawiane.

429 oznacza, że agent musi zwolnić. Odpowiedź zawiera nagłówek Retry-After; użyj go jako minimalnego backoffu zamiast wymyślać osobny harmonogram:

Przykład kodu

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

Nie ponawiaj innych odpowiedzi 4xx bez zmian. Mechanizm idempotentności cachuje je i powtarza, ponieważ to samo żądanie produkuje ten sam błąd. Napraw żądanie (Wzorzec 4) i użyj nowego klucza; ponowne użycie klucza z innym ciałem żądania zwróci 409 IdempotencyKeyReuse.

Następne kroki

Serwer MCP: powierzchnia narzędziowa, którą te wzorce obsługują, hostowana na mcp.bird.com lub uruchamiana lokalnie przez CLI
CLI dla agentów: te same operacje dla agentów obsługujących shell
Webhooki i zdarzenia: semantyka dostarczania, podpisy i katalog zdarzeń stojący za Wzorcem 2
Idempotentność: semantyka powtórek i tryby awarii stojące za Wzorcem 5
Błędy: koperta błędu i pełny katalog kodów błędów
Sandbox mailowy: matryca magicznych adresów stojąca za Wzorcem 3