AI 构建者指南

Bird 的 API 接口天然适合代理模式：每个工具对应一个操作，JSON 输入输出，机器可检查的结果。但可靠的代理仍然需要正确的模式来支撑。以下五种模式涵盖了会破坏代理集成的故障场景：将接受视为投递、无上下文地重试、以及解析散文而非结构化数据。无论你的代理驱动的是 MCP server 还是 bird CLI，每种模式的工作方式都相同。以下示例以邮件为主，因为邮件发送相关的工具链最为完善，而这些模式可以原样迁移到 SMS 和 WhatsApp：相同的 202 发送响应、相同的"已接受-然后-终态"事件序列、相同的错误信封。唯一的例外是模式 3，其魔术地址属于邮件沙箱。

模式 1：每次循环执行一个操作

Bird 的工具设计为细粒度的：发送消息、获取消息、列出域名或创建 webhook 端点。每个工具都返回结构化 JSON，其字段可供下一步检查。构建循环时，确保每一步的退出条件都来自上一步的输出：

代码示例

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

使用 CLI 时，故障类别由退出码表示，因此分支判断无需解析消息。完整表格见 CLI：

代码示例

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

细粒度正是关键：一个能在步骤之间检查状态的代理可以从任何单一故障中恢复；而驱动一个大型操作的代理只能从头开始。

模式 2：发送返回 202；结果稍后到达

POST 发送后你会收到 202 Accepted 和一个消息 ID。**Accepted 意味着 Bird 接收了消息，投递仍在进行中。**最终结果通过 webhook 事件到达：收件人服务器接受时触发 email.delivered，永久投递失败时触发 email.bounced，还有 email.complained 等。

在 202 时就宣布成功的代理会静默地遗漏每一次退信。应将任务结构化为"发送-然后-等待"：

代码示例

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

通过 email_id 进行关联。Webhook 载荷会在身份字段旁回传你的标签和元数据，因此你自己的上下文无需额外查询即可返回。投递事件是至少一次且无序的；使用 webhook-id 头进行去重，并按载荷 timestamp 排序。如果你的代理没有 webhook 接收器，可以使用 GET（或 bird email get）轮询消息，直到其状态确定。轮询虽然更慢，但回读仍然是事实来源。

模式 3：使用沙箱作为测试工具

在开发循环过程中，使用邮件沙箱在 messagebird.dev 上的魔术地址，而非真实邮箱。地址决定结果（delivered@ 始终投递、bounce@ 始终硬退信、complaint@ 始终投诉）。其他一切都使用生产管道：相同的 202、事件序列和签名 webhook 投递，没有任何标记表明消息是测试。

代码示例

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)

沙箱提供确定性的结果、零信誉风险、不会写入抑制列表、以及跨运行可复用的地址。通过沙箱矩阵测试的代理已经在接触真实收件箱之前完整演练了模式 2 路径（发送、等待和分支）。

模式 4：基于标准错误信封进行恢复

每个 Bird API 错误都具有相同的结构，因此一条错误恢复路径适用于所有端点：

代码示例

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

每个字段在循环中都有其作用。基于 type/code（稳定且机器可读）进行分支，将 message 展示给人类，当代理需要该确切错误的页面时获取 doc_url。该 URL 会解析为代理可读的 Markdown。记录 request_id 以便人类可以将其提供给 Bird 支持团队。然后区分可重试错误与请求错误：

代码示例

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)

完整的错误代码目录在错误页面。使用 CLI 时，错误信封会输出到 stderr，退出码会预先分类（见模式 1 和 CLI 中的完整表格）。因此 shell 驱动的代理可以在解析任何内容之前就进行分支判断。

模式 5：使用 Idempotency-Key 和 Retry-After 安全重试

发送超时后代理再次尝试时，重试可能会导致重复操作。Bird 的幂等性支持使重试变得安全。为每个逻辑操作生成一个 Idempotency-Key，并在每次尝试时复用它：

代码示例

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

Idempotency-Replay: true 响应头标记这是原始响应的重放，因此你的代理可以记录"已恢复"而非"发送了两次"。Bird SDK 会在每个变更请求上自动注入密钥，因此基于 SDK 的代理可以免费获得此功能；使用 CLI 时，在可能需要重试的变更操作上传递 --idempotency-key。

429 意味着代理必须减速。响应携带 Retry-After 头；将其作为最小退避值，而非自行发明调度策略：

代码示例

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

不要原样重试其他 4xx 响应。幂等性机制会缓存并重放它们，因为相同的请求会产生相同的错误。修复请求（模式 4）并使用新的密钥；使用相同密钥但不同请求体会返回 409 IdempotencyKeyReuse。

后续步骤

MCP server：这些模式驱动的工具接口，托管在 mcp.bird.com 或通过 CLI 本地运行
CLI for agents：适用于 shell 能力代理的相同操作
Webhook 与事件：模式 2 背后的投递语义、签名和事件目录
幂等性：模式 5 背后的重放语义和故障模式
错误：错误信封和完整的错误代码目录
邮件沙箱：模式 3 背后的魔术地址矩阵

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptHow do I use Bird from a low-code tool like n8n or Zapier?Explore the capabilityWorkflow automation Follow the learning pathBuild with AI agents

Get an implementation brief