智能体控制:限定范围的密钥、支出限额与安全重试
通过 Bird 发送消息的智能体持有凭据,并消耗你的余额。有五项控制可限制它的操作范围。第一项是凭据本身。其余四项只有在智能体的凭据无法修改它们时才有效,因此请先从凭据入手。
| 控制项 | 限制的内容 | 达到限制时调用方收到的结果 | 设置者 |
|---|---|---|---|
| 凭据 | 智能体可以调用的操作 | 403 | 创建密钥或批准登录的人 |
| 幂等键 | 请求重试时产生的重复发送 | 重放的原始响应 | 调用方,在每个请求中设置 |
| SMS 目的地允许列表 | SMS API 发送可以到达的国家 | 422 SMSDestinationNotEnabled | 具有 sms_management 写权限的凭据 |
| SMS 每日支出上限 | 一天内发往单个国家的 SMS 支出 | 422 SMSDestinationDailySpendExceeded | 具有 sms_management 写权限的凭据 |
| 预付费钱包 | 按量付费的支出 | SMS 和 WhatsApp 返回 402。付费邮件在发送后扣费。 | 组织所有者或账单管理员 |
本页的目的地允许列表和每日支出限额适用于 SMS。Verify 和 Voice 各有自己的目的地设置,且初始状态不同。Email 和 WhatsApp 没有目的地允许列表,也没有每日支出限额,因此在这些渠道上,限制智能体的是凭据的权限范围和钱包。
选择智能体持有的凭据
智能体调用 Bird 时使用两种凭据之一。两者的可访问范围不同。
- API 密钥(
bk_)带有你授予它的权限范围,并归属于一个工作区。它不能签发其他密钥,也无法访问组织账单、成员或设置。你的代码将其作为 bearer 令牌发送。设置了BIRD_API_KEY中的密钥时,CLI 和本地 MCP 服务器(bird mcp)会优先使用该密钥,而不是已保存的登录凭据。 - OAuth 令牌(
bt_)是用户登录后 CLI 和 MCP 服务器持有的凭据。它带有该用户批准的权限,且永远不会超出该用户自身拥有的权限。这些权限可能包括api_keys写入、sms_management写入和组织账单。持有此类令牌的智能体可以签发密钥、启用国家/地区,并提高本页所述的限额。
OAuth 令牌的权限大小取决于它的创建方式:
bird auth login请求只读访问权限。--scope请求你指定的权限集,--yolo请求你能够委派的所有权限。你需要在浏览器中批准最终结果。- 托管的 MCP 客户端可以请求你能够委派的所有权限。你可以在授权同意页面上选择要授予哪些权限。批准前,请取消勾选智能体不需要的权限。
- 自助注册 没有授权同意页面。它创建的凭据拥有新组织所有者可委派的全部权限,包括组织账单权限。
对于无人值守运行的代理,请创建一个限定范围的 API 密钥并交给代理使用。权限更广的登录凭据留给负责配置工作区的人。你可以在 Profile > Connected apps 下撤销某个工具的登录。API 密钥与 OAuth 令牌 比较了这两类凭据。
为每个密钥限定其所需的产品范围
API 密钥带有一组作用域,每个作用域对应一个产品领域,级别为 read 或 write。只用于发送 SMS 的密钥持有 sms:write。超出密钥作用域的请求会返回 403,因此即使密钥泄露或被滥用,也只能访问你授予它的内容。
无论作用域如何,密钥始终具有以下三个特性:
- 密钥不能签发其他密钥。 签发和轮换密钥需要
api_keys:write,而 API 密钥无法获得该权限。这一权限须由人在控制台会话中,或在 CLI 或 MCP 登录时批准。 - 密钥仅限于其所属工作区。 它无法访问账单、组织成员或组织设置。
- 密钥可以设置过期时间。 创建时设置
expires_at,过了该时刻后密钥会返回401。你可以随时轮换或撤销密钥。
你可以在控制台或终端中创建密钥。CLI 登录只能为密钥授予该登录本身持有的作用域,因此下面的示例除了 api_keys:write 之外还请求了 sms:write:
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write身份验证与 API 密钥 列出了作用域表,并介绍了过期、轮换和撤销。
重试发送而不重复发送
代理如果没有收到响应,就无法判断请求是否已被接受。每次计划发送时,在 Idempotency-Key 请求头中附上一个唯一值;结果未知时,用同一个键重复同一请求。Bird 会返回原始响应,且消息只被接受一次。重放的响应带有 Idempotency-Replay: true。
保证的是:在保留期内,每个密钥只会有一次操作被接受。该保证仅覆盖 API 对请求的接受。消息是否送达手机另行报告,以消息状态及其事件为准。
SDK 会为每个修改性调用生成一个密钥,并在自动重试时复用该密钥。使用 CLI 时,请传入 --idempotency-key。幂等性介绍了密钥格式、保留期,以及同一密钥用于不同请求时的处理方式。
逐个允许 SMS 目的地国家
SMS 目的地允许列表默认拒绝。通过 SMS API 发送的消息只能发往列表中已启用的国家。发往其他国家的消息会在解析发送方之前被拒绝并返回 422 SMSDestinationNotEnabled,因此不会有消息被接受。如果代理将消息发往意外的国家,请求会被拒绝。此规则适用于从您自己的代码、从 bird sms send 以及从 sms_send MCP 工具发出的消息。
验证码不受此列表约束。Verify 在 Verify destinations 下有自己的列表,所有国家初始均为启用状态。因此,拥有 verify 写权限的凭据可以通过 SMS 向此允许列表所阻止的国家发送验证码。如果代理持有 verify,请在该页面上同样关闭您不提供服务的国家。
您可以在 SMS > Destinations 下、使用 bird sms destinations update,或使用 sms_destinations_update MCP 工具启用国家:
bird sms destinations update --destination NL=true修改允许列表需要 write 级别的 sms_management 作用域。仅持有 sms 的凭据可以向已启用的国家发送消息,但不能启用更多国家。请为负责发送的代理提供 sms,并将 sms_management 留给负责配置工作区的凭据。
发送 SMS 说明了允许列表的初始状态以及本国的添加方式。
按国家限制每日 SMS 支出
每个目的地国家都可以设置每日支出上限,以您钱包的币种计算。当天发往该国家的支出达到上限后,新消息会被拒绝并返回 422 SMSDestinationDailySpendExceeded,直到 UTC 午夜。上限设为零即阻止该国家。
通过 SMS 发送的验证码计入该上限。达到上限后,Verify 会停止通过 SMS 向该国家发送验证码,并尝试该国家启用的下一个渠道。如果没有剩余渠道,验证将失败并返回 422 NoAvailableChannel。
上限的设置位置与允许列表相同,共三处。以下命令在钱包币种为 EUR 的工作区中启用荷兰,并将其上限设为每天 25 EUR:
bird sms destinations update --destination "NL=true;25EUR"该限额并不精确。修改限额后,最多需要一分钟才会在发送中生效。花费在消息计费时才计入,因此已接受的消息可能使当天总额超出限额,超出部分为这些消息的费用。设定限额时请预留这部分余量。bird sms destinations list 会显示每个国家的限额及当天已用额度。
设置限额所需的 sms_management 写入权限与允许列表相同,因此仅持有 sms 的凭据无法提高自己的限额。完整规则请参阅发送 SMS。
用预付费钱包限制总花费
按用量付费的发送从组织的预付费钱包中扣款。余额不足以支付一次发送时会发生什么,取决于渠道:
- SMS 和 WhatsApp 会在 API 处被拒绝,并返回
402。如果消息已被接受但扣费失败,该消息以rejected结束,且不计费。 - 付费 Email 套餐中的邮件在发送后不久扣费,因此余额可能短暂低于零。钱包没有余额或信用额度后,新邮件会被拒绝并返回
402,直到充值为止。 - 投递时产生的费用如果余额无法支付,则会跳过该费用,消息仍会送达收件人。
钱包余额耗尽会阻止后续花费,但不会将花费精确限制在余额以内。充值时请为接受后才扣费的发送预留余量。如果开启了自动充值,余额低于你设定的阈值时,钱包会从已保存的银行卡自动充值,此时余额本身不再限制代理能花费的金额。这些规则以账单与用量为准。
账单操作需要组织的账单权限 org:billing。API 密钥无法持有该权限,因此任何密钥都不能为钱包充值、更改套餐或读取用量。如果批准登录的人持有该权限并授予组织权限(组织所有者可以这样做),OAuth 令牌就能持有它。自助注册生成的凭据从一开始就持有该权限。为无人值守的代理提供限定范围的密钥,充值操作就仍由预算负责人掌控。
支付方式与钱包介绍充值、自动充值和余额不足提醒。
后续步骤
- 自助注册:在终端中创建代理使用的账户。
- 身份验证与 API 密钥:作用域、过期、轮换和吊销。
- 速率限制:适用于组织内所有密钥的请求限制。
- 为智能体分配专属电话号码和收件箱:智能体用于发送和接收消息的身份。