---
title: "Agenti AI di lunga durata: timeout, retry e checkpoint"
description: "Tenere in vita per ore un agente LLM: timeout per chiamata, streaming per scoprire gli stalli, retry sicuri, side effect idempotenti e un checkpoint a ogni passo."
url: https://broadrouter.com/it/blog/long-running-agents-timeouts-retries/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/blog/long-running-agents-timeouts-retries/) (aggiornato il 2026-11-16).

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

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato 2026-11-14 · Aggiornato 2026-11-16

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.

## Punti chiave

-   L’SDK Python di OpenAI va in timeout dopo 10 minuti e per impostazione predefinita ripete due volte. Per gli agenti imposta entrambi i valori in modo esplicito.
-   Uno stream che termina prima di data \[DONE\] è una risposta incompleta. Ripeterlo è una nuova inferenza, fatturata di nuovo con il pagamento a consumo.
-   Le chiamate al modello si possono ripetere senza rischi. I side effect dei tool no, a meno che non abbiano una chiave di idempotenza.
-   Fai un checkpoint dopo ogni passo completato: la lista dei messaggi, il numero del passo e gli ID dei side effect già eseguiti.
-   In una sessione di un piano, i retry non costano nulla in più, ma occupano l’unico slot di richiesta mentre girano.

**In questa pagina**

1.  Che cosa si rompe quando un agente gira per ore?
2.  1\. Quanto può durare al massimo una chiamata?
3.  2\. Perché usare lo streaming in un agente di lunga durata?
4.  3\. Che cosa conviene ripetere?
5.  4\. Come si rendono idempotenti le tool call?
6.  5\. Come si fa il checkpoint di un agente?
7.  Una checklist prima di un’esecuzione notturna
8.  Dove si colloca BroadNet Inference

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:

```python
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](https://broadrouter.com/it/glossary/reasoning-tokens/) 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](https://broadrouter.com/it/glossary/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](https://broadrouter.com/it/guides/streaming-chat-completions/).

```python
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](https://broadrouter.com/it/glossary/exponential-backoff/) 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](https://broadrouter.com/it/guides/errors-and-retries/).
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](https://broadrouter.com/it/blog/llm-api-failover-fallback/) 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](https://broadrouter.com/it/glossary/rate-limit/); il [calcolatore dei rate limit](https://broadrouter.com/tools/llm-rate-limit-calculator/) mostra quanto margine ha il tuo agente. L’[articolo sulla gestione dei 429](https://broadrouter.com/it/blog/handle-llm-api-429-rate-limits/) tratta il backoff in dettaglio. Con un [piano illimitato](https://broadrouter.com/it/guides/unlimited-llm-api-sessions/), 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](https://broadrouter.com/it/glossary/idempotency-key/) ricavata da task e passo, controllala prima di agire e salta la chiamata se è già registrata:

```python
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.

```python
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](https://broadrouter.com/it/glossary/context-window/), anche con 1.048.576 token su [DeepSeek V4.1 Flash](https://broadrouter.com/it/models/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](https://broadrouter.com/it/blog/run-parallel-coding-agents-flat-rate/) e [quanto costano i sistemi multi-agente](https://broadrouter.com/it/blog/multi-agent-cost/).

## 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](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-long-running-agents-timeouts-retries&utm_content=body).

Strumenti gratuiti sul tema (in inglese)

-   [Agent run cost estimator](https://broadrouter.com/tools/agent-run-cost-estimator/) Context growth per step, total tokens and cost of one agent run, with a DeepSeek session comparison.
-   [LLM batch job planner](https://broadrouter.com/tools/llm-batch-job-planner/) Run time, binding limit, cost per model and the flat sessions needed to finish a big job by a deadline.
-   [Flat-rate vs per-token LLM cost calculator](https://broadrouter.com/tools/flat-rate-vs-per-token-calculator/) Break-even between an unlimited plan and paying per token, per agent.
-   [LLM rate limit and concurrency calculator](https://broadrouter.com/tools/llm-rate-limit-calculator/) Which limit binds first: RPM, TPM or concurrency, with Little's law.

[Strumenti gratuiti (in inglese)](https://broadrouter.com/tools/)

## Termini in questo articolo

[Streaming](https://broadrouter.com/it/glossary/streaming/)

Lo streaming è un modo di restituire la risposta di un modello linguistico in piccoli pezzi mentre viene ancora generata, invece che in un’unica risposta alla fine. Le API compatibili con OpenAI trasmettono in streaming tramite server-sent event quando la richiesta imposta stream a true.

[Rate limit (limite di frequenza)](https://broadrouter.com/it/glossary/rate-limit/)

Un rate limit è un tetto che un’API pone a quanto un client può usarla in un intervallo di tempo, per esempio richieste al minuto o token al minuto. Le richieste oltre il limite vengono rifiutate, di solito con HTTP 429 Too Many Requests, finché l’uso non torna sotto la soglia.

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[Timeout della richiesta (request timeout)](https://broadrouter.com/it/glossary/request-timeout/)

Il timeout di una richiesta è il tempo massimo che un client HTTP aspetta un server prima di abbandonare la richiesta. I client di solito lo dividono in un timeout di connessione, per aprire la connessione, e un timeout di lettura, per l’attesa dei dati. Le chiamate LLM richiedono timeout di lettura generosi perché le risposte lunghe richiedono tempo.

[Pagamento a consumo (pay-as-you-go)](https://broadrouter.com/it/glossary/pay-as-you-go/)

Il pagamento a consumo è un modello di prezzo in cui paghi solo ciò che usi, misurato per unità come token, richieste o minuti di audio, senza abbonamento né impegno minimo. La maggior parte delle API LLM fattura così, da un saldo prepagato o con una fattura periodica.

[Chiave di idempotenza (idempotency key)](https://broadrouter.com/it/glossary/idempotency-key/)

Una chiave di idempotenza è un valore univoco, di solito un ID casuale come un UUID, che il client allega a una richiesta che modifica lo stato, come un pagamento o un acquisto. Se la stessa richiesta arriva di nuovo con la stessa chiave, il server restituisce il risultato originale invece di eseguire l’azione due volte.

[Concorrenza (concurrency)](https://broadrouter.com/it/glossary/concurrency/)

La concorrenza è il numero di richieste che un client ha in corso nello stesso momento. Le API LLM spesso la limitano per chiave o per piano, separatamente dalle richieste al minuto, perché ogni richiesta aperta occupa capacità GPU finché la sua risposta non è terminata.

[Sistema multi-agente (multi-agent system)](https://broadrouter.com/it/glossary/multi-agent-system/)

Un sistema multi-agente è un’applicazione LLM in cui più agenti, ognuno con il proprio prompt, i propri strumenti e il proprio contesto, lavorano su parti di un unico compito. Uno schema comune è orchestrator-worker: un agente principale pianifica, avvia agenti worker in parallelo e combina i loro risultati.

## 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.

## Continua a leggere

-   [Tool calling con modelli aperti: schemi, chiamate parallele, retry](https://broadrouter.com/it/blog/tool-calling-open-models/)
-   [Quanto costano davvero i sistemi multi-agente: token o sessioni flat](https://broadrouter.com/it/blog/multi-agent-cost/)
-   [Come far girare agenti di coding in parallelo con un’API LLM flat](https://broadrouter.com/it/blog/run-parallel-coding-agents-flat-rate/)
-   [Cosa significa davvero «illimitato» in un piano API LLM](https://broadrouter.com/it/blog/what-unlimited-llm-api-really-means/)
-   [Failover API LLM: passare a un secondo provider nel tuo codice](https://broadrouter.com/it/blog/llm-api-failover-fallback/)
-   [Costo di un’esecuzione di un agente di coding: passi, contesto, cache](https://broadrouter.com/it/blog/ai-coding-agent-run-cost/)
-   [Claude Code con modelli open-weight: proxy, endpoint nativi e limiti](https://broadrouter.com/it/blog/claude-code-with-openai-compatible-models/)
-   [Guida: Codici di errore di BroadNet Inference e quando ritentare](https://broadrouter.com/it/guides/errors-and-retries/)
-   [Guida: Streaming delle chat completions e connessioni interrotte](https://broadrouter.com/it/guides/streaming-chat-completions/)
-   [Guida: Come funzionano i piani API LLM illimitati per gli agenti](https://broadrouter.com/it/guides/unlimited-llm-api-sessions/)
-   [Guida: Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-long-running-agents-timeouts-retries&utm_content=page-cta) ·

**Fonti**

-   [README dell’SDK Python di OpenAI, retry e timeout (consultato il 2026-11-14)](https://github.com/openai/openai-python)
-   [Riferimento API di BroadNet Inference, errori e retry (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-long-running-agents-timeouts-retries&utm_content=sources#errors)
-   [Riferimento API di BroadNet Inference, streaming e limiti (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-long-running-agents-timeouts-retries&utm_content=sources#requests)
-   [Piani illimitati di BroadNet Inference (in inglese)](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-long-running-agents-timeouts-retries&utm_content=sources)
