Sondeo de endpoints de estado: cómo esperan los agentes sin bucles

Un agente que inicia un trabajo externo no debe seguir preguntando «¿ya está?» hasta que un proveedor, un presupuesto o una persona se rindan. El sondeo de un endpoint de estado necesita un contrato explícito: qué cuenta como progreso, cuándo puede hacerse la siguiente solicitud, cuándo termina la espera y quién decide qué ocurre después.

He visto comprobaciones de estado aparentemente inofensivas convertirse en cientos de llamadas porque el identificador del trabajo era válido, el endpoint seguía devolviendo HTTP 200 y nadie le indicó al agente que «running» ya no era una respuesta aceptable después de un plazo. La solución no es una planificación ingeniosa. Consiste en convertir la espera en una acción limitada, con pruebas y una vía de escalamiento.

Un estado en ejecución permite esperar, no actuar

Un estado de trabajo no terminal permite hacer otra observación más adelante. No permite al agente obtener el resultado, iniciar trabajo dependiente, repetir el envío original ni ampliar su autoridad.

La diferencia importa porque las API asíncronas suelen devolver una respuesta HTTP correcta para todos los estados. Una respuesta como esta indica que el endpoint de estado funcionó. No indica que el trabajo haya terminado correctamente.

{
  "job_id": "exp_71c",
  "state": "running",
  "updated_at": "2025-04-18T10:24:00Z"
}

Trata el resultado HTTP y el resultado del trabajo como dos hechos independientes. El primero responde a «¿el proveedor respondió a esta solicitud?». El segundo responde a «¿puede avanzar el flujo de trabajo?». Los equipos los confunden constantemente y luego un agente descarga una exportación incompleta o publica un resultado que nunca existió.

Escribe una tabla de estados pequeña para cada integración con un proveedor. No deduzcas el significado a partir de un nombre de campo como status; los proveedores usan la misma palabra para ciclos de vida muy distintos. Una tabla útil incluye estas categorías:

• Estados pendientes permiten hacer otra solicitud de estado más adelante, como queued, running o processing.
• Estados correctos permiten la acción posterior indicada, como recuperar una URL de resultado.
• Estados de fallo detienen la ejecución y conservan el error del proveedor.
• Estados de cancelación y expiración detienen la ejecución sin volver a enviar el trabajo, salvo que una persona lo pida expresamente.
• Estados desconocidos detienen la ejecución porque una integración no puede adivinar con seguridad si paused, awaiting_review o un valor nuevo son inofensivos.

La respuesta de estado también debe comprobarse en busca de contradicciones. Un trabajo que indica succeeded pero no incluye la referencia de resultado necesaria no está listo para consumirse. Un trabajo que indica running después de su propia hora de expiración necesita escalamiento, no más confianza en el sondeo.

Conserva juntos el identificador del trabajo, el contexto de la cuenta del proveedor, la huella de la solicitud original y los estados terminales esperados. Si el agente pierde esa asociación, podría consultar el trabajo equivocado después de reiniciarse o tratar por accidente un trabajo de una solicitud anterior como si fuera el actual.

Los intervalos fijos crean presión sincronizada

Un intervalo fijo parece ordenado en el código y funciona mal en una flota. Si cincuenta agentes envían trabajo cerca del mismo minuto y cada uno consulta cada diez segundos, tienden a golpear al proveedor en grupos. Los grupos permanecen después de una interrupción breve porque todos los agentes vuelven a intentar la operación según el mismo reloj.

Usa un retraso creciente con variación aleatoria. Empieza con un retraso breve solo cuando el proveedor suele terminar rápido o expone el estado de inmediato. Aumenta la espera después de cada respuesta pendiente, establece un límite y varía el retraso real en cada ejecución.

Una planificación práctica puede usar esta regla:

base_delay = 5 seconds
max_delay = 120 seconds
attempt = number of completed polls
raw_delay = min(max_delay, base_delay * 2^attempt)
actual_delay = random value between 50% and 100% of raw_delay

El intervalo aleatorio importa. Una secuencia determinista de 5, 10, 20, 40 y 80 segundos solo desplaza la sincronización hacia oleadas más amplias. El jitter completo, en el que el valor aleatorio puede ir de cero al límite, también funciona en algunos sistemas. Para el sondeo de trabajos prefiero un límite inferior, porque una ejecución que elige repetidamente retrasos cercanos a cero empieza a parecerse a una avalancha de reintentos.

No apliques una planificación genérica de backoff sin tener en cuenta la duración del trabajo. Una conversión de documentos que normalmente termina en un minuto se beneficia de observaciones tempranas. Una exportación por lotes que informa de una hora estimada de finalización no debería recibir una consulta cada pocos segundos solo porque el agente está inactivo.

Si la API proporciona un campo como next_check_at, poll_after_seconds o similar, trátalo como una indicación del proveedor. Valídalo antes de aceptarlo. Rechaza valores negativos, esperas absurdamente largas que superen el plazo de tu operación y marcas de tiempo que no puedan analizarse. El agente puede esperar hasta la hora indicada o hasta su propio plazo, lo que ocurra primero.

Un retraso no promete que el agente hará una solicitud exactamente en ese instante. Un proceso local puede quedar suspendido, reiniciarse, perder conectividad o reanudarse mucho más tarde. Al despertarse, comprueba primero si ha pasado el plazo. No compenses los intervalos perdidos enviando varias consultas de estado en una ráfaga.

Un plazo y un presupuesto de solicitudes detectan fallos distintos

Cada ejecución de sondeo necesita un plazo de reloj y un número máximo de solicitudes de estado. Añade un límite separado para los fallos de transporte si el proveedor es remoto o poco fiable.

El plazo controla cuánto tiempo puede permanecer sin resolverse el flujo de trabajo. Evita que un agente mantenga vivo un trabajo obsoleto durante todo un fin de semana porque la API sigue diciendo queued. Elígelo según el efecto empresarial del retraso, el periodo de retención documentado por el proveedor y el momento a partir del cual una persona debería decidir. No lo calcules solo a partir de la duración media. Las medias ocultan los trabajos que se atascan.

Un presupuesto de solicitudes controla la presión que el agente ejerce sobre el proveedor y sobre la credencial que utiliza. Detecta un error de planificación aunque el tiempo avance despacio y limita el coste cuando una API cobra por llamada. El presupuesto debe incluir las consultas de estado realizadas después de una ambigüedad de red. Si no contabilizas esas llamadas, un agente puede agotar la cuota del proveedor mientras se convence de que solo ha hecho unos pocos intentos.

Un presupuesto de fallos tiene una función más concreta. Cuenta los rechazos de conexión, errores DNS, fallos TLS y respuestas 5xx que impiden al agente conocer el estado del trabajo. Un único tiempo de espera agotado no demuestra que el trabajo haya fallado. Repetir la misma solicitud fallida durante una hora tampoco demuestra paciencia.

Usa un registro de operación parecido a este, almacenado de forma persistente antes del primer sondeo:

{
  "operation_id": "report-export-2025-04-18-01",
  "provider_job_id": "exp_71c",
  "started_at": "2025-04-18T10:20:00Z",
  "deadline_at": "2025-04-18T11:00:00Z",
  "max_status_requests": 12,
  "max_transport_failures": 3,
  "status_requests_used": 0,
  "transport_failures_used": 0,
  "last_known_state": "queued"
}

Los valores son ejemplos, no valores predeterminados para todos los proveedores. Doce comprobaciones en cuarenta minutos pueden ser adecuadas para una exportación lenta. Sería absurdo para una operación que normalmente termina en tres segundos y peligroso para otra que el proveedor pide consultar una vez cada quince minutos.

Comprueba el plazo antes de una solicitud, no solo después. De lo contrario, un proceso que se despierta tarde podría hacer una llamada adicional no autorizada. Comprueba el presupuesto de solicitudes justo antes de planificar y auméntalo justo antes de transmitir. El orden importa cuando un proceso se bloquea entre la planificación y el envío. Es preferible tener alguna reserva sin usar que una solicitud adicional invisible.

Las condiciones de detención deben poder ejecutarse, no ser aspiraciones

«Detente si tarda demasiado» es una nota para una persona, no una condición que un agente pueda hacer cumplir. Define las condiciones de detención como predicados sobre el registro y la respuesta actuales.

Detente correctamente solo cuando el proveedor informe de un estado terminal de éxito aceptado y todos los campos necesarios para la siguiente acción superen la validación. Si la siguiente acción descarga un artefacto, valida su referencia antes de declarar el éxito. Si la siguiente acción afecta a otro sistema, registra la respuesta terminal antes de realizarla.

Detente con fallo cuando el proveedor informe de un fallo terminal, cuando la respuesta no pueda analizarse o cuando un estado quede fuera de la lista permitida de la integración. Gestionar los estados desconocidos merece la misma seriedad que denegar una autorización. Un proveedor puede añadir sin avisar un estado needs_payment, manual_review o blocked. Suponer que significa «esperar» convierte un cambio de software en su lado en un bucle interminable en el tuyo.

Detente por tiempo agotado cuando llegue el plazo, aunque el estado haya cambiado justo entonces. El agente debe informar del último estado observado, pero no debe concederse otro retraso completo porque haya visto algo que parece progreso. Si se acepta una espera más larga, conviértela en una nueva decisión de autorización con un nuevo plazo.

Detente por agotamiento del presupuesto cuando la siguiente consulta de estado superaría el número permitido. No reinicies el contador solo porque el agente se haya reiniciado, haya cambiado de sesión o haya recibido una nueva instrucción. El proveedor ve un único solicitante y un único trabajo, no los límites internos de tu proceso.

Detente por entrega ambigua después de que una consulta de estado agote su tiempo de espera si el presupuesto de fallos se ha agotado. El agente no puede saber si el proveedor recibió la solicitud, pero las consultas de estado deberían poder repetirse sin riesgo. Si el endpoint cambia el estado, cobra dinero o actualiza un artefacto en cada GET, no es un endpoint de estado en sentido operativo. Trátalo como una acción y exige controles más estrictos.

Aquí es donde los equipos cometen un error caro: suponen que GET significa inofensivo. HTTP define GET como un método seguro en sentido semántico, es decir, el cliente no solicitó un cambio de estado. Es un contrato que el servidor debe respetar, no una propiedad mágica de una URL. Verifica el comportamiento del proveedor con una cuenta de prueba y su documentación antes de clasificar una llamada como observacional.

Respeta las señales del protocolo que los proveedores ya envían

HTTP incluye varias señales que deberían cambiar de inmediato el comportamiento de sondeo de un agente. Ignorarlas porque el bucle tiene su propio temporizador resulta descortés con el proveedor y normalmente ralentiza la recuperación.

RFC 9110 define Retry-After como una indicación del tiempo mínimo que un cliente debería esperar antes de hacer una solicitud posterior. El campo puede contener un retraso en segundos o una fecha HTTP. Analiza ambos formatos. Para una solicitud de estado que recibe un 503 con Retry-After: 120, no uses tu backoff normal de treinta segundos ni vuelvas a intentarlo antes de tiempo. Espera al menos dos minutos, siempre que el plazo de la operación lo permita.

RFC 6585 define HTTP 429, Too Many Requests, e indica que una respuesta puede incluir Retry-After. Esto permite que los proveedores omitan la cabecera, por lo que el agente sigue necesitando su propio backoff. Un 429 sin indicaciones debería aumentar mucho el retraso y consumir el presupuesto de fallos o de control de tráfico que hayas definido. Una ejecución que sigue recibiendo 429 debe escalarse. No debe seguir ampliando el temporizador indefinidamente.

Para 202 Accepted, revisa el cuerpo y las cabeceras de la respuesta en busca de una ubicación, un ID de trabajo y el recurso de estado indicado. No construyas una URL adivinada a partir del endpoint de envío. Algunos proveedores usan una ubicación de resultado, otros una ubicación de estado y otros devuelven la representación final más adelante. Sigue el contrato documentado.

Para 404, no supongas siempre que el trabajo nunca existió. Un trabajo recién enviado puede estar sujeto a consistencia eventual y un trabajo terminado puede desaparecer cuando expire la retención. El contrato original del proveedor decide qué explicación es plausible. Si el comportamiento documentado no lo explica, clasifícalo como un fallo de integración y escálalo con el ID del trabajo y las marcas de tiempo.

Para 401 o 403, detén el sondeo. Reintentar fallos de autorización con la misma credencial añade ruido y puede activar las defensas del proveedor. La acción humana consiste en revisar el acceso, la rotación de credenciales, el alcance de la cuenta o la configuración de la puerta de enlace. La acción de sondeo ha terminado.

Para respuestas 5xx y fallos de red, usa el presupuesto de fallos de transporte. Conserva el código de respuesta, la hora de la solicitud y cualquier ID de solicitud del proveedor. Esos datos importan cuando el equipo de soporte o una persona encargada necesita distinguir una respuesta perdida de un fallo del trabajo.

El escalamiento debe pedir una decisión, no volcar un registro

Un agente necesita un punto definido en el que deje de esperar y entregue la situación a una persona o a otro flujo de trabajo autorizado de forma explícita. El escalamiento no es una notificación decorativa después de que el agente haya reintentado todas las posibilidades.

Haz que el motivo del escalamiento sea legible por las máquinas. Usa categorías como deadline_exceeded, request_budget_exhausted, rate_limited, unknown_state, authorization_denied o provider_failure. Cada categoría debe determinar la siguiente acción permitida. Una persona que vea unknown_state puede aprobar una pausa temporal mientras alguien revisa los cambios del proveedor. Una persona que vea authorization_denied no debería aprobar otra solicitud idéntica.

El mensaje de escalamiento debe contener contexto suficiente para decidir sin exponer secretos:

External job needs a decision
Operation: report-export-2025-04-18-01
Provider job: exp_71c
Last state: running
Elapsed time: 40 minutes
Status requests: 12 of 12
Last HTTP result: 200 at 10:58 UTC
Stopped because: request_budget_exhausted
Safe options: extend waiting once, cancel at provider, inspect provider console

No formules la opción como «¿continuar?». Eso invita a la persona operadora a aprobar un bucle indefinido. Ofrece opciones limitadas. «Ampliar quince minutos con cuatro comprobaciones adicionales» expresa el coste y crea un nuevo límite. «Cancelar en el proveedor» solo debe aparecer si la integración tiene una acción de cancelación documentada y la persona entiende sus efectos.

Escala antes cuando el resultado final tenga una ventana de utilidad breve. Una validación de despliegue que llegue después de cerrar la ventana de despliegue quizá no merezca más sondeos. Una exportación de documentos fiscales puede justificar esperar durante una incidencia del proveedor. El estado técnico por sí solo no puede decidir esa prioridad, así que codifica por separado el plazo empresarial del flujo de trabajo y el plazo del trabajo del proveedor cuando sean distintos.

Evita volver a enviar automáticamente el trabajo después de un tiempo de espera, salvo que el proveedor ofrezca idempotencia y conserves el token de idempotencia. Un fallo en el sondeo de estado no demuestra que el trabajo original haya fallado. Volver a enviarlo puede crear facturas duplicadas, correos duplicados, despliegues duplicados o exportaciones que compitan entre sí. La gente lo llama «autorreparación» hasta que tiene que limpiar las consecuencias.

Un controlador de sondeo necesita estado persistente y un único responsable

Un controlador de sondeo fiable conserva su registro y garantiza que solo un trabajador sea responsable de un trabajo a la vez. Sin esas dos propiedades, la recuperación tras un reinicio y los agentes paralelos generarán comprobaciones duplicadas o acciones posteriores contradictorias.

El responsable puede ser un arrendamiento de proceso, un bloqueo de base de datos u otro mecanismo persistente adecuado para tu entorno. El mecanismo debe caducar si el trabajador muere y el nuevo responsable debe volver a cargar el registro completo antes de enviar nada. Un booleano en memoria no es una propiedad de exclusividad cuando existe un segundo proceso de agente.

Conserva el registro después de cada evento importante: envío del trabajo, planificación de la siguiente comprobación, envío de una solicitud de estado, recepción de la respuesta, transición de estado y escalamiento. No necesitas un diario separado para cada detalle de depuración, pero sí debes poder recuperar los hechos que afectan a la autoridad y los presupuestos.

Este pseudocódigo muestra el orden que evita la mayoría de los bucles accidentales:

load operation
if operation is terminal or escalated:
    exit
if current_time >= operation.deadline_at:
    record timeout and escalate
    exit
if operation.status_requests_used >= operation.max_status_requests:
    record budget exhaustion and escalate
    exit
if current_time < operation.next_poll_at:
    schedule wakeup and exit

acquire ownership lease
reload operation
increment status_requests_used and persist
send one status request
persist response metadata

if response has terminal success and required result fields are valid:
    record success
else if response has terminal failure or unknown state:
    record stop reason and escalate
else if response requires waiting:
    calculate next_poll_at with provider guidance, backoff, and jitter
    persist next_poll_at
else:
    record integration failure and escalate

La segunda carga después de adquirir la propiedad es deliberada. Otro trabajador puede haber terminado el trabajo mientras este esperaba el arrendamiento. Si la omites, acabarás viendo dos agentes recuperar o publicar el mismo resultado.

