AI 智能体能在 Bird 上做什么:CLI、MCP、终端注册和支出控制

今年九月,我们宣布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 密钥无法持有该权限。为无人值守的代理提供限定范围的密钥,充值操作就仍由管理预算的人员负责。

后续步骤

Start building with Bird in minutes.