---
title: "Agentes de IA de longa duração: timeouts e checkpoints"
description: "Mantenha um agente LLM vivo por horas: timeout por chamada, streaming para detectar travamentos, retentativas seguras, efeitos colaterais idempotentes e checkpoints."
url: https://broadrouter.com/pt/blog/long-running-agents-timeouts-retries/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/blog/long-running-agents-timeouts-retries/) (atualizado em 2026-11-16).

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

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em 2026-11-14 · Atualizado em 2026-11-16

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.

## Pontos principais

-   O SDK Python da OpenAI tem timeout de 10 minutos e, por padrão, faz duas retentativas. Em agentes, defina os dois valores explicitamente.
-   Um stream que termina antes de data \[DONE\] é uma resposta incompleta. Repeti-lo é uma nova inferência, cobrada de novo no pagamento por uso.
-   Chamadas ao modelo podem ser repetidas com segurança. Efeitos colaterais de ferramentas não, a menos que levem uma chave de idempotência.
-   Faça um checkpoint após cada passo concluído: a lista de mensagens, o número do passo e os IDs dos efeitos colaterais já executados.
-   Em uma sessão de plano, as retentativas não custam nada a mais, mas ocupam o único slot de requisição enquanto rodam.

**Nesta página**

1.  O que quebra quando um agente roda por horas?
2.  1\. Quanto tempo uma chamada pode levar?
3.  2\. Por que usar streaming em um agente de longa duração?
4.  3\. O que você deve repetir?
5.  4\. Como tornar tool calls idempotentes?
6.  5\. Como fazer checkpoint de um agente?
7.  Checklist antes de uma execução noturna
8.  Onde a BroadNet Inference entra

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:

```python
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](https://broadrouter.com/pt/glossary/reasoning-tokens/) 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](https://broadrouter.com/pt/glossary/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](https://broadrouter.com/pt/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)
```

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](https://broadrouter.com/pt/glossary/exponential-backoff/) 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](https://broadrouter.com/pt/guides/errors-and-retries/).
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](https://broadrouter.com/pt/blog/llm-api-failover-fallback/) 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](https://broadrouter.com/pt/glossary/rate-limit/); a [calculadora de rate limit](https://broadrouter.com/tools/llm-rate-limit-calculator/) mostra quanta folga o seu agente tem. O [post sobre como lidar com 429](https://broadrouter.com/pt/blog/handle-llm-api-429-rate-limits/) detalha o backoff. Em um [plano ilimitado](https://broadrouter.com/pt/guides/unlimited-llm-api-sessions/), 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](https://broadrouter.com/pt/glossary/idempotency-key/) derivada da tarefa e do passo, confira-a antes de agir e pule a chamada se ela já estiver registrada:

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

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.

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

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](https://broadrouter.com/pt/glossary/context-window/), mesmo com 1.048.576 tokens no [DeepSeek V4.1 Flash](https://broadrouter.com/pt/models/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](https://broadrouter.com/pt/blog/run-parallel-coding-agents-flat-rate/) e [quanto custam setups multiagente](https://broadrouter.com/pt/blog/multi-agent-cost/).

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

Ferramentas gratuitas sobre o tema (em inglês)

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

[Ferramentas gratuitas (em inglês)](https://broadrouter.com/tools/)

## Termos neste artigo

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

Streaming é uma forma de devolver a resposta de um modelo de linguagem em pequenos pedaços enquanto ela ainda está sendo gerada, em vez de uma resposta única no final. APIs compatíveis com a OpenAI fazem streaming via server-sent events quando a requisição define stream como true.

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

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Timeout de requisição (request timeout)](https://broadrouter.com/pt/glossary/request-timeout/)

Timeout de requisição é o tempo máximo que um cliente HTTP espera por um servidor antes de abandonar a requisição. Os clientes costumam dividi-lo em timeout de conexão, para abrir a conexão, e timeout de leitura, para esperar os dados. Chamadas a LLMs precisam de timeouts de leitura generosos, porque respostas longas levam tempo.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

[Chave de idempotência (idempotency key)](https://broadrouter.com/pt/glossary/idempotency-key/)

Uma chave de idempotência é um valor único, normalmente um ID aleatório como um UUID, que o cliente anexa a uma requisição que altera estado, como um pagamento ou uma compra. Se a mesma requisição for enviada de novo com a mesma chave, o servidor retorna o resultado original em vez de executar a ação duas vezes.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Backoff exponencial (exponential backoff)](https://broadrouter.com/pt/glossary/exponential-backoff/)

Backoff exponencial é uma estratégia de retry em que o cliente espera mais tempo depois de cada tentativa que falha, normalmente dobrando o atraso até um teto, antes de tentar de novo. Adicionar um jitter aleatório a cada espera espalha os retries de muitos clientes, para que não atinjam o servidor no mesmo instante.

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

## Continue lendo

-   [Tool calling com modelos abertos: schemas, chamadas paralelas, retry](https://broadrouter.com/pt/blog/tool-calling-open-models/)
-   [Quanto custam de verdade os sistemas multiagente: token ou sessão fixa](https://broadrouter.com/pt/blog/multi-agent-cost/)
-   [Como rodar agentes de código em paralelo numa API de LLM de preço fixo](https://broadrouter.com/pt/blog/run-parallel-coding-agents-flat-rate/)
-   [O que "ilimitado" significa de verdade em um plano de API de LLM](https://broadrouter.com/pt/blog/what-unlimited-llm-api-really-means/)
-   [Failover de API de LLM: passe para um segundo provedor no seu código](https://broadrouter.com/pt/blog/llm-api-failover-fallback/)
-   [Custo de uma execução de agente de código: passos, contexto e cache](https://broadrouter.com/pt/blog/ai-coding-agent-run-cost/)
-   [Claude Code com modelos abertos: proxies, endpoints nativos e limites](https://broadrouter.com/pt/blog/claude-code-with-openai-compatible-models/)
-   [Guia: Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/)
-   [Guia: Streaming de chat completions e conexões que caem](https://broadrouter.com/pt/guides/streaming-chat-completions/)
-   [Guia: Como funcionam os planos de API de LLM ilimitada para agentes](https://broadrouter.com/pt/guides/unlimited-llm-api-sessions/)
-   [Guia: Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

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

**Fontes**

-   [README do SDK Python da OpenAI, retentativas e timeouts (consultado em 2026-11-14)](https://github.com/openai/openai-python)
-   [Referência da API da BroadNet Inference, erros e retentativas (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-long-running-agents-timeouts-retries&utm_content=sources#errors)
-   [Referência da API da BroadNet Inference, streaming e limites (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-long-running-agents-timeouts-retries&utm_content=sources#requests)
-   [Planos ilimitados da BroadNet Inference (em inglês)](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-long-running-agents-timeouts-retries&utm_content=sources)