No mantengas un arrendamiento mientras duermes. Mantenlo solo mientras actualizas el registro y envías la única solicitud, si el diseño de propiedad lo permite de forma segura. Un arrendamiento mantenido durante toda la duración de un trabajo externo lento se convierte en un problema de recursos abandonados cuando un portátil entra en suspensión o muere un proceso.

Un endpoint de estado debería ser de solo lectura desde la perspectiva del agente. Mantén la recuperación del resultado, la cancelación y la publicación posterior como acciones separadas, cada una con su propio registro. Combinarlo todo dentro de una función de sondeo es la forma de convertir un temporizador inofensivo en un motor de flujos de trabajo oculto.

La aprobación humana pertenece al límite de escalamiento

La mayoría de los sondeos rutinarios no necesitan un clic humano si permanecen dentro de la operación aprobada originalmente, el alcance de la credencial, el plazo y el presupuesto de solicitudes. Exigir aprobación para cada lectura enseña a las personas a aprobar sin leer y retrasa el trabajo sin aportar seguridad.

La aprobación sí corresponde cuando el agente solicita una nueva frontera de autoridad: más tiempo que el plazo original, un presupuesto de solicitudes mayor, una llamada de cancelación, un reenvío, otra credencial o el uso de un resultado que no superó la validación. Son cambios en la operación, no observaciones ordinarias.

Sallyport puede mantener la credencial de API fuera de un agente compatible con MCP mientras la aplicación realiza la consulta de estado y devuelve el resultado. Su configuración de clave por llamada encaja en operaciones donde cada uso de una credencial concreta, incluida una consulta de estado, necesita aprobación explícita, pero esa configuración no puede corregir un diseño de sondeo sin límites.

Elige el modelo de aprobación según las consecuencias. Una consulta de estado de bajo riesgo puede permanecer dentro de una autorización por sesión. Una API de estado privilegiada que revele metadatos sensibles del trabajo puede necesitar aprobación por llamada o una credencial más limitada. En ambos casos, define los límites del controlador antes de decidir cómo autorizar una solicitud.

No permitas que una instrucción decida si ampliar un plazo es inofensivo. La solicitud debe indicar el estado actual, el tiempo transcurrido, las llamadas realizadas, el presupuesto adicional propuesto y el efecto esperado de continuar. Así, la persona revisora puede rechazar una ampliación que haría perder una ventana de lanzamiento o produciría datos obsoletos.

Audita la decisión de esperar, no solo la solicitud

Un registro de solicitudes indica que un agente llamó a /jobs/exp_71c. No indica si la llamada estaba permitida por el plan de sondeo, si el agente ignoró Retry-After o si el trabajo ya había superado su plazo.

Registra la decisión del controlador con cada llamada: estado actual, hora siguiente planificada, origen del retraso, número de solicitudes, plazo, código de respuesta, estado del trabajo analizado y decisión resultante. El origen del retraso puede ser provider_retry_after, provider_poll_hint, local_backoff o manual_extension. Ese pequeño campo ahorra muchas discusiones después de un incidente.

Una secuencia de auditoría útil se lee como una historia:

10:20:00 submitted job exp_71c, deadline 11:00:00, budget 12
10:20:05 polled, state queued, next poll 10:20:14 from local backoff
10:20:14 polled, state running, next poll 10:20:31 from local backoff
10:20:31 received 503, Retry-After 120, next poll 10:22:31 from provider guidance
10:22:31 polled, state running, next poll 10:23:48 from local backoff
10:58:00 polled, state running, request budget exhausted, escalated

Ese registro hace evidente un controlador defectuoso. Si las marcas de tiempo muestran una solicitud por segundo a pesar del retraso indicado por el proveedor, tienes una prueba. Si un agente afirma que el trabajo agotó el tiempo pero su estado final era succeeded, tienes un problema concreto que corregir.

Sallyport proyecta las sesiones de los agentes y las llamadas individuales desde un registro de auditoría cifrado y encadenado mediante hashes, y sp audit verify puede verificar esa cadena sin conexión sobre el texto cifrado. Ese tipo de evidencia resulta más útil cuando tu propio registro de operación explica por qué ocurrió cada llamada observada.

No midas la calidad del sondeo según si los trabajos terminan finalmente. Mide si cada trabajo alcanza un resultado terminal o un escalamiento limitado, si los agentes respetan las instrucciones de espera del proveedor y si una persona operadora puede reconstruir una decisión discutida. El primer cambio que haría en un bucle sin control es sencillo: conservar un plazo y un presupuesto de solicitudes antes de que el agente haga su primera consulta de estado.