BroadRouter

Agentes de larga duración: timeouts, reintentos y checkpoints sólidos

Por el equipo de BroadNet Inference · 4 min de lectura · Publicado · Actualizado

Trate cada llamada al modelo como desechable y el estado del agente como duradero. Fije un timeout por llamada, use streaming para detectar bloqueos, reintente los 429, 5xx y streams cortados con backoff acotado, y dé a cada herramienta con efectos secundarios una clave de idempotencia. Guarde la lista de mensajes tras cada paso para que, si el proceso cae, se reanude desde el último checkpoint y no desde el principio.

Un agente que corre cinco minutos puede ignorar los fallos. Uno que corre cinco horas verá un timeout, un 429, un stream cortado y probablemente un reinicio. La mayoría de las guías sobre agentes de larga duración venden un motor de workflows. Puede que usted no lo necesite. Este artículo cubre los cinco hábitos que mantienen vivo durante horas un bucle de agente sencillo, con código para el SDK de OpenAI para Python.

¿Qué se rompe cuando un agente corre durante horas?

Fallo Cómo se manifiesta Hábito que lo resuelve
Llamada colgada o lenta Sin respuesta durante minutos Timeout por llamada, streaming
Límite de tasa o sobrecarga 429, 5xx Reintento acotado con backoff
Stream cortado La conexión termina antes de [DONE] Tratarlo como incompleto y reintentar la llamada
Efecto secundario duplicado La herramienta se ejecuta dos veces tras un reintento Claves de idempotencia
Caída del proceso o despliegue El agente vuelve al paso 1 Checkpoint por paso

1. ¿Cuánto tiempo se le debe permitir a una llamada?

El README del SDK de OpenAI para Python dice que las solicitudes agotan el tiempo a los 10 minutos de forma predeterminada y que ciertos errores se reintentan dos veces. En un agente, fije ambos valores usted mismo, para que el comportamiento no cambie sin que usted lo sepa:

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
                timeout=300, max_retries=4)

Elija el timeout a partir de datos. Registre la duración de cada llamada durante un día y fije el timeout bastante por encima de la llamada exitosa más lenta. Los prompts grandes tardan más en empezar, y los modelos de razonamiento piensan antes de escribir. A unos 100 tokens por segundo, 8,000 tokens de salida tardan por sí solos más de un minuto. Añada un presupuesto de tiempo total aparte por tarea, para que un bucle que no se detiene no pueda correr toda la noche.

2. ¿Por qué usar streaming en un agente de larga duración?

El streaming le da una señal mientras el modelo trabaja. Sin él, una llamada lenta y una conexión muerta se ven iguales hasta que salta el timeout. Con él, puede ver llegar los fragmentos y además obtener el uso de tokens en el último fragmento.

Las reglas de streaming de BroadNet: lea hasta la línea literal data: [DONE]. Si la conexión se cierra antes, la respuesta está incompleta. Registre el X-Request-ID y luego decida si hace una nueva solicitud. Guía completa 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 esbozo solo recoge texto. Si hace streaming de tool calls, acumule también delta.tool_calls por índice.

3. ¿Qué debe reintentar?

El SDK ya reintenta los errores de conexión, 408, 409, 429 y 5xx. Añada su propio reintento encima solo para lo que el SDK no puede ver, como un stream incompleto:

  1. Reintente: errores de conexión, 429, 5xx y streams incompletos. Use backoff exponencial con jitter y un tope, por ejemplo 4 intentos.
  2. Corrija, no reintente: 400, 401, 402, 403, 413, 422. Fallan igual cada vez. Consulte códigos de error y cuándo reintentar.
  3. Presupueste los reintentos por tarea, no solo por llamada. Diez pasos que reintentan cuatro veces cada uno son cuarenta llamadas extra.
  4. Cambie de proveedor cuando se agoten los reintentos. Si una ejecución debe sobrevivir a una caída del proveedor, desvíe los errores de conexión, los 5xx y los 429 por límite de tasa a un segundo proveedor. Failover de API de LLM muestra el código del cliente y un circuit breaker.

En pago por uso, cada reintento es una nueva inferencia y se cobra otra vez. Una clave de pago por uso permite además 30 solicitudes por minuto y 4 simultáneas, así que las ráfagas de reintentos chocan rápido con el límite de tasa; la calculadora de límites de tasa muestra cuánto margen tiene su agente. El artículo sobre cómo manejar los 429 trata el backoff en detalle. En un plan ilimitado, los reintentos no cuestan nada extra, pero ocupan el único hueco de solicitud de la sesión mientras se ejecutan.

4. ¿Cómo hacer idempotentes las llamadas a herramientas?

Una llamada al modelo no tiene efectos secundarios. Una llamada a una herramienta puede tenerlos. Si el agente cae después de ejecutar send_invoice pero antes de guardar el paso, el agente reiniciado la enviará otra vez.

Dé a cada llamada con efectos secundarios una clave de idempotencia derivada de la tarea y el paso, compruébela antes de actuar y omita la llamada si ya está 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

Muchas API de pagos y mensajería aceptan una cabecera de clave de idempotencia. Cuando lo hagan, pásele la suya.

5. ¿Cómo hacer checkpoints de un agente?

Guarde tras cada paso completado: la lista de mensajes, el número de paso y las claves de efectos secundarios. Al iniciar, cargue el checkpoint más reciente si existe.

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

Escribir en un archivo temporal y renombrarlo garantiza que una caída a mitad de escritura nunca deje un checkpoint a medias. En sesiones muy largas, guarde también un resumen: sustituya los turnos antiguos por un resumen corto para que un agente reanudado no recargue un historial enorme. Así se mantiene dentro de la ventana de contexto, incluso con 1,048,576 tokens en DeepSeek V4.1 Flash.

Lista de comprobación antes de una ejecución nocturna

  1. Timeout y max_retries fijados explícitamente en el cliente.
  2. Streaming activado, con include_usage, y streams incompletos reintentados.
  3. Un presupuesto de reintentos por tarea y un límite de tiempo total.
  4. Claves de idempotencia en cada herramienta que escriba, envíe o pague.
  5. Un checkpoint tras cada paso, escrito de forma atómica.
  6. Logs con número de paso, duración, tokens y X-Request-ID.

Si ejecuta varios agentes en paralelo, lea ejecutar agentes de programación en paralelo con tarifa plana y cuánto cuestan los sistemas multiagente.

Dónde encaja BroadNet Inference

BroadNet Inference usa streaming estándar de chat completions, devuelve una cabecera X-Request-ID que usted puede registrar y documenta qué errores reintentar, así que los patrones anteriores funcionan tal cual. Para agentes que corren todo el día, los planes ilimitados eliminan el contador de tokens de DeepSeek V4.1 Flash por $60 al mes por sesión, lo que hace gratuitos los reintentos. Tenga en cuenta que una hora de Meteoro (Meteor) termina una hora después de la compra y una semana de Órbita (Orbit) a los siete días, así que un trabajo largo debe terminar dentro del periodo o pasar a una sesión de Luna Llena (Full Moon) con renovación. Los planes están en inference.broadnet.ai/plans.

Preguntas frecuentes

¿Qué timeout debo fijar para las llamadas a la API de LLM en un agente?

Lo bastante largo para la llamada legítima más lenta y lo bastante corto para detectar una que se quedó colgada. El SDK de OpenAI para Python usa 10 minutos de forma predeterminada. Muchos agentes usan de 2 a 5 minutos por llamada con streaming, y un límite de tiempo total aparte por tarea.

¿Qué errores de la API de LLM debe reintentar un agente?

Reintente los errores de conexión, 429 y 5xx con backoff exponencial acotado y jitter. Los 400, 401, 402, 403, 413 y 422 hay que corregirlos, no reintentarlos. En BroadNet, registre también la cabecera X-Request-ID de cada fallo.

¿Es seguro reintentar un chat completion?

La llamada al modelo en sí no tiene efectos secundarios, así que sí, pero es una nueva inferencia y se cobra otra vez en pago por uso. El peligro está en las herramientas: un paso reintentado puede enviar un correo dos veces si la herramienta no usa una clave de idempotencia.

¿Cómo reanudo un agente después de una caída?

Guarde la lista de mensajes y el número de paso tras cada paso completado, escriba los ID de los efectos secundarios antes de actuar y vuelva a cargarlos al iniciar. El agente se reanuda desde el último paso guardado.

¿Los agentes de larga duración necesitan un plan ilimitado?

No, pero en pago por uso los reintentos y los contextos largos se acumulan. En los planes ilimitados de BroadNet, DeepSeek V4.1 Flash no tiene contador de tokens, así que los reintentos no cuestan nada extra, aunque cada sesión sigue ejecutando una solicitud a la vez.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity