BroadRouter

Agentes de longa duração: timeouts, retentativas e checkpoints

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em · Atualizado em

Trate cada chamada ao modelo como descartável e o estado do agente como durável. Defina um timeout por chamada, use streaming para detectar travamentos, repita 429, 5xx e streams interrompidos com backoff limitado, e dê uma chave de idempotência a toda ferramenta com efeito colateral. Salve a lista de mensagens após cada passo, para que uma queda retome do último checkpoint, e não do início.

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:

  1. Repita: erros de conexão, 429, 5xx, streams incompletos. Use backoff exponencial com jitter e um teto, por exemplo 4 tentativas.
  2. 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.
  3. Defina um orçamento de retentativas por tarefa, não só por chamada. Dez passos repetindo quatro vezes cada são quarenta chamadas extras.
  4. 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

  1. Timeout e max_retries definidos explicitamente no cliente.
  2. Streaming ligado, com include_usage, e streams incompletos repetidos.
  3. Um orçamento de retentativas por tarefa e um limite de tempo real.
  4. Chaves de idempotência em toda ferramenta que grava, envia ou paga.
  5. Um checkpoint após cada passo, gravado de forma atômica.
  6. 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.

Perguntas frequentes

Que timeout devo definir para chamadas de API de LLM em um agente?

Longo o bastante para a chamada legítima mais lenta, curto o bastante para pegar uma travada. O SDK Python da OpenAI usa 10 minutos por padrão. Muitos agentes usam de 2 a 5 minutos por chamada com streaming, e um limite de tempo real separado por tarefa.

Quais erros de API de LLM um agente deve repetir?

Repita erros de conexão, 429 e 5xx com backoff exponencial limitado e jitter. Em 400, 401, 402, 403, 413 e 422, corrija a causa em vez de repetir. Na BroadNet, registre também o header X-Request-ID de cada falha.

É seguro repetir uma chat completion?

A chamada ao modelo em si não tem efeitos colaterais, então sim, mas é uma nova inferência e é cobrada de novo no pagamento por uso. O perigo está nas ferramentas. Um passo repetido pode enviar um e-mail duas vezes, a menos que a ferramenta use uma chave de idempotência.

Como retomo um agente depois de uma queda?

Salve a lista de mensagens e o número do passo após cada passo concluído, grave os IDs dos efeitos colaterais antes de agir e recarregue tudo na inicialização. O agente retoma do último passo salvo.

Agentes de longa duração precisam de um plano ilimitado?

Não, mas retentativas e contextos longos se acumulam no pagamento por uso. Nos planos ilimitados da BroadNet, o DeepSeek V4.1 Flash não tem medidor de tokens, então as retentativas não custam nada a mais, embora cada sessão continue rodando uma requisição por vez.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity