Przewodniki dla twórców AI

Powierzchnia API w Bird jest zaprojektowana pod agenty: jedna operacja na narzędzie, JSON na wejściu i wyjściu oraz wyniki weryfikowalne maszynowo. Niezawodny agent wciąż potrzebuje odpowiednich wzorców wokół siebie. Te pięć wzorców obejmuje tryby awarii, które psują integracje agentów: traktowanie przyjęcia jako dostarczenia, ponawianie bez kontekstu i parsowanie tekstu zamiast struktury. Każdy wzorzec działa tak samo niezależnie od tego, czy agent korzysta z serwera MCP, czy z bird CLI. Poniższe przykłady dotyczą e-maila, ponieważ tam narzędzia wokół wysyłki są najbogatsze, a wzorce przenoszą się na SMS i WhatsApp bez zmian: ten sam 202 przy wysyłce, ta sama sekwencja zdarzeń przyjęto-potem-końcowe, ta sama odpowiedź z błędem. Jedynym wyjątkiem jest Wzorzec 3, którego magiczne adresy dotyczą sandboxa e-mail.

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 wyjścia z każdego kroku wynikał z danych wyjściowych 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 przypadku CLI kategorię błędu określa kod wyjścia, więc rozgałęzienie nie wymaga parsowania komunikatu. 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 sprawdzać stan między krokami, odzyskuje sprawność po każdej pojedynczej awarii; agent sterujący jedną megaoperacją może jedynie zacząć od nowa.

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

Wyślij POST, a otrzymasz 202 Accepted z identyfikatorem wiadomości. Przyjęto oznacza, że Bird odebrał wiadomość i dostarczenie jest w toku. Końcowy wynik przychodzi jako zdarzenia webhooka: email.delivered, gdy serwer odbiorcy ją zaakceptuje, email.bounced, gdy dostarczenie trwale się nie powiedzie, email.complained i tak dalej.

Agent, który ogłasza sukces przy 202, po cichu pomija każdy bounce. Zamiast tego zbuduj zadanie jako wyślij-potem-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 własny kontekst wraca bez dodatkowego zapytania. Dostarczenia są 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ę rozstrzygnie. Odpytywanie jest wolniejsze, ale odczyt zwrotny pozostaje źródłem prawdy.

Wzorzec 3: Używaj sandboxa jako środowiska testowego

Podczas rozwijania pętli używaj magicznych adresów sandboxa e-mail w messagebird.dev zamiast prawdziwych skrzynek. Adres determinuje wynik (delivered@ zawsze dostarczy, bounce@ zawsze zwróci twardy bounce, a complaint@ zawsze zgłosi skargę). Wszystko inne korzysta z produkcyjnego pipeline'u: ten sam 202, sekwencja zdarzeń i podpisane dostarczenia webhooków, bez flagi oznaczającej wiadomość jako testową.

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, zerowe ryzyko reputacyjne, brak wpisów na listę blokad i adresy wielokrotnego użytku między uruchomieniami. Agent, który przejdzie macierz sandboxa, przetestował pełną ścieżkę Wzorca 2 (wyślij, czekaj i rozgałęź) zanim dotknie prawdziwej skrzynki.

Wzorzec 4: Obsługuj błędy w oparciu o standardową odpowiedź z błędem

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

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 zadanie w pętli. Rozgałęziaj na type/code (stabilne i czytelne maszynowo), wyświetlaj message człowiekowi i pobieraj doc_url, gdy agent potrzebuje strony dla danego błędu. URL prowadzi do Markdowna, który agent może odczytać. Loguj request_id, aby człowiek mógł przekazać go do wsparcia Bird. Następnie oddziel błędy do ponowienia 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 przypadku CLI odpowiedź z błędem 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 limit czasu i agent spróbuje ponownie. Obsługa idempotencji w 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 logować "recovered" zamiast "sent twice". SDK Bird automatycznie wstrzykują klucz przy każdym mutującym żądaniu, więc agenty oparte na SDK dostają to za darmo; w przypadku CLI przekazuj --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. Idempotencja je buforuje i odtwarza, ponieważ to samo żądanie daje ten sam błąd. Napraw żądanie (Wzorzec 4) i użyj nowego klucza; ponowne użycie klucza z innym ciałem zwróci 409 IdempotencyKeyReuse.

Następne kroki

Serwer MCP: powierzchnia narzędziowa, którą te wzorce obsługują, hostowana pod mcp.bird.com lub uruchamiana lokalnie z CLI
CLI dla agentów: te same operacje dla agentów obsługujących shell
Webhooki i zdarzenia: semantyka dostarczania, sygnatury i katalog zdarzeń stojący za Wzorcem 2
Idempotencja: semantyka powtórek i tryby awarii stojące za Wzorcem 5
Błędy: odpowiedź z błędem i pełny katalog kodów błędów
Sandbox e-mail: macierz magicznych adresów stojąca za Wzorcem 3

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęHow do I use Bird from a low-code tool like n8n or Zapier?Poznaj możliwościWorkflow automation Podążaj ścieżką naukiBuild with AI agents

Uzyskaj brief wdrożeniowy