Ferma gli agenti AI in loop prima che spendano
Quando un agente ripete la stessa chiamata, GuardrailX se ne accorge e la blocca prima del provider: di base, alla sesta chiamata uguale in 60 secondi quel lavoro si ferma per 5 minuti. Le ripetizioni bloccate non costano nulla.
Piano Free per sempre: 5000 richieste al mese, senza carta di credito.
Un loop non fa rumore. Lo vedi in fattura.
Gli agenti ritentano da soli, e basta un errore di logica per mandare la stessa richiesta centinaia di volte. I limiti della console del provider valgono per tutto l’account e arrivano quando la spesa è già fatta.
Lo strumento che risponde sempre uguale
Una ricerca che dà sempre «nessun risultato» e l’agente che riprova con la stessa domanda, all’infinito.
L’errore ritentato senza cambiare nulla
Il modello rifiuta un formato e l’agente rimanda lo stesso corpo. Gli SDK aggiungono i loro tentativi automatici.
Di notte, senza nessuno a guardare
I lavori pianificati girano quando il team dorme. Un loop alle 3 di notte va avanti fino al mattino.
Come lo riconosce
Ogni chiamata passa da GuardrailX prima di arrivare al provider. Il controllo è in memoria e non rallenta le chiamate normali.
-
1
Calcola l’impronta della chiamata
Una firma che tiene conto del modello, degli ultimi due messaggi e degli allegati. Prima toglie quello che cambia a ogni giro senza cambiare la domanda: date, orari, uuid, id e numeri lunghi.
-
2
Guarda il circuito
Il circuito è la chiave gr_ più, se c’è, la sessione (X-GuardrailX-Session). Ogni esecuzione con la sua sessione si conta da sola: un agente in loop non ferma gli altri lavori con la stessa chiave.
-
3
Conta le ripetizioni
Se nella finestra (60 secondi di base) sono già passate 5 chiamate con la stessa impronta, la sesta si ferma con loop_detected.
-
4
Mette in pausa il circuito
Per 5 minuti ogni chiamata di quel circuito riceve loop_paused, anche se è diversa. Le altre sessioni e le altre chiavi lavorano normalmente.
-
5
Ti avvisa
Ricevi un avviso per email, webhook (Slack, Discord) o Telegram con l’agente, la sessione e quante chiamate uguali. Dalla scheda Limiti puoi riaprire il circuito prima della fine della pausa.
Cosa riceve il tuo codice
Un errore 429 nel formato del provider (OpenAI, Anthropic o Gemini): gli SDK ufficiali lo leggono come qualsiasi altro errore.
- Il codice loop_detected, poi loop_paused finché dura la pausa.
- L’intestazione Retry-After con i secondi di pausa rimasti.
- x-should-retry: false: gli SDK di OpenAI e Anthropic non ritentano da soli, così il loop non continua con i tentativi automatici.
# La risposta di GuardrailX alla sesta chiamata uguale
HTTP/1.1 429 Too Many Requests
retry-after: 300
x-should-retry: false
x-guardrailx-blocco: loop_detected
{
"error": {
"type": "guardrail_error",
"code": "loop_detected",
"message": "GuardrailX: probabile loop dell’agente (agente-fatture ripete la stessa richiesta). Chiamate sospese per 300 secondi."
}
}
// Node: fermi l’esecuzione invece di riprovare
const client = new OpenAI({
baseURL: 'https://agent.guardrailx.ai/openai/v1',
apiKey: process.env.GUARDRAILX_KEY,
defaultHeaders: { 'X-GuardrailX-Session': run.id }
});
try {
await client.chat.completions.create(richiesta);
} catch (e) {
if (e.code === 'loop_detected' || e.code === 'loop_paused') {
return run.stop('loop');
}
throw e;
}
Quando due chiamate sono «uguali»
Conta la domanda, non i dettagli che cambiano a ogni giro. I numeri piccoli restano: «pagina 2» e «pagina 3» sono chiamate diverse.
| Due chiamate | Per il blocco dei loop |
|---|---|
| «Controlla l’ordine 12345 alle 10:00» e «Controlla l’ordine 67890 alle 10:05» | Uguali: cambiano solo il numero d’ordine e l’ora |
| «Estrai i dati della pagina 2» e «Estrai i dati della pagina 3» | Diverse |
| Lo stesso testo a due modelli diversi | Diverse |
| Gli stessi ultimi due messaggi, con una conversazione più lunga | Uguali |
| Un giro che cambia solo un piccolo contatore («tentativo 3», «tentativo 4») | Diverse, a meno che tu mandi il passo in X-GuardrailX-Step: stessa sessione e stesso passo sono la stessa chiamata |
Decidi tu quando due chiamate sono «la stessa»
Oltre al blocco dei loop puoi scrivere regole di unicità sui campi che il tuo codice manda a GuardrailX nelle intestazioni (X‑GuardrailX‑Session, ‑Step, ‑Agent, ‑Customer, ‑User, ‑Feature), sul modello e sul prompt. Si accendono dalla scheda Limiti, sono spente di base e il blocco dei loop resta com’è.
- Uguali se hanno gli stessi campi: per esempio sessione e passo, anche se il prompt cambia un po’.
- Al massimo un certo numero di volte in un intervallo, da 1 secondo a 24 ore.
- Solo sulle chiamate con un certo valore di un campo, anche con un prefisso (fatt*).
- Oltre il limite: rifiuta la chiamata (duplicate_call) o mette in pausa tutto il gruppo, anche con un prompt diverso.
- Mentre la scrivi, l’anteprima dice quante chiamate degli ultimi 7 giorni avrebbe fermato.
// I campi su cui scrivere le regole
const client = new OpenAI({
baseURL: 'https://agent.guardrailx.ai/openai/v1',
apiKey: process.env.GUARDRAILX_KEY,
defaultHeaders: {
'X-GuardrailX-Session': lavoro.id,
'X-GuardrailX-Step': `pagina-${n}`,
'X-GuardrailX-Feature': 'fatture',
'X-GuardrailX-Customer': cliente.id
}
});
# La risposta quando una regola ferma la chiamata
HTTP/1.1 429 Too Many Requests
x-should-retry: false
x-guardrailx-regola: Una volta per sessione
{ "error": { "code": "duplicate_call", … } }
| Regola | Cosa ottieni |
|---|---|
| Una volta per passo · sessione + passo, una volta in 24 ore | Ogni pagina di un file si elabora una volta sola, anche se il client la rimanda con un prompt un po’ diverso. |
| Una volta per sessione · sessione + feature, solo la feature «fatture» | La fattura si genera una volta per sessione, qualunque sia il prompt. |
| Stesso prompt per cliente · cliente + prompt, per esempio 3 volte in 10 minuti, poi pausa | Il cliente che ripete la stessa domanda si ferma; gli altri clienti continuano. |
Domande sul blocco dei loop
Come riconosce un loop?
Se nello stesso circuito (la chiave gr_ e, se c’è, la sessione) arriva più volte la stessa richiesta, di base 5 volte in 60 secondi, la successiva si ferma con loop_detected e il circuito resta in pausa per 5 minuti. Ripetizioni, finestra e pausa si regolano per progetto.
Posso decidere io quando due chiamate sono uguali?
Sì, con le regole di unicità della scheda Limiti. Scegli i campi che il tuo codice manda nelle intestazioni X-GuardrailX (sessione, passo, agente, cliente, utente, feature), il modello o il prompt, quante volte possono passare e in quanto tempo. Oltre il limite la chiamata riceve un 429 duplicate_call, oppure il gruppo va in pausa.
E se una chiamata ripetuta è voluta?
Manda una sessione diversa per ogni lavoro (X-GuardrailX-Session): i circuiti si contano a parte. Oppure alza le ripetizioni ammesse o accorcia la finestra dalla scheda Limiti, o spegni il blocco dei loop per quel progetto.
Un errore del provider conta come ripetizione?
No. Una chiamata fallita per colpa del provider (429, errori 5xx, connessione caduta, nessuna risposta in tempo) non si conta: il tuo codice può ritentarla senza sembrare un loop. Le risposte 4xx invece contano: rimandare lo stesso corpo che il provider rifiuta è un loop.
Il blocco ferma tutti i miei agenti?
No, solo il circuito in loop. Con X-GuardrailX-Session ogni esecuzione si conta a parte, e con X-GuardrailX-Customer anche ogni tuo cliente: gli altri continuano a lavorare. Senza sessione il circuito è tutta la chiave gr_.
Posso cambiare le soglie?
Sì, per ogni progetto nella scheda Limiti: quante chiamate uguali, in quanti secondi e quanto dura la pausa. Il blocco dei loop c’è in tutti i piani, anche in Free.
Le chiamate bloccate costano?
No. Si fermano prima del provider, quindi non consumano token. Nel registro delle richieste le vedi come bloccate, con la stima di quanto sarebbero costate.
Funzioni collegate
Limiti di spesa a ogni livello
Per progetto, chiave, agente e sessione, al giorno e al mese. Superato il limite, la chiamata si ferma prima di costare.
Allarme anomalie e pausa
Se la spesa dell’ultima ora esce dalla norma ricevi un avviso, con un link per mettere in pausa il progetto o l’agente.
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.