Un tetto alla spesa dei tuoi agenti AI, prima che parta
Limiti al giorno e al mese per progetto, chiave, agente, cliente e sessione. Quando un limite è raggiunto, GuardrailX ferma la chiamata prima del provider, quindi non costa nulla, e ti avvisa.
Piano Free per sempre: 5000 richieste al mese, senza carta di credito.
La fattura arriva dopo. La spesa no.
Il provider ti dà un totale e un limite per tutto l’account. Ma gli agenti lavorano da soli, a ogni ora e per clienti diversi.
Spese di notte
I lavori pianificati girano quando nessuno guarda. Te ne accorgi la mattina, dal cruscotto del provider.
Un limite per tutto l’account
Il tetto del provider vale per tutti: un agente che esagera consuma il budget degli altri, e dei tuoi clienti.
Chi ha speso?
Quale agente, quale cliente, quale sessione? Dal provider arriva un numero solo.
Come funziona
Ogni chiamata passa da GuardrailX, che conta la spesa vera con i listini dei provider e controlla i limiti prima di inoltrarla.
-
1
Imposti i tetti
Al giorno e al mese per progetto, chiave, agente e cliente, e un tetto per sessione. Oppure parti da un’impostazione pronta (Prudente, Equilibrato, Solo avvisi), calcolata sulla spesa degli ultimi 7 giorni.
-
2
Prenota il costo prima di inoltrare
Per non sforare con le chiamate in corso, prima di inoltrare prenota il costo stimato, con tutto il max_tokens chiesto, e a fine risposta lo sostituisce con quello vero.
-
3
Ferma la chiamata al limite
Raggiunto il limite, la chiamata riceve un 429 nel formato del provider con il motivo (per esempio agent_daily_limit) e non arriva al provider.
-
4
Ti avvisa prima e dopo
Un avviso quando la spesa arriva alla soglia che scegli (80% di base) e uno quando una chiamata si ferma: per email, webhook (Slack, Discord) o Telegram.
-
5
Si accorge dei picchi
Ogni 5 minuti confronta la spesa dell’ultima ora di ogni agente con la sua media dei 7 giorni prima. Se la supera di molto ti avvisa, con un link per mettere in pausa l’agente o il progetto.
Cosa riceve il tuo codice
Un errore 429 nel formato del provider (OpenAI, Anthropic o Gemini), che gli SDK ufficiali leggono come qualsiasi altro errore.
- Il motivo nell’intestazione x-guardrailx-blocco e nel codice dell’errore: project_daily_limit, key_monthly_limit, agent_daily_limit, customer_monthly_limit, session_limit…
- x-should-retry: false: gli SDK di OpenAI e Anthropic non ritentano da soli una chiamata che non può passare.
- Per i limiti per agente, cliente e sessione bastano le intestazioni X‑GuardrailX‑Agent, ‑Customer e ‑Session.
# La risposta quando un agente supera il suo limite del giorno
HTTP/1.1 429 Too Many Requests
x-should-retry: false
x-guardrailx-blocco: agent_daily_limit
{
"error": {
"type": "guardrail_error",
"code": "agent_daily_limit",
"message": "GuardrailX: raggiunto il limite giornaliero dell’agente «agente-fatture» (speso $20.03 su $20.00). Chiamate bloccate fino a domani."
}
}
// Node: le intestazioni per i limiti per agente, cliente e sessione
const client = new OpenAI({
baseURL: 'https://agent.guardrailx.ai/openai/v1',
apiKey: process.env.GUARDRAILX_KEY,
defaultHeaders: {
'X-GuardrailX-Agent': 'agente-fatture',
'X-GuardrailX-Customer': cliente.id,
'X-GuardrailX-Session': lavoro.id
}
});
Un tetto a ogni livello
Al giorno e al mese, la sessione con un tetto unico. Vale sempre il limite più stretto; un campo vuoto vuol dire nessun limite.
| Livello | Vale per |
|---|---|
| Progetto | Tutte le chiamate del progetto |
| Chiave gr_ | Le chiamate fatte con quella chiave |
| Agente | Le chiamate con X‑GuardrailX‑Agent |
| Cliente (piano Agency) | Le chiamate con X‑GuardrailX‑Customer |
| Sessione | Ogni valore di X‑GuardrailX‑Session, cioè ogni esecuzione |
Solo i modelli che hai scelto
Un limite di spesa aiuta poco se un agente finisce per sbaglio su un modello molto caro. Con i modelli ammessi decidi quali modelli possono usare gli agenti del progetto.
- Scegli i modelli dall’elenco, anche di provider diversi, e attiva «Ammetti solo i modelli dell’elenco».
- Si controlla il modello finale, dopo le regole di instradamento; le versioni con la data contano come il loro modello.
- Vale per ogni chiamata che nomina un modello, anche embedding e trascrizioni.
| Se un agente chiede un modello non ammesso | Quanto costa |
|---|---|
| Blocca la chiamata · 429 model_not_allowed | Niente: la chiamata non parte. |
| Usa il modello di default del provider · la risposta porta x‑guardrailx‑modello‑originale | Il costo del modello di default; in Richieste vedi «chiesto … → usato …». |
Domande sui limiti di spesa
Cosa succede quando un agente supera il limite?
La chiamata si ferma prima di partire, quindi non costa nulla. L’agente riceve un 429 nel formato del provider, con il motivo nell’intestazione x-guardrailx-blocco (per esempio agent_daily_limit) e x-should-retry: false, e tu ricevi un avviso.
Se ho più limiti, quale vale?
Il più stretto. Un campo vuoto vuol dire nessun limite. La spesa di agenti e clienti si conta comunque, anche senza limite, così un limite messo a metà mese parte già dalla spesa vera.
Le chiamate in corso possono sforare il limite?
Prima di inoltrare, GuardrailX prenota il costo stimato della chiamata con tutto il max_tokens chiesto (senza, il massimo del modello) e a fine risposta lo sostituisce con quello vero. Con valori molto alti, vicino al limite passano meno chiamate insieme. Con un limite di spesa, una chiamata di cui non riconosce il modello non parte (model_not_recognized).
Quando ricevo un avviso?
Quando la spesa arriva alla soglia che scegli (80% del limite di base) e quando una chiamata si ferma. Ogni avviso arriva una volta sola, per email, webhook (Slack, Discord o un tuo indirizzo che riceve JSON) e Telegram, se collegato.
Come funziona l’allarme anomalie?
Ogni 5 minuti confronta la spesa dell’ultima ora di ogni agente con la sua media oraria dei 7 giorni prima. Se supera il fattore che scegli (per esempio 5 volte) ricevi un avviso con un pulsante per mettere in pausa. La spesa minima evita avvisi per pochi centesimi.
Posso fermare tutto subito?
Sì. La pausa del progetto ferma ogni chiamata (project_paused) finché non riprendi; quella di un agente ferma solo le sue (agent_paused). Gli avvisi contengono un link firmato per mettere in pausa senza aprire la dashboard.
Perché non bastano i limiti del provider?
Valgono per tutto l’account, non per agente, cliente o sessione, e spesso intervengono quando la spesa è già fatta. GuardrailX controlla ogni chiamata prima di inoltrarla, al livello che scegli tu.
Funzioni collegate
Blocco dei loop
Riconosce la stessa richiesta ripetuta in pochi secondi e la blocca, con un errore chiaro che il tuo codice può gestire.
Instradamento dei modelli
Regole per modello e per agente: manda a un modello più economico il lavoro che non ha bisogno di quello più caro, con riserva automatica.
Registro di ogni chiamata
Costo, token (anche quelli di ragionamento), modello, agente, sessione, tentativi. Filtri, grafici ed esportazione CSV.
Metti un tetto alla spesa prima del prossimo loop.
Inizia con il piano Free: 5000 richieste al mese, senza carta e senza scadenza.