今年九月,我们宣布Bird 的通信基础设施向 AI 智能体开放。本文是这一公告的开发者版本。它列出智能体运行的命令、连接的对象、获取账户的方式,以及你可以对它施加的限制,并给出每一项对应的文档页面。
CLI
能运行 shell 命令的智能体(例如 Claude Code、Cursor 的终端或 CI 作业)应从 CLI 入手:每次操作消耗的 token 远少于 MCP。下文介绍的 MCP 服务器适用于调用工具但无法运行 shell 的宿主,也用于 MCP Events。
bird 是一个专为智能体驱动而构建的单一二进制文件。输出以 JSON 格式写入 stdout,错误写入 stderr,退出码表示失败类别,因此智能体无需解析文字即可根据结果分支处理。
curl -fsSL https://cli.bird.com/install.sh | sh
bird auth login
对智能体来说,三个标志承担了大部分工作。--example 输出有效的请求体,--dry-run 显示请求但不发送,--idempotency-key 让响应丢失时的重试保持安全。面向智能体的 CLI 说明了这一约定,CLI 参考列出了每条命令。
托管的 MCP 服务器
有些宿主调用工具但无法运行 shell,例如 Claude Desktop、ChatGPT 或移动应用。对于这类宿主,Bird MCP 服务器运行在 https://mcp.bird.com。将该 URL 提供给 MCP 客户端并通过浏览器登录后,客户端即持有一个代表你操作的令牌。授权页面会显示客户端请求的权限,你可以取消勾选智能体不需要的权限。你无需安装任何东西,也无需复制 API 密钥。支持的客户端包括 Claude Code、Cursor、VS Code、Codex、Claude、ChatGPT 和 Muse,Bird 已列入 Claude 的连接器目录。
该服务器将 Bird API 作为工具提供,因此已连接的智能体可以通过 Bird 运营的渠道发送消息、配置这些渠道并查看你的工作区。对工具数量有限制的客户端可以连接 https://mcp.bird.com/dynamic,它只列出两个工具:search 用于查找操作,execute 用于调用操作。借助 MCP Events,客户端可以订阅工作区中发生的事件,例如收到的 SMS 或邮箱中的新邮件,这样智能体就无需轮询。
MCP 服务器介绍了每个客户端的配置步骤。安装 CLI 后,bird mcp 会通过 stdio 运行本地服务器。本地服务器额外提供注册工具和本地文件上传,但不提供 MCP Events。
从终端注册
没有账户的代理可以在终端中创建账户,无需浏览器会话,也无需访问控制台。代理需要能访问一个电子邮件收件箱,因为登录码通过电子邮件发送:
bird auth signup you@example.com
bird auth verify-email you@example.com --code 123456
bird auth create-org "Acme" --workspace-name "Production" --region eu1 --onboarding-ticket "YOUR_ONBOARDING_TICKET"
bird auth create-org 会创建组织及其工作区,并存储一个凭据,此后 CLI 和本地 MCP 服务器都使用该凭据。--region 决定账户及其数据存放的位置:us1 或 eu1。对于没有 CLI 的代理,同样的三个步骤也可以用 curl 完成。托管的 MCP 服务器不提供注册功能,因为客户端必须先持有凭据才能连接到该服务器。
这个初始凭据的权限很宽。它包含新组织所有者可以委派的所有权限,其中包括组织账单权限,而且注册过程不会显示用于缩小权限的授权同意页面。在让代理无人值守运行之前,请先为它创建一个限定范围的 API 密钥。自助注册介绍了这两种方式。
限制代理可执行的操作
通过 Bird 发送消息的代理持有凭据,并会消耗你的余额。代理控制在一个页面中说明了约束代理的各项机制。在让代理无人值守运行之前,需要设置以下四项。目标地允许列表和每日支出上限适用于 SMS。电子邮件和 WhatsApp 不提供这两项,因此在这些渠道上,约束代理的是密钥的权限范围和钱包。同一页面还介绍了安全重试:发送 Idempotency-Key 请求头,或在 CLI 上使用 --idempotency-key,重复的请求只会被接受一次。
限定范围的 API 密钥。 API 密钥属于一个工作区,并带有你授予的权限范围,每个范围对应一个产品领域,级别为 read 或 write。只发送 SMS 而不做其他操作的密钥持有 sms:write,超出其权限范围的请求会返回 403。密钥不能签发其他密钥,也无法访问账单。
bird auth login --scope api_keys:write --scope sms:write # an existing account
bird api-keys create --name "Support agent" --scope sms:write
登录身份必须持有 api_keys:write 以及该密钥将携带的权限范围。终端注册得到的凭据已经具备这些权限,因此执行 bird auth create-org 之后,只需运行第二条命令。不要在那里重新登录:新的登录会替换注册凭据。请在未设置 BIRD_API_KEY 的 shell 中运行该命令,因为 CLI 会优先使用该密钥而不是登录身份,而密钥无法签发密钥。
然后只把该密钥交给代理,不要提供更宽的权限。在代理的环境中设置 BIRD_API_KEY,或在代码中将该密钥作为 bearer 令牌发送。登录身份会保存在执行登录的机器上,该机器上没有 BIRD_API_KEY 的代理会使用它。请在其他机器上运行代理,或使用 bird auth logout 移除该登录身份。
默认拒绝的 SMS 目标地。 工作区只向其目标地允许列表中的国家/地区发送 SMS。允许列表初始为空,设置组织的所在国家/地区后,Bird 会将其加入列表。通过 SMS API 向其他任何国家/地区发送时,会在解析发送方之前以 422 SMSDestinationNotEnabled 拒绝,因此指向意外国家/地区的代理会被拒绝。验证码不使用此列表。Verify 有自己的列表,其中所有国家/地区初始均已启用,Voice 也有自己的设置。
每日支出上限。 每个 SMS 目标国家/地区都可以设置每日支出上限,币种为钱包的币种。当天发往该国家/地区的支出达到上限后,Bird 会拒绝发往该地的新消息,直到 UTC 午夜。该上限并不精确:支出在消息计费时才计入,因此已接受的消息可能使当天总额超过上限。SMS 发送的验证码也计入上限。以下命令在钱包币种为 EUR 的工作区中启用荷兰,并设置每天 25 EUR 的上限:
bird sms destinations update --destination "NL=true;25EUR"
修改允许列表或上限需要 write 级别的 sms_management 权限范围。为发送消息的代理授予 sms,把 sms_management 留给配置工作区的凭据,这样代理就无法提高自己的上限。
预付费钱包。 按量付费的发送从组织的预付费钱包中扣款。余额不足以支付的 SMS 发送会被拒绝,并返回 402。有些费用在发送被接受后才结算(付费 Email 套餐下的邮件,以及在送达时收取的费用),而且自动充值会从已保存的银行卡为钱包充值,因此在把余额当作硬性上限之前,请先阅读钱包规则。计费操作需要组织的计费权限,而 API 密钥无法持有该权限。为无人值守的代理提供限定范围的密钥,充值操作就仍由管理预算的人员负责。
后续步骤
- 为代理分配专属电话号码和收件箱:一个
inbox.ai地址和一个专用号码,均可收发消息。在获取第一个号码之前,需要有人为钱包充值,并由组织所有者完成身份验证。该指南说明了订购过程中哪些步骤需要人工参与。 - 面向欧洲客户的 Bird:与您签约的荷兰实体、
eu1区域以及数据处理协议。 - 使用 Bird 发送 Supabase Auth SMS 验证码:通过 Bird SMS API 为 Supabase 项目发送手机登录验证码。
- 设置您的编程代理:粘贴一条提示词,代理就会安装 CLI 和 Bird 的技能。