Controlli per gli agenti: chiavi con ambito limitato, limiti di spesa e nuovi tentativi sicuri
Un agente che invia tramite Bird possiede una credenziale e spende il tuo saldo. Cinque controlli limitano ciò che può fare. Il primo è la credenziale stessa. Gli altri quattro funzionano solo finché la credenziale dell'agente non può modificarli, quindi inizia dalla credenziale.
| Controllo | Cosa limita | Cosa riceve il chiamante al raggiungimento del limite | Chi lo imposta |
|---|---|---|---|
| Credenziale | Le operazioni che l'agente può chiamare | 403 | La persona che crea la chiave o approva l'accesso |
| Chiave di idempotenza | Invii duplicati quando si riprova una richiesta | La risposta originale, restituita di nuovo | Il chiamante, a ogni richiesta |
| Lista dei paesi di destinazione SMS consentiti | I paesi verso cui può andare un invio SMS API | 422 SMSDestinationNotEnabled | Una credenziale con accesso in scrittura a sms_management |
| Limite di spesa giornaliero SMS | La spesa SMS verso un paese in un giorno | 422 SMSDestinationDailySpendExceeded | Una credenziale con accesso in scrittura a sms_management |
| Portafoglio prepagato | Spesa a consumo | 402 per SMS e WhatsApp. L'email a pagamento viene addebitata dopo l'invio. | Un proprietario dell'organizzazione o un amministratore della fatturazione |
La lista di destinazioni consentite e il limite di spesa giornaliero descritti in questa pagina si applicano a SMS. Verify e Voice hanno ciascuno le proprie impostazioni delle destinazioni, con una configurazione iniziale diversa. Email e WhatsApp non hanno né una lista di destinazioni consentite né un limite di spesa giornaliero, quindi lì a limitare un agente sono gli scope della credenziale e il portafoglio.
Scegli la credenziale affidata all'agente
Un agente chiama Bird con uno di due tipi di credenziale, che differiscono per la portata dell'accesso.
- Una chiave API (
bk_) ha gli scope che le assegni e appartiene a un solo spazio di lavoro. Non può emettere altre chiavi e non può accedere alla fatturazione, ai membri o alle impostazioni dell'organizzazione. Il tuo codice la invia come bearer token. La CLI e il server MCP locale (bird mcp) usano la chiave inBIRD_API_KEY, se è impostata, al posto di un accesso salvato. - Un token OAuth (
bt_) è ciò che la CLI e il server MCP ottengono dopo che una persona ha effettuato l'accesso. Ha i permessi approvati da quella persona, e mai più di quelli che la persona possiede. Possono includere la scrittura suapi_keys, la scrittura susms_managemente la fatturazione dell'organizzazione. Un agente con un token di questo tipo può emettere chiavi, abilitare paesi e alzare i limiti descritti in questa pagina.
Ciò che un token OAuth può fare dipende da come è stato creato:
bird auth loginrichiede l'accesso in sola lettura.--scoperichiede l'insieme che indichi, e--yolorichiede tutti i permessi che puoi delegare. Approvi il risultato nel browser.- Un client MCP ospitato può richiedere tutti i permessi che puoi delegare. La schermata di consenso ti permette di selezionare quali concedere. Prima di approvare, deseleziona quelli che non servono all'agente.
- Self-serve signup non prevede una schermata di consenso. La credenziale che crea ha tutte le autorizzazioni che il proprietario della nuova organizzazione può delegare, compresa la fatturazione dell'organizzazione.
Per un agente che funziona senza supervisione, crea una chiave API con scope limitati e assegnala all'agente. Riserva l'accesso più ampio alla persona che configura lo spazio di lavoro. Puoi revocare l'accesso di uno strumento in Profile > Connected apps. Chiavi API e token OAuth mette a confronto i due tipi di credenziale.
Limita ogni chiave ai prodotti di cui ha bisogno
Una chiave API ha un elenco di scope, ciascuno corrispondente a un'area di prodotto a livello read o write. Una chiave che invia solo SMS ha sms:write. Una richiesta al di fuori degli scope della chiave restituisce 403, quindi una chiave trapelata o usata in modo improprio raggiunge solo ciò che le hai concesso.
Tre proprietà di una chiave valgono indipendentemente dai suoi scope:
- Una chiave non può emettere un'altra chiave. Per emettere e ruotare le chiavi serve
api_keys:write, che non è disponibile per le chiavi API. Lo approva una persona in una sessione della dashboard o in un accesso CLI o MCP. - Una chiave non va oltre il suo spazio di lavoro. Non può accedere alla fatturazione, ai membri dell'organizzazione o alle impostazioni dell'organizzazione.
- Una chiave può scadere. Imposta
expires_atquando la crei: da quel momento la chiave restituisce401. Puoi ruotare o revocare una chiave in qualsiasi momento.
Crea una chiave nella dashboard oppure da un terminale. Un accesso CLI può assegnare a una chiave solo gli scope che possiede, quindi questo richiede sms:write oltre a api_keys:write:
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:writeAutenticazione e chiavi API contiene la tabella degli scope e tratta scadenza, rotazione e revoca.
Riprovare un invio senza inviare due volte
Un agente che perde una risposta non può sapere se la sua richiesta è stata accettata. Invia un'intestazione Idempotency-Key con un valore univoco per ogni invio previsto e, quando l'esito è sconosciuto, ripeti la stessa richiesta con la stessa chiave. Bird restituisce la risposta originale e accetta il messaggio una sola volta. Una risposta riprodotta contiene Idempotency-Replay: true.
La garanzia è un'unica operazione accettata per chiave entro la finestra di conservazione. Copre l'accettazione da parte di API. La consegna al telefono viene riportata separatamente, tramite lo stato del messaggio e i relativi eventi.
Gli SDK generano una chiave per ogni chiamata che modifica dati e la riutilizzano per i propri nuovi tentativi automatici. Su CLI, passa --idempotency-key. Idempotenza descrive il formato della chiave, la finestra di conservazione e cosa succede quando una chiave viene riutilizzata con una richiesta diversa.
Consenti ogni paese di destinazione SMS
La allowlist delle destinazioni SMS nega tutto per impostazione predefinita. Un invio tramite SMS API raggiunge un paese abilitato nella lista, altrimenti viene rifiutato con 422 SMSDestinationNotEnabled prima che venga determinato un mittente, quindi nessun messaggio viene accettato. Un agente indirizzato verso un paese inatteso viene respinto. Questo vale per gli invii dal tuo codice, da bird sms send e dallo strumento sms_send MCP.
I codici di verifica non usano questa lista. Verify ha una propria lista in Verify destinations, dove ogni paese è abilitato fin dall'inizio. Una credenziale con permesso di scrittura verify può quindi inviare un codice tramite SMS a un paese bloccato da questa allowlist. Se l'agente dispone di verify, disattiva anche in quella pagina i paesi che non servi.
Abilita un paese in SMS > Destinations, con bird sms destinations update oppure con lo strumento sms_destinations_update MCP:
bird sms destinations update --destination NL=truePer modificare la allowlist serve lo scope sms_management a livello write. Una credenziale che dispone solo di sms può inviare ai paesi abilitati, ma non può abilitarne altri. Assegna all'agente che invia sms e riserva sms_management alla credenziale che configura lo spazio di lavoro.
Invio di SMS spiega come è impostata inizialmente la allowlist e come viene aggiunto il paese di origine.
Limita la spesa giornaliera SMS per ogni paese
Ogni paese di destinazione può avere un limite di spesa giornaliero, nella valuta del tuo wallet. Quando la spesa del giorno verso quel paese raggiunge il limite, i nuovi messaggi diretti lì vengono rifiutati con 422 SMSDestinationDailySpendExceeded fino alla mezzanotte UTC. Un limite pari a zero blocca il paese.
I codici di verifica inviati tramite SMS rientrano nel limite. Quando il limite viene raggiunto, Verify smette di inviare codici tramite SMS verso quel paese e prova il canale successivo abilitato per esso. Se non resta alcun canale, la verifica non riesce con 422 NoAvailableChannel.
Imposta un limite negli stessi tre punti della allowlist. Questo comando abilita i Paesi Bassi e li limita a 25 EUR al giorno, in uno spazio di lavoro il cui wallet è in EUR:
bird sms destinations update --destination "NL=true;25EUR"Il limite non è esatto. Una modifica a un limite impiega fino a un minuto per applicarsi agli invii. La spesa viene conteggiata quando un messaggio viene addebitato, quindi i messaggi già accettati possono portare il totale del giorno oltre il limite, per l'importo del loro costo. Imposta il limite tenendo conto di questo margine. bird sms destinations list mostra il limite di ogni paese e l'utilizzo del giorno rispetto a quel limite.
Per impostare un limite serve lo stesso accesso in scrittura sms_management richiesto per l'allowlist, quindi una credenziale che ha solo sms non può aumentare il proprio limite. Invio di SMS riporta le regole complete.
Limita la spesa totale con il wallet prepagato
Gli invii a consumo attingono al wallet prepagato della tua organizzazione. Cosa succede quando il saldo non copre un invio dipende dal canale:
- SMS e WhatsApp vengono rifiutati dalla API con
402. Un messaggio già accettato il cui addebito non va a buon fine termina inrejectede non viene fatturato. - Le email con un piano Email a pagamento vengono addebitate poco dopo l'invio, quindi il saldo può scendere brevemente sotto zero. Quando nel wallet non restano né saldo né credito, le nuove email vengono rifiutate con
402finché non aggiungi fondi. - Una tariffa applicata alla consegna che il saldo non copre viene saltata, e il messaggio raggiunge comunque il destinatario.
Un wallet vuoto blocca ulteriori spese, ma non limita la spesa esattamente al saldo. Ricaricalo con un margine per gli invii addebitati dopo essere stati accettati. Se la ricarica automatica è attiva, il wallet si ricarica da una carta salvata quando il saldo scende sotto la tua soglia, quindi il saldo da solo non limita più quanto può spendere un agente. Fatturazione e utilizzo è la fonte di queste regole.
Le operazioni di fatturazione richiedono il permesso di fatturazione dell'organizzazione, org:billing. Una chiave API non può averlo, quindi nessuna chiave può ricaricare il wallet, cambiare piano o leggere l'utilizzo. Un token OAuth può averlo se la persona che approva l'accesso lo possiede e concede i permessi dell'organizzazione, come può fare il proprietario di un'organizzazione. La credenziale creata con la registrazione self-service lo possiede fin dall'inizio. Assegna a un agente non supervisionato una chiave con ambiti limitati, così l'aggiunta di fondi resta alle persone responsabili del budget.
Metodi di pagamento e wallet tratta ricariche, ricarica automatica e avvisi di saldo basso.
Passaggi successivi
- Registrazione self-service: crea da terminale l'account in cui lavora un agente.
- Autenticazione e chiavi API: ambiti, scadenza, rotazione e revoca.
- Limiti di frequenza: i limiti di richieste che si applicano a tutte le chiavi della tua organizzazione.
- Assegna a un agente un numero di telefono e una casella di posta propri: le identità con cui un agente invia e riceve.
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.