BroadRouter

Agenti di lunga durata: timeout, retry e checkpoint che reggono

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato · Aggiornato

Tratta ogni chiamata al modello come usa e getta e lo stato dell’agente come durevole. Imposta un timeout per chiamata, usa lo streaming per accorgerti degli stalli, ripeti 429, 5xx e stream interrotti con un backoff limitato, e dai una chiave di idempotenza a ogni tool con side effect. Salva la lista dei messaggi dopo ogni passo, così dopo un crash riparti dall’ultimo checkpoint e non dall’inizio.

Un agente che gira per cinque minuti può ignorare i guasti. Uno che gira per cinque ore incontrerà un timeout, un 429, uno stream interrotto e probabilmente un riavvio. Quasi tutte le guide sugli agenti di lunga durata vendono un motore di workflow. Potrebbe non servirti. Questo articolo raccoglie le cinque abitudini che tengono in vita per ore un semplice ciclo di agente, con codice per l’SDK Python di OpenAI.

Che cosa si rompe quando un agente gira per ore?

Guasto Come si presenta Abitudine che lo gestisce
Chiamata bloccata o lenta Nessuna risposta per minuti Timeout per chiamata, streaming
Rate limit o sovraccarico 429, 5xx Retry limitato con backoff
Stream interrotto La connessione si chiude prima di [DONE] Trattarlo come incompleto, ripetere la chiamata
Side effect duplicato Il tool gira due volte dopo un retry Chiavi di idempotenza
Crash del processo o deploy L’agente riparte dal passo 1 Un checkpoint per passo

1. Quanto può durare al massimo una chiamata?

Il README dell’SDK Python di OpenAI dice che per impostazione predefinita le richieste vanno in timeout dopo 10 minuti e alcuni errori vengono ripetuti due volte. Per un agente imposta tu entrambi i valori, così il comportamento non cambia a tua insaputa:

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
                timeout=300, max_retries=4)

Scegli il timeout in base ai dati. Registra per un giorno la durata di ogni chiamata e imposta il timeout ben sopra la chiamata riuscita più lenta. I prompt grandi ci mettono di più a partire, e i modelli di ragionamento pensano prima di scrivere. A circa 100 token al secondo, 8.000 token di output richiedono da soli più di un minuto. Aggiungi un budget di tempo reale separato per ogni task, così un ciclo che non si ferma non può girare tutta la notte.

2. Perché usare lo streaming in un agente di lunga durata?

Lo streaming ti dà un segnale mentre il modello lavora. Senza, una chiamata lenta e una connessione morta sembrano uguali finché non scatta il timeout. Con lo streaming vedi arrivare i chunk e ricevi anche l’uso dei token nell’ultimo chunk.

Le regole di streaming di BroadNet: leggi fino alla riga letterale data: [DONE]. Se la connessione si chiude prima, la risposta è incompleta. Registra l’X-Request-ID, poi decidi se fare una nuova richiesta. Guida completa allo streaming.

def call_streaming(messages, tools=None):
    parts, done = [], False
    stream = client.chat.completions.create(
        model="broadnet/glm-5.3", messages=messages, tools=tools, stream=True,
        stream_options={"include_usage": True}, max_tokens=8000)
    for chunk in stream:
        if chunk.choices and chunk.choices[0].finish_reason:
            done = True
        if chunk.choices and chunk.choices[0].delta.content:
            parts.append(chunk.choices[0].delta.content)
    if not done:
        raise IncompleteStream()   # retry the whole call
    return "".join(parts)

Questo abbozzo raccoglie solo il testo. Se fai streaming delle tool call, accumula anche delta.tool_calls per indice.

3. Che cosa conviene ripetere?

L’SDK ripete già errori di connessione, 408, 409, 429 e 5xx. Aggiungi un tuo retry sopra solo per ciò che l’SDK non vede, come uno stream incompleto:

  1. Ripeti: errori di connessione, 429, 5xx, stream incompleti. Usa un backoff esponenziale con jitter e un tetto, per esempio 4 tentativi.
  2. Correggi, non ripetere: 400, 401, 402, 403, 413, 422. Falliscono ogni volta nello stesso modo. Vedi codici di errore e quando ripetere.
  3. Dai un budget di retry a ogni task, non solo a ogni chiamata. Dieci passi che ripetono quattro volte ciascuno fanno quaranta chiamate in più.
  4. Passa a un altro provider quando i retry sono finiti. Se un’esecuzione deve sopravvivere a un disservizio del provider, sposta errori di connessione, 5xx e 429 da rate limit su un secondo provider. Failover delle API LLM mostra il codice client e un circuit breaker.

