Paginación de API para agentes de IA: descubrimiento acotado

Un agente que llama a un endpoint de lista sin un presupuesto de páginas no está haciendo descubrimiento. Está iniciando un procedimiento remoto sin final definido y esperando que la factura, el límite de frecuencia y el conjunto de resultados sigan siendo manejables. El error contrario es igual de perjudicial: consultar la primera página, encontrar una respuesta plausible y asumir en silencio que representa todo el sistema.

La paginación cambia lo que un agente puede afirmar honestamente. Un elemento devuelto demuestra que ese elemento existe. No demuestra que no haya otros. La ausencia de un elemento demuestra muy poco, a menos que el agente pueda mostrar el alcance que inspeccionó, el orden en el que se basó y por qué el servidor indicó que había terminado.

He visto agentes convertir una solicitud inocua como «buscar tokens de acceso obsoletos» en miles de llamadas porque nadie les indicó dónde termina el descubrimiento. También he visto que un inventario de una sola página llevó a intentar limpiar cuentas que estaban en la página dos. La solución no está en redactar mejor el prompt. Hay que dar al agente un contrato de recorrido acotado y hacer que su informe final deje claro el límite.

Las llamadas de descubrimiento necesitan un presupuesto explícito

Toda llamada de descubrimiento paginada necesita límites que el agente no pueda ampliar en silencio. Define antes de la primera solicitud un número máximo de páginas, un número máximo de registros devueltos, un plazo y una asignación para el límite de frecuencia. Los valores adecuados dependen de la tarea, pero la existencia de límites no depende de ella.

Trata el descubrimiento como una fase separada de la acción. Durante el descubrimiento, el agente reúne identificadores y datos. No debería eliminar, rotar ni modificar objetos solo porque una página contenga algo sospechoso. Cuando tenga suficiente evidencia, puede presentar un plan acotado o iniciar una fase de acción autorizada por separado.

Un contrato útil tiene cuatro partes:

• El endpoint y todos los filtros, incluido el orden cuando la API permita elegirlo.
• Un tamaño de página y un límite máximo de páginas o registros.
• Una condición de finalización definida por la API, como la ausencia de un cursor siguiente.
• Una condición de parada temprana, como encontrar un objeto concreto o agotar el presupuesto asignado.

No confundas el límite de registros con el límite de páginas. Si el servicio permite 100 registros por página y el agente tiene un límite de 500 registros, cinco llamadas pueden ser suficientes. Si el servicio reduce el tamaño efectivo de la página por los filtros o los permisos, el mismo trabajo podría necesitar más llamadas. Una buena implementación comprueba ambos límites después de cada respuesta.

Por ejemplo, un agente al que se le pide localizar un repositorio llamado billing-service podría detenerse al recibir una coincidencia exacta si el filtro y el orden del endpoint permiten llegar con seguridad a esa conclusión. Un agente al que se le pide identificar todos los repositorios sin protección de ramas no puede detenerse en la primera coincidencia. Esa tarea requiere una enumeración completa o un resultado parcial explícito.

La palabra «todos» debe tener un coste. Un agente solo puede usarla después de que el recorrido alcance la condición terminal del servidor sin superar su presupuesto de páginas, registros, tiempo o errores. Si se activa uno de esos límites, el informe debe decir «análisis parcial» e indicar el límite alcanzado.

El tamaño de página controla el coste, no la integridad del resultado

El parámetro limit, per_page o page_size indica al servicio cuántos registros debe intentar devolver en una respuesta. No indica cuánto de la colección necesita inspeccionar el agente. Establecerlo en el máximo reduce algunos viajes de ida y vuelta, pero puede hacer que cada respuesta sea tan costosa que provoque un tiempo de espera, supere el presupuesto de contexto o esconda detalles importantes entre una gran cantidad de datos irrelevantes.

Empieza con la página más pequeña que permita tomar la decisión. Si un agente necesita una cuenta exacta, normalmente es mejor solicitar 20 registros breves que 1.000 objetos completos. Si tiene que crear un inventario, usa un tamaño de página mayor, compatible con el servicio, solo después de confirmar que el endpoint devuelve una representación acotada y útil.

Los campos importan tanto como el tamaño de página. Muchas API ofrecen fields, include, expand o mecanismos similares. Una pasada de descubrimiento debería solicitar identificadores, nombres, estado, marcas de tiempo y la propiedad que determina la decisión. Recupera el detalle completo solo de los candidatos que necesiten inspección. Así reduces el tráfico y das al modelo menos texto incidental que pueda interpretar mal.

Cuando el proveedor admita paginación por cursor, usa una forma de solicitud como esta:

GET /v1/projects?state=active&limit=50&sort=id HTTP/1.1
Authorization: Bearer injected-by-gateway
Accept: application/json

Y espera una respuesta que separe los registros del estado de continuación:

{
  "data": [
    {"id": "prj_104", "name": "billing-service", "state": "active"}
  ],
  "next_cursor": "eyJvcmRlciI6ImlkIiwicG9zIjoiMTA0In0"
}

El agente debe registrar que solicitó 50 registros y recibió uno. No debe inferir que terminó a partir de la longitud reducida del array. En este ejemplo, la única señal útil de finalización es la ausencia de next_cursor o su valor nulo documentado.

Evita una regla arbitraria como «usar siempre 100». El tamaño máximo varía según la API, y algunos servicios cuentan los objetos secundarios expandidos o los bytes de la respuesta dentro de límites diferentes. Solicita el máximo documentado solo cuando la tarea se beneficie de ello. Para análisis amplios, un tamaño de página medio suele ofrecer mejores puntos de control, reintentos más sencillos e informes que una persona puede auditar.

Conserva los cursores como estado opaco del servidor

Un cursor no es un desplazamiento con un nombre sofisticado. El servidor controla su significado y el agente debe copiarlo byte por byte en la siguiente solicitud. Puede codificar una posición de ordenación, un identificador de instantánea, un límite de permisos o una firma. Que parezca Base64 no autoriza a descodificarlo, editarlo o fabricarlo.

El bucle seguro es sencillo: solicita la primera página con filtros y parámetros de ordenación estables, guarda el cursor que devuelve esa respuesta y envía después la misma consulta con ese cursor. Conserva todos los parámetros originales, salvo que la documentación de la API indique explícitamente lo contrario. Cambiar el filtro entre solicitudes puede invalidar el cursor o, peor aún, producir un conjunto de resultados aparentemente válido pero discontinuo.

request = { state: "active", limit: 50, sort: "id" }
seen_ids = set()
pages = 0

while pages < 10 and len(seen_ids) < 500:
    response = GET /v1/projects with request
    record response status, request, and response cursor

    for item in response.data:
        if item.id in seen_ids:
            report "duplicate record encountered" with item.id
            stop or apply the provider's documented recovery method
        seen_ids.add(item.id)

    pages += 1
    if response.next_cursor is absent:
        report "complete"
        break

    request.cursor = response.next_cursor
else:
    report "partial: traversal budget reached"

La comprobación de duplicados no es decorativa. Las colecciones mutables pueden cambiar mientras el agente las recorre, y existen implementaciones de paginación defectuosas. Un duplicado no siempre significa que el servicio haya fallado, pero sí que el agente debe dejar de fingir que tiene una enumeración limpia. Si el proveedor ofrece un token de instantánea, un parámetro as_of o un modo de consistencia documentado, úsalo para trabajos que puedan conducir a una acción importante.

La caducidad del cursor necesita una regla explícita. Algunos servicios hacen que los cursores duren poco; otros los vinculan a una sesión o los invalidan cuando cambia una consulta. Ante una respuesta que indique que el cursor ha caducado, el agente debe conservar el error y después reiniciar desde un punto de control estable o finalizar el análisis como incompleto. No debe avanzar saltándose páginas al adivinar un cursor nuevo.

Un reinicio también puede crear una falsa sensación de integridad. Si los registros cambiaron entre la primera pasada y el reinicio, una lista combinada puede contener omisiones o duplicados. Informa del reinicio y de la condición usada para continuar, como created_at >= last_observed_timestamp. Si no existe un método estable para reanudar, indica que la colección cambió durante el recorrido y no uses el resultado como lista de eliminación.

La paginación por desplazamiento se desajusta cuando cambian las colecciones

La paginación por desplazamiento usa un número como offset=200&limit=50 o page=5&per_page=50. Es fácil de programar y de explicar, por eso sigue siendo común. También se vuelve poco fiable cuando llegan registros nuevos o desaparecen registros antiguos mientras el agente recorre la colección.

Supón que la primera página devuelve los registros del 1 al 50 en orden descendente de fecha de actualización. Antes de que el agente solicite la segunda página llegan diez registros nuevos. offset=50 comienza ahora después de los registros recién insertados y se solapa con objetos que el agente ya había visto. Si en cambio desaparecen registros de la primera página, el mismo desplazamiento puede saltarse objetos que subieron de posición. El agente no puede arreglarlo solo deduplicando identificadores, porque la deduplicación detecta repeticiones, pero no omisiones.

Si la API permite un orden estable, elige uno con un criterio de desempate determinista. created_at por sí solo suele no bastar porque varios registros pueden compartir una marca de tiempo. Un orden como created_at,id, cuando el proveedor lo documenta, permite al agente registrar una marca de agua y reanudar con más cuidado. Si la API solo ofrece un desplazamiento y no proporciona una instantánea ni un orden estable, sé prudente con las conclusiones extraídas de varias páginas.

Para una tarea que necesite una respuesta completa, usa uno de estos enfoques, ordenados de mayor a menor confianza:

1. Pide al servicio una instantánea, un trabajo de exportación o un cursor que documente una vista estable.
2. Limita la consulta a un intervalo de tiempo inmutable y usa un orden estable documentado.
3. Ejecuta un segundo análisis y compara los identificadores; después informa de cualquier discrepancia.
4. Pide a una persona que apruebe un alcance más estrecho y bien definido en lugar de realizar un cambio amplio.

No conviertas una interfaz deficiente en un flujo destructivo. Un agente puede seguir usando páginas por desplazamiento para muestrear, localizar un objeto concreto o producir un inventario parcial. No debe usar un análisis inestable por desplazamiento como prueba de que ha encontrado todas las credenciales, proyectos o usuarios que coinciden.

La finalización debe proceder del protocolo, no de una intuición

Las distintas API expresan el estado de paginación en lugares diferentes. Un cuerpo JSON puede contener next_cursor, has_more o una URL para la página siguiente. Otras API usan el encabezado HTTP Link. RFC 8288 define Web Linking y el parámetro rel, usado para relaciones como next; el encabezado proporciona una relación, pero no garantiza que el cuerpo de la respuesta tenga un campo de cursor conocido.

El agente necesita una regla de finalización específica para cada endpoint. Escríbela junto a la definición de la solicitud. Por ejemplo: «Terminar cuando next_cursor sea null». O: «Terminar cuando ninguna relación de Link tenga rel="next"». No escribas: «Terminar cuando se devuelvan menos de 100 registros». Ese atajo falla con páginas filtradas, recortes por permisos, límites del servicio y API que devuelven páginas de tamaño deliberadamente irregular.

Un encabezado Link típico puede tener este aspecto:

Link: </v1/events?limit=100&cursor=a6f3>; rel="next",
      </v1/events?limit=100&cursor=first>; rel="first"

El agente debe seleccionar solo la relación que entiende. No debe concatenar el encabezado, asumir que el enlace first es un punto de control seguro para reiniciar ni deducir que la ausencia de un enlace last significa que no existe una página final. La documentación de la propia API rige su contrato de paginación; RFC 8288 solo describe cómo viajan las relaciones de enlace en los encabezados HTTP.

Algunas API devuelven has_more: true con una página vacía. Parece absurdo hasta que aparece un filtro de permisos, una eliminación simultánea o un índice retrasado. Si la API documenta este comportamiento, continúa con el token de continuación mientras el presupuesto lo permita y registra la página vacía. Si no documenta ese comportamiento, detente y marca la respuesta de paginación como incoherente. Continuar indefinidamente porque has_more sigue siendo verdadero es un error de programación, no perseverancia.

Distingue también una respuesta terminal de un estado HTTP correcto. 200 OK indica que esa solicitud concreta tuvo éxito. No indica que la colección haya terminado. Un 404 puede significar que el cursor caducó, que el endpoint no coincide o que desapareció un recurso. Conserva el estado, el cuerpo de la respuesta y el último cursor en el registro de ejecución para que una persona pueda determinar cuál de esas situaciones ocurrió.

Un resultado parcial necesita una declaración de límites

Un agente debería informar del descubrimiento como lo haría una persona operadora cuidadosa al redactar una nota de incidente: indicar qué solicitó, qué observó y qué no inspeccionó. La mayoría de los informes deficientes de los agentes fallan en la última parte. Enumeran los hallazgos, pero omiten el cursor, el límite o el error que demuestra que son incompletos.

Usa un formato de informe que una persona pueda utilizar sin reconstruir la sesión:

Scope: GET /v1/projects?state=active&sort=id
Requested page size: 50
Pages fetched: 10
Records received: 487
Completion: partial
Stop reason: page budget reached
Last continuation cursor: eyJvcmRlciI6ImlkIiwicG9zIjoiNTg3In0
Observed finding: 12 projects matched the review rule
Uninspected scope: records after the last continuation cursor
Action taken: none

La última línea importa. Una ejecución de descubrimiento debe indicar si cambió algo. Quien revise el informe nunca debería tener que deducir si el agente se limitó a enumerar objetos o actuó sobre ellos.

No expongas un cursor sensible en una transcripción de chat si el proveedor lo trata como una capacidad bearer o si su contenido puede revelar la estructura de una cuenta. Guarda el token exacto en metadatos protegidos de la ejecución y presenta después una huella o un prefijo oculto en el informe para personas. El agente necesita suficiente estado para reanudar o auditar el recorrido, pero no hace falta que los tokens de continuación queden dispersos por tickets y terminales.

El lenguaje controla el riesgo en este punto. «No encontré registros coincidentes entre los primeros 500 inspeccionados» es exacto. «No hay registros coincidentes» solo es exacto después de un recorrido completo sobre una vista suficientemente estable. La diferencia parece pedante hasta que una decisión de limpieza o cumplimiento depende de ella.

Los límites de frecuencia y los reintentos necesitan sus propias reglas de parada

La paginación amplifica los errores relacionados con los límites de frecuencia porque una sola solicitud se convierte en un bucle. Un agente que recibe 429 Too Many Requests no debe responder golpeando el endpoint repetidamente con el mismo cursor. Respeta Retry-After cuando el servidor lo proporcione, descuenta la espera del plazo de ejecución y detente cuando se agote el presupuesto de reintentos.

Para fallos transitorios, como un tiempo de espera o una respuesta 5xx, repite la misma página antes de avanzar. Si la API admite un identificador de idempotencia o de solicitud para las llamadas de lista, úsalo de acuerdo con su documentación. Nunca avances al cursor siguiente después de una respuesta incierta solo porque la solicitud podría haber tenido éxito. Eso crea un hueco silencioso.

Una política de reintentos acotada podría establecer lo siguiente:

• Reintentar la página actual como máximo dos veces después de fallos transitorios de transporte o del servidor.
• Respetar Retry-After para los límites de frecuencia si el plazo restante lo permite.
• No repetir fallos de autenticación o autorización sin un cambio en el estado de autorización.
• Detenerse ante datos de paginación mal formados, un cursor repetido o una respuesta de continuación no documentada.

Un cursor repetido merece especial atención. Si la página tres devuelve el mismo next_cursor que el agente envió, continuar puede crear un bucle infinito. Compara cada cursor nuevo con el enviado y con un conjunto de cursores anteriores. Detente ante una repetición, salvo que el proveedor documente un caso en el que sea esperable, algo poco frecuente que debería gestionarse con una regla específica para ese proveedor.

El agente debe conservar suficientes metadatos de la respuesta para diagnosticar un reintento sin guardar secretos. Registra el código de estado, la ruta de la solicitud, los encabezados seleccionados que no sean sensibles, el número de secuencia de la página, la huella del cursor, las marcas de tiempo y un resumen del cuerpo de la respuesta si la política lo permite. No pegues encabezados de autorización, tokens bearer completos ni URL con credenciales en los registros solo porque una solicitud haya fallado.

Un recorrido de un fallo demuestra por qué la primera página es peligrosa

Imagina un agente al que se le pide desactivar todas las integraciones inactivas anteriores a una fecha determinada. El endpoint de integraciones devuelve por defecto 25 elementos, los ordena por fecha de actualización más reciente y solo proporciona next_cursor cuando quedan más páginas. El agente consulta la primera página, encuentra tres integraciones inactivas y las desactiva. Después informa de que limpió las integraciones inactivas.

Ese informe es incorrecto por dos motivos. El agente no inspeccionó todas las integraciones y actuó durante el descubrimiento. Encontrar tres candidatos no dice nada sobre las páginas posteriores. Además, desactivar elementos cambia updated_at, lo que puede reordenar la colección si el endpoint usa su orden predeterminado. El agente ha hecho menos estable su propio recorrido.

Una ejecución más segura comienza con un filtro explícito y un orden estable, si la API lo admite:

GET /v1/integrations?status=inactive&updated_before=2024-01-01&limit=50&sort=id HTTP/1.1

El agente reúne los identificadores de todas las páginas sin modificarlos. Se detiene solo cuando el servidor no emite un cursor siguiente o cuando se activa su presupuesto de descubrimiento. Después informa de un conjunto completo o parcial de candidatos. Una solicitud de acción separada puede usar los identificadores reunidos, idealmente después de que una persona vea el recuento y el alcance.

Si el endpoint de lista no admite un orden estable, el agente debe decirlo. Puede seguir reuniendo candidatos, pero no debe afirmar que tiene un conjunto completo y libre de condiciones de carrera. El consejo popular de «actuar al encontrar cada elemento» parece eficiente porque ahorra una segunda pasada. Es incorrecto para listas mutables cuando la acción cambia la posición, la elegibilidad o los permisos.

El mismo patrón se aplica a hallazgos de seguridad, cuentas de usuario, registros de despliegue y artefactos de compilación. Primero lee, establece el alcance y después cambia. Hay excepciones para la contención urgente, como revocar una credencial comprometida concreta, pero eso no es un trabajo de limpieza paginado. Es una acción específica con un identificador conocido.

Mantén las credenciales y la observabilidad fuera del agente

Un agente no debería necesitar el secreto de la API solo para paginar. El componente que ejecuta las solicitudes HTTP puede inyectar las credenciales, exigir autorización humana cuando sea necesario y registrar la secuencia real de solicitudes. Así el agente se concentra en construir e interpretar consultas, en lugar de manejar tokens que le permitirían ejecutar llamadas sin límite en otros lugares.

Para los equipos que usan Sallyport, las llamadas HTTP pueden pasar por su puerta de enlace de acciones mientras las credenciales permanecen en la bóveda cifrada, y el diario de actividad registra cada llamada. Ese registro ayuda a quien revisa a comparar el número de páginas declarado por el agente con las solicitudes que realmente se ejecutaron, pero no sustituye los presupuestos de páginas en las instrucciones del agente.

Mantén la política de recorrido cerca de la definición de la tarea. Especifica los endpoints permitidos, los filtros, los campos, el número máximo de páginas, el comportamiento de los reintentos y la declaración de límites obligatoria. Una capa de autorización general no puede decidir si un análisis de un repositorio termina después de una página o si un inventario de cumplimiento necesita todas las páginas.

El diario de sesiones y el registro de actividad por llamada de Sallyport pueden hacer práctica la revocación y la revisión cuando una ejecución del agente se desvía. Aun así, hay que indicar al agente que se detenga ante una forma de cursor desconocida, un presupuesto agotado o una respuesta de la API que contradiga el contrato documentado del endpoint. Registrar un rastreo incorrecto después de los hechos es mejor que no tener pruebas, pero no deshace las llamadas innecesarias ni una acción equivocada.

Prueba el recorrido con casos de paginación adversos

La paginación del caso ideal oculta los defectos importantes. Antes de confiar en un flujo de trabajo de agente, pruébalo con casos que devuelvan una primera página vacía con cursor, una página corta con más resultados, un elemento duplicado, un cursor repetido, un cursor caducado y una respuesta de límite de frecuencia entre dos páginas normales.

El comportamiento esperado debe ser aburrido y específico. El agente continúa después de una página vacía solo cuando el estado de continuación documentado indica que debe hacerlo. Deduplica o se detiene ante identificadores repetidos según el requisito de consistencia de la tarea. Nunca inventa un cursor después de su caducidad y notifica una cobertura parcial cuando un límite de seguridad termina la ejecución.

Usa esta tabla de aceptación al revisar un bucle de llamadas a herramientas:

Inspecciona las llamadas sin procesar además del texto final. Un informe pulido puede ocultar un cursor omitido o una solicitud adicional después de la condición de parada. El registro de ejecución debe mostrar una solicitud inicial, cada solicitud de continuación, cualquier reintento del mismo cursor y ninguna llamada posterior a la respuesta terminal.

Establece un presupuesto predeterminado pequeño para el trabajo exploratorio y exige un cambio explícito de tarea para las enumeraciones amplias. Esa única restricción evita los dos fallos que más tiempo desperdician: agentes que analizan sin parar y agentes que confunden en silencio la primera página con la respuesta completa.