---
title: "Controles de agentes: chaves com escopo, limites de gastos e novas tentativas seguras"
description: "Como o Bird limita o que um agente de IA pode fazer: chaves API com escopo, envios idempotentes, destinos SMS bloqueados por padrão, limites diários de gastos por país e uma carteira pré-paga."
canonical: "https://bird.com/pt-br/documentacao/ai/agent-controls"
---

# Controles de agentes: chaves com escopo, limites de gastos e novas tentativas seguras

Um agente que envia pelo Bird tem uma credencial e gasta o seu saldo. Cinco controles limitam o que ele pode fazer. O primeiro é a própria credencial. Os outros quatro só valem enquanto a credencial do agente não puder alterá-los, então comece pela credencial.

| Controle                                                                        | O que ele limita                                    | O que quem chama recebe ao atingir o limite                          | Quem o define                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Credencial](#escolha-a-credencial-que-o-agente-usa)                            | As operações que o agente pode chamar               | `403`                                                                | A pessoa que cria a chave ou aprova o login                    |
| [Chave de idempotência](#tente-novamente-um-envio-sem-enviar-duas-vezes)        | Envios duplicados quando uma solicitação é repetida | A resposta original, reproduzida novamente                           | Quem faz a chamada, em cada solicitação                        |
| [Lista de destinos permitidos de SMS](#permita-cada-país-de-destino-de-sms)     | Os países para os quais um envio API de SMS pode ir | `422 SMSDestinationNotEnabled`                                       | Uma credencial com permissão de escrita em `sms_management`    |
| [Limite diário de gastos de SMS](#limite-o-gasto-diário-com-sms-para-cada-país) | Gastos de SMS com um país em um dia                 | `422 SMSDestinationDailySpendExceeded`                               | Uma credencial com permissão de escrita em `sms_management`    |
| [Carteira pré-paga](#limite-o-gasto-total-com-a-carteira-pré-paga)              | Gastos pré-pagos por uso                            | `402` para SMS e WhatsApp. O email pago é cobrado depois de enviado. | Um proprietário da organização ou administrador de faturamento |

A lista de destinos permitidos e o limite diário de gastos desta página se aplicam a SMS. [Verify](/docs/guides/verify/destinations) e [Voice](/docs/guides/voice/destinations) têm cada um suas próprias configurações de destino, com um estado inicial diferente. Email e WhatsApp não têm lista de destinos permitidos nem limite diário de gastos, então são os escopos da credencial e a carteira que limitam um agente nesses canais.

## Escolha a credencial que o agente usa

Um agente chama Bird com um de dois tipos de credencial. Eles diferem no alcance que têm.

- **Uma chave API** (`bk_`) tem os escopos que você atribui a ela e pertence a um único espaço de trabalho. Ela não pode emitir outra chave nem acessar o faturamento, os membros ou as configurações da organização. Seu código a envia como bearer token. O CLI e o servidor MCP local (`bird mcp`) usam a chave em `BIRD_API_KEY` quando ela está definida, em vez de um login armazenado.
- **Um token OAuth** (`bt_`) é o que o CLI e o servidor MCP guardam depois que uma pessoa faz login. Ele tem as permissões que essa pessoa aprovou, nunca mais do que ela própria tem. Elas podem incluir escrita em `api_keys`, escrita em `sms_management` e o faturamento da organização. Um agente com um token assim pode emitir chaves, habilitar países e aumentar os limites desta página.

O quanto um token OAuth pode fazer depende de como ele foi criado:

- **`bird auth login`** solicita acesso somente leitura. `--scope` solicita o conjunto que você indicar, e `--yolo` solicita todas as permissões que você pode delegar. Você aprova o resultado no navegador.
- **Um cliente MCP hospedado** pode solicitar todas as permissões que você pode delegar. A tela de consentimento permite selecionar quais conceder. Desmarque as que o agente não precisa antes de aprovar.
- **[Cadastro self-service](/docs/ai/self-serve-signup)** não tem tela de consentimento. A credencial que ele cria tem todas as permissões que o proprietário da nova organização pode delegar, incluindo o faturamento da organização.

Para um agente que roda sem supervisão, crie uma chave API com escopo restrito e entregue essa chave ao agente. Deixe o login mais amplo com a pessoa que configura o espaço de trabalho. Você pode revogar o login de uma ferramenta em **Profile** > [**Connected apps**](https://bird.com/dashboard/profile/connected-apps). [Chaves API e tokens OAuth](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) compara os dois tipos de credencial.

## Limite o escopo de cada chave aos produtos de que ela precisa

Uma chave API tem uma lista de escopos, cada um uma área de produto no nível `read` ou `write`. Uma chave que só envia SMS tem `sms:write`. Uma solicitação fora dos escopos da chave retorna `403`, então uma chave vazada ou mal utilizada alcança apenas o que você concedeu a ela.

Três propriedades valem para qualquer chave, sejam quais forem seus escopos:

- **Uma chave não pode emitir outra chave.** Emitir e rotacionar chaves exige `api_keys:write`, que não está disponível para chaves API. Uma pessoa aprova isso em uma sessão do dashboard ou em um login do CLI ou do MCP.
- **Uma chave fica restrita ao seu espaço de trabalho.** Ela não alcança o faturamento, os membros da organização nem as configurações da organização.
- **Uma chave pode expirar.** Defina `expires_at` ao criá-la, e a chave passa a retornar `401` depois desse momento. Você pode rotacionar ou revogar uma chave a qualquer momento.

Crie uma chave no dashboard ou pelo terminal. Um login do CLI só pode atribuir a uma chave os escopos que ele mesmo tem, por isso este solicita `sms:write` além de `api_keys:write`:

```bash
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write
```

[Autenticação e chaves API](/docs/guides/authentication) traz a tabela de escopos e explica expiração, rotação e revogação.

## Tente novamente um envio sem enviar duas vezes

Um agente que perde uma resposta não consegue saber se sua solicitação foi aceita. Envie um cabeçalho `Idempotency-Key` com um valor único para cada envio pretendido e, quando o resultado for desconhecido, repita a mesma solicitação com a mesma chave. O Bird retorna a resposta original e aceita a mensagem uma única vez. Uma resposta reproduzida contém `Idempotency-Replay: true`.

A garantia é de uma operação aceita por chave dentro da janela de retenção. Ela cobre a aceitação pela API. A entrega ao telefone é informada separadamente, pelo status da mensagem e pelos seus eventos.

Os SDKs geram uma chave para cada chamada que altera dados e a reutilizam nas suas novas tentativas automáticas. Na CLI, passe `--idempotency-key`. [Idempotência](/docs/guides/idempotency) explica o formato da chave, a janela de retenção e o que acontece quando uma chave é reutilizada com uma solicitação diferente.

## Permita cada país de destino de SMS

A lista de permissões de destinos de SMS nega por padrão. Um envio pela SMS API vai para um país habilitado na lista ou é rejeitado com `422 SMSDestinationNotEnabled` antes de o remetente ser definido, de modo que nenhuma mensagem é aceita. Um agente direcionado a um país inesperado é recusado. Isso vale para envios do seu próprio código, de `bird sms send` e da ferramenta `sms_send` MCP.

Os códigos de verificação não usam essa lista. O Verify tem sua própria lista em [Verify destinations](/docs/guides/verify/destinations), onde todos os países começam habilitados. Por isso, uma credencial com permissão de escrita em `verify` pode enviar um código por SMS para um país que esta lista de permissões bloqueia. Se o agente tiver `verify`, desative também nessa página os países que você não atende.

Habilite um país em [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations), com `bird sms destinations update` ou com a ferramenta `sms_destinations_update` MCP:

```bash
bird sms destinations update --destination NL=true
```

Para alterar a lista de permissões, é preciso o escopo `sms_management` no nível `write`. Uma credencial que tem apenas `sms` pode enviar para os países habilitados, mas não pode habilitar outros. Dê ao agente que envia `sms` e reserve `sms_management` para a credencial que configura o espaço de trabalho.

[Envio de SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) explica como a lista de permissões começa e como o país de origem é adicionado.

## Limite o gasto diário com SMS para cada país

Cada país de destino pode ter um limite de gasto diário, na moeda da sua carteira. Quando o gasto do dia com esse país atinge o limite, novas mensagens para ele são recusadas com `422 SMSDestinationDailySpendExceeded` até a meia-noite UTC. Um limite de zero bloqueia o país.

Os códigos de verificação enviados por SMS contam para o limite. Quando o limite é atingido, o Verify para de enviar códigos por SMS para esse país e tenta o próximo canal habilitado para ele. Quando não resta nenhum canal, a verificação falha com `422 NoAvailableChannel`.

Defina um limite nos mesmos três lugares da lista de permissões. Este comando habilita a Holanda e a limita a 25 EUR por dia, em um espaço de trabalho cuja carteira está em EUR:

```bash
bird sms destinations update --destination "NL=true;25EUR"
```

O limite não é exato. Uma alteração em um limite leva até um minuto para valer no envio. O gasto é contabilizado quando a mensagem é cobrada, então mensagens já aceitas podem levar o total do dia além do limite pelo valor que custam. Planeje o limite com essa margem. `bird sms destinations list` mostra o limite de cada país e o uso do dia em relação a ele.

Definir um limite exige o mesmo acesso de escrita `sms_management` que a allowlist, então uma credencial que tem apenas `sms` não consegue aumentar o próprio limite. [Envio de SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) traz as regras completas.

## Limite o gasto total com a carteira pré-paga

Envios pré-pagos por uso são debitados da carteira pré-paga da sua organização. O que acontece quando o saldo não cobre um envio depende do canal:

- **SMS e WhatsApp** são recusados na API com `402`. Uma mensagem que já tinha sido aceita quando a cobrança falha termina como `rejected` e não é cobrada.
- **Email em um plano pago de Email** é cobrado pouco depois do envio, então o saldo pode ficar negativo por um breve período. Quando a carteira não tem mais saldo nem crédito, novos emails são recusados com `402` até que fundos sejam adicionados.
- **Uma tarifa cobrada na entrega** que o saldo não cobre é ignorada, e a mensagem ainda chega ao destinatário.

Uma carteira vazia impede novos gastos, mas não limita o gasto exatamente ao saldo. Mantenha nela uma margem para envios cobrados depois de aceitos. Se a recarga automática estiver ativada, a carteira é recarregada a partir de um cartão salvo quando o saldo fica abaixo do seu limite mínimo, então o saldo sozinho deixa de limitar quanto um agente pode gastar. [Faturamento e uso](/docs/guides/billing-and-usage#the-wallet) é a fonte dessas regras.

Operações de faturamento exigem a permissão de faturamento da organização, `org:billing`. Uma chave API não pode ter essa permissão, então nenhuma chave consegue recarregar a carteira, mudar de plano ou ler o uso. Um token OAuth pode tê-la quando a pessoa que aprova o login a possui e concede permissões da organização, como um proprietário da organização pode fazer. A credencial criada no cadastro self-service tem essa permissão desde o início. Dê a um agente que roda sem supervisão uma chave com escopo, e a adição de fundos continua com as pessoas responsáveis pelo orçamento.

[Métodos de pagamento e carteira](/docs/knowledge-base/billing/payment-methods-wallet) aborda recargas, recarga automática e alertas de saldo baixo.

## Próximos passos

- [Cadastro self-service](/docs/ai/self-serve-signup): crie pelo terminal a conta em que um agente trabalha.
- [Autenticação e chaves API](/docs/guides/authentication): escopos, expiração, rotação e revogação.
- [Limites de requisições](/docs/guides/rate-limits): os limites de requisições que se aplicam a todas as chaves da sua organização.
- [Dê a um agente o próprio número de telefone e a própria caixa de entrada](/docs/ai/agent-number-and-inbox): as identidades com as quais um agente envia e recebe mensagens.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)
