Um agente que roda por cinco minutos pode ignorar falhas. Um que roda por cinco horas vai ver um timeout, um 429, um stream interrompido e provavelmente um reinício. A maioria dos guias sobre agentes de longa duração vende um motor de workflow. Talvez você não precise de um. Este post cobre os cinco hábitos que mantêm um loop de agente simples vivo por horas, com código para o SDK Python da OpenAI.
O que quebra quando um agente roda por horas?
| Falha | Como aparece | Hábito que resolve |
|---|---|---|
| Chamada travada ou lenta | Nenhuma resposta por minutos | Timeout por chamada, streaming |
| Rate limit ou sobrecarga | 429, 5xx | Retentativa limitada com backoff |
| Stream interrompido | A conexão termina antes de [DONE] |
Tratar como incompleto e repetir a chamada |
| Efeito colateral duplicado | A ferramenta roda duas vezes após uma retentativa | Chaves de idempotência |
| Queda do processo ou deploy | O agente recomeça do passo 1 | Checkpoint a cada passo |
1. Quanto tempo uma chamada pode levar?
O README do SDK Python da OpenAI diz que, por padrão, as requisições expiram após 10 minutos e certos erros são repetidos duas vezes. Em um agente, defina os dois você mesmo, para que o comportamento não mude sem você saber:
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
timeout=300, max_retries=4)
Escolha o timeout a partir de dados. Registre a duração de cada chamada por um dia e defina o timeout bem acima da chamada bem-sucedida mais lenta. Prompts grandes demoram mais para começar, e modelos de raciocínio pensam antes de escrever. A cerca de 100 tokens por segundo, 8.000 tokens de saída levam mais de um minuto sozinhos. Acrescente um orçamento de tempo real separado por tarefa, para que um loop que não para não rode a noite inteira.
2. Por que usar streaming em um agente de longa duração?
O streaming dá um sinal enquanto o modelo trabalha. Sem ele, uma chamada lenta e uma conexão morta parecem iguais até o timeout disparar. Com ele, você vê os chunks chegando e ainda recebe o uso de tokens no último chunk.
As regras de streaming da BroadNet: leia até a linha literal data: [DONE]. Se a conexão fechar antes, a resposta está incompleta. Registre o X-Request-ID e então decida se faz uma nova requisição. Guia completo de 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)
Este esboço coleta só texto. Se você faz streaming de tool calls, acumule também delta.tool_calls por índice.
3. O que você deve repetir?
O SDK já repete erros de conexão, 408, 409, 429 e 5xx. Coloque sua própria retentativa por cima só para o que ele não enxerga, como um stream incompleto:
- Repita: erros de conexão, 429, 5xx, streams incompletos. Use backoff exponencial com jitter e um teto, por exemplo 4 tentativas.
- Corrija, não repita: 400, 401, 402, 403, 413, 422. Eles falham do mesmo jeito toda vez. Veja códigos de erro e quando repetir.
- Defina um orçamento de retentativas por tarefa, não só por chamada. Dez passos repetindo quatro vezes cada são quarenta chamadas extras.
- Faça failover quando as retentativas acabarem. Se uma execução precisa sobreviver a uma queda do provedor, mande erros de conexão, 5xx e 429 de rate limit para um segundo provedor. Failover de API de LLM mostra o código do cliente e um circuit breaker.
No pagamento por uso, cada retentativa é uma nova inferência, cobrada de novo. Uma chave de pagamento por uso também permite 30 requisições por minuto e 4 simultâneas, então tempestades de retentativas batem rápido no rate limit; a calculadora de rate limit mostra quanta folga o seu agente tem. O post sobre como lidar com 429 detalha o backoff. Em um plano ilimitado, as retentativas não custam nada a mais, mas ocupam o único slot de requisição da sessão enquanto rodam.
4. Como tornar tool calls idempotentes?
Uma chamada ao modelo não tem efeitos colaterais. Uma tool call pode ter. Se o agente cair depois que send_invoice rodou, mas antes de o passo ser salvo, o agente reiniciado vai enviar de novo.
Dê a cada chamada com efeito colateral uma chave de idempotência derivada da tarefa e do passo, confira-a antes de agir e pule a chamada se ela já estiver registrada:
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
Muitas APIs de pagamento e de mensagens aceitam um header com chave de idempotência. Quando aceitarem, repasse a sua.
5. Como fazer checkpoint de um agente?
Salve após cada passo concluído: a lista de mensagens, o número do passo e as chaves dos efeitos colaterais. Na inicialização, carregue o checkpoint mais recente, se existir.
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
Gravar em um arquivo temporário e renomear garante que uma queda no meio da gravação nunca deixe um checkpoint pela metade. Em sessões muito longas, salve também um resumo: substitua turnos antigos por um resumo curto, para que um agente retomado não recarregue um histórico enorme. Isso mantém você dentro da janela de contexto, mesmo com 1.048.576 tokens no DeepSeek V4.1 Flash.
Checklist antes de uma execução noturna
- Timeout e
max_retriesdefinidos explicitamente no cliente. - Streaming ligado, com
include_usage, e streams incompletos repetidos. - Um orçamento de retentativas por tarefa e um limite de tempo real.
- Chaves de idempotência em toda ferramenta que grava, envia ou paga.
- Um checkpoint após cada passo, gravado de forma atômica.
- Logs com número do passo, duração, tokens e
X-Request-ID.
Se você roda vários agentes lado a lado, leia rodar agentes de código em paralelo com preço fixo e quanto custam setups multiagente.
Onde a BroadNet Inference entra
A BroadNet Inference usa o streaming padrão de chat completions, devolve um header X-Request-ID que você pode registrar e documenta quais erros repetir, então os padrões acima funcionam como estão escritos. Para agentes que rodam o dia todo, os planos ilimitados eliminam o medidor de tokens no DeepSeek V4.1 Flash por $60 por mês por sessão, o que torna as retentativas gratuitas. Lembre que uma hora Meteor termina uma hora após a compra e uma semana Orbit após sete dias, então um trabalho longo precisa terminar dentro do período ou passar para uma sessão Full Moon com renovação. Os planos estão em inference.broadnet.ai/plans.