Con il pagamento a consumo, ogni retry è una nuova inferenza, fatturata di nuovo. Una chiave a consumo consente inoltre 30 richieste al minuto e 4 in parallelo, quindi le raffiche di retry raggiungono presto il rate limit; il calcolatore dei rate limit mostra quanto margine ha il tuo agente. L’articolo sulla gestione dei 429 tratta il backoff in dettaglio. Con un piano illimitato, i retry non costano nulla in più, ma occupano l’unico slot di richiesta della sessione mentre girano.

4. Come si rendono idempotenti le tool call?

Una chiamata al modello non ha side effect. Una tool call sì. Se l’agente va in crash dopo che send_invoice è stato eseguito ma prima che il passo sia salvato, l’agente riavviato lo invierà di nuovo.

Dai a ogni chiamata con side effect una chiave di idempotenza ricavata da task e passo, controllala prima di agire e salta la chiamata se è già registrata:

def run_side_effect(task_id, step, call, store):
    key = f"{task_id}:{step}:{call.id}"
    if store.done(key):
        return store.result(key)       # already ran: return the saved result
    result = execute(call)             # pass key to the API if it supports one
    store.save(key, result)
    return result

Molte API di pagamento e messaggistica accettano un header con la chiave di idempotenza. Quando è così, passa la tua.

5. Come si fa il checkpoint di un agente?

Salva dopo ogni passo completato: la lista dei messaggi, il numero del passo e le chiavi dei side effect. All’avvio carica l’ultimo checkpoint, se esiste.

def save_checkpoint(path, step, messages):
    tmp = path + ".tmp"
    with open(tmp, "w") as f:
        json.dump({"step": step, "messages": messages}, f)
    os.replace(tmp, path)   # atomic on the same filesystem

Scrivere su un file temporaneo e poi rinominarlo significa che un crash a metà scrittura non lascia mai un checkpoint a metà. Per sessioni molto lunghe salva anche un riassunto: sostituisci i turni vecchi con un breve riassunto, così un agente ripreso non ricarica una cronologia enorme. Così resti dentro la finestra di contesto, anche con 1.048.576 token su DeepSeek V4.1 Flash.

Una checklist prima di un’esecuzione notturna

  1. Timeout e max_retries impostati in modo esplicito sul client.
  2. Streaming attivo, con include_usage, e stream incompleti ripetuti.
  3. Un budget di retry per task e un limite di tempo reale.
  4. Chiavi di idempotenza su ogni tool che scrive, invia o paga.
  5. Un checkpoint dopo ogni passo, scritto in modo atomico.
  6. Log con numero del passo, durata, token e X-Request-ID.

Se fai girare più agenti in parallelo, leggi eseguire coding agent in parallelo a tariffa fissa e quanto costano i sistemi multi-agente.

Dove si colloca BroadNet Inference

BroadNet Inference usa lo streaming standard delle chat completions, restituisce un header X-Request-ID che puoi registrare e documenta quali errori ripetere, quindi gli schemi qui sopra funzionano così come sono. Per agenti che girano tutto il giorno, i piani illimitati tolgono il contatore di token su DeepSeek V4.1 Flash per $60 al mese per sessione, e così i retry diventano gratuiti. Tieni presente che un’ora Meteor termina un’ora dopo l’acquisto e una settimana Orbit dopo sette giorni, quindi un lavoro lungo deve finire entro il periodo oppure passare a una sessione Full Moon che si rinnova. I piani sono su inference.broadnet.ai/plans.

Domande frequenti

Che timeout devo impostare per le chiamate API LLM in un agente?

Abbastanza lungo per la chiamata legittima più lenta, abbastanza corto da intercettarne una bloccata. L’SDK Python di OpenAI usa 10 minuti come default. Molti agenti usano da 2 a 5 minuti per chiamata con lo streaming, più un limite di tempo reale separato per ogni task.

Quali errori delle API LLM deve ripetere un agente?

Ripeti errori di connessione, 429 e 5xx con backoff esponenziale limitato e jitter. Per 400, 401, 402, 403, 413 e 422 correggi la causa invece di ripetere. Su BroadNet registra anche l’header X-Request-ID di ogni errore.

È sicuro ripetere una chat completion?

La chiamata al modello in sé non ha side effect, quindi sì, ma è una nuova inferenza e con il pagamento a consumo si paga di nuovo. Il pericolo sta nei tool. Un passo ripetuto può mandare un’email due volte, a meno che il tool non usi una chiave di idempotenza.

Come faccio a riprendere un agente dopo un crash?

Salva la lista dei messaggi e il numero del passo dopo ogni passo completato, scrivi gli ID dei side effect prima di agire e ricaricali all’avvio. L’agente riparte dall’ultimo passo salvato.

Gli agenti di lunga durata hanno bisogno di un piano illimitato?

No, ma con il pagamento a consumo retry e contesti lunghi si sommano. Con i piani illimitati di BroadNet, DeepSeek V4.1 Flash non ha contatore di token, quindi i retry non costano nulla in più, anche se ogni sessione esegue comunque una richiesta alla volta.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity