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:
- Ripeti: errori di connessione, 429, 5xx, stream incompleti. Usa un backoff esponenziale con jitter e un tetto, per esempio 4 tentativi.
- Correggi, non ripetere: 400, 401, 402, 403, 413, 422. Falliscono ogni volta nello stesso modo. Vedi codici di errore e quando ripetere.
- 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ù.
- 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
- Timeout e
max_retriesimpostati in modo esplicito sul client. - Streaming attivo, con
include_usage, e stream incompleti ripetuti. - Un budget di retry per task e un limite di tempo reale.
- Chiavi di idempotenza su ogni tool che scrive, invia o paga.
- Un checkpoint dopo ogni passo, scritto in modo atomico.
- 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.
