Paginação de API em agentes de IA: buscar todas as páginas ou sinalizar
Método prático para agentes de IA lerem APIs paginadas: seguir cada cursor, checar se a leitura está completa e sinalizar lacunas para revisão.

Um agente de IA deve seguir todas as páginas de uma resposta paginada de API usando o sinal de continuação documentado pelo fornecedor, e não por suposição. Ele deve registrar o que cada página trouxe, confirmar que a leitura terminou em um sinal de fim claro e comparar suas contagens com qualquer total informado pela fonte. Se uma página falhar, um cursor for rejeitado ou as contagens divergirem sem explicação, o agente deve marcar o resultado como incompleto e enviá-lo a uma pessoa nomeada antes que alguém dependa dele.
Principais pontos
- Siga o sinal de continuação da própria API, como um cursor seguinte, um link seguinte ou um indicador de mais resultados, até que ele termine com clareza. Nunca presuma o fim da lista só porque a página veio curta.
- Trate cursor expirado, token repetido ou timeout como uma pergunta a responder, e não como o fim dos dados.
- Guarde um recibo de conclusão para cada leitura: páginas lidas, registros recebidos, o último token, as novas tentativas e as lacunas.
- Quando não for possível provar que a leitura está completa, marque-a como incompleta e bloqueie qualquer ação posterior até que um revisor decida.
- Desenhe a ferramenta para que o estado da paginação chegue em campos estruturados, para que o agente não precise interpretar texto livre.
Por que a paginação é arriscada para um agente?
A maioria dos sistemas de negócio não devolve a lista inteira em uma única resposta. Eles devolvem um recorte de registros mais um token ou link que aponta para o próximo recorte. Uma pessoa percebe quando a lista para de aparecer na tela. Um agente que lê o primeiro recorte e escreve um resumo pode facilmente tratar esse recorte como resposta completa, e nada no texto que ele recebe vai avisar sobre a lacuna.
A paginação cria quatro falhas típicas. A primeira é o corte silencioso, em que o laço para cedo por causa de um timeout, de um limite de páginas ou de um campo mal interpretado. A segunda é a deriva: registros são inseridos, removidos ou reordenados durante a leitura, então um registro aparece duas vezes e outro some. A terceira são cursores expirados ou reutilizados, que algumas APIs invalidam depois de certo tempo. A quarta é a falha parcial, em que um limite de requisições ou um erro do servidor interrompe a leitura depois de muitas páginas já lidas. As regras de nova tentativa importam aqui e são tratadas em Limites de taxa para agentes de IA: regras de nova tentativa, backoff e fila. Para a paginação, o ponto central é que uma nova tentativa deve retomar a partir do último token confirmado, e não recomeçar em silêncio.
Como um agente deve seguir uma API paginada?
O agente deve seguir exatamente o mecanismo de continuação documentado. Os passos abaixo podem ser executados por um wrapper de ferramenta ou pelo harness do agente, o que tira a suposição das partes em que ela causa dano.
- Envie a primeira requisição com ordem explícita e o maior tamanho de página que o fornecedor permitir, para que a requisição possa ser reproduzida.
- Leia o sinal de continuação documentado em cada resposta e não trate uma página curta como prova de que a lista acabou.
- Busque a página seguinte usando apenas o token da resposta anterior, mantendo cada parâmetro da consulta idêntico ao da primeira requisição.
- Antes de avançar, salve os identificadores dos registros da página, o token usado para buscá-la e o horário da requisição.
- Pare somente quando o sinal de continuação estiver ausente ou falso, e registre qual sinal encerrou o laço.
- Se uma página falhar, tente novamente a partir do mesmo token, respeitando as regras de limite do fornecedor. Se o token for rejeitado, marque a leitura como incompleta em vez de recomeçar da primeira página sem deixar registro.
Recomeços importam para escritas. Uma leitura reprocessada não pode gerar ações duplicadas, então qualquer escrita posterior deve usar um identificador estável como chave. O padrão é descrito em Ações idempotentes em agentes de IA: evite faturas e reservas duplicadas.
Como o agente confirma que leu todas as páginas?
Terminar o laço não é o mesmo que provar completude. A verificação de completude deve ser um conjunto curto de fatos que o agente consegue declarar e que uma pessoa consegue auditar. Use esta lista antes de descrever qualquer resultado como completo:
- O laço terminou no sinal de fim documentado pelo fornecedor, e o agente consegue nomear esse sinal.
- Cada requisição usou um token vindo da resposta anterior, nenhum token se repetiu e nenhuma sequência voltou para trás.
- O número de identificadores únicos corresponde ao número de registros recebidos, para que duplicatas entre páginas tenham sido percebidas.
- Se o fornecedor informar um total, a contagem única bate com ele, ou a diferença foi registrada junto com o motivo que o fornecedor apresenta.
- A chave de ordenação foi fixada na primeira requisição, e o agente confirmou que os registros devolvidos seguem essa ordem.
- Um recibo de conclusão foi guardado com a consulta, os horários de início e fim, as páginas lidas, o token final e as novas tentativas.
Um total informado pode mudar durante uma leitura ao vivo, porque registros são criados ou removidos do lado do fornecedor. Uma divergência é, portanto, uma informação, e não uma falha automática. O agente deve registrá-la e aplicar as regras de sinalização da seção seguinte, em vez de ajustar a contagem até os números baterem. Tratar cada leitura como uma operação rastreada, com registro claro de cada passo, segue a mesma lógica de observabilidade usada em sistemas de software. Esse comportamento também pode ser testado antes da liberação com um conjunto de casos conhecidos.
Quando o agente deve sinalizar uma leitura incompleta?
Sinalizar é uma instrução para parar de depender do resultado e perguntar a uma pessoa nomeada o que fazer em seguida. Uma sinalização custa uma pequena demora, enquanto um resumo confiante feito sobre uma lista parcial pode custar muito mais. Use este guia de decisão:
- Sinalize quando qualquer página depois da primeira falhar com erro de servidor, timeout ou limite de requisições que as regras de nova tentativa não consigam resolver.
- Sinalize quando um token estiver expirado, rejeitado ou voltar duas vezes, porque a sequência não pode mais ser confiável.
- Sinalize quando a contagem única e o total informado forem diferentes e o fornecedor não oferecer explicação.
- Sinalize quando a leitura alimentar um pagamento, uma mensagem a cliente, uma exclusão, uma mudança de status ou um relatório financeiro.
- Sinalize quando o laço atingir um teto de páginas definido por custo ou tempo, porque um laço interrompido não é um laço concluído.
- Não sinalize, mas guarde o recibo, quando a leitura terminar no sinal documentado, as contagens baterem e a saída for um resumo interno somente leitura.
Uma sinalização deve dizer quatro coisas: qual consulta foi executada, quais páginas foram confirmadas, onde a sequência quebrou e qual ação está bloqueada agora. A rota de revisão deve ser definida antes da entrada em produção. Por exemplo, o canal de chat da equipe pode entregar a sinalização a um responsável nomeado de operações, com escolhas claras como tentar de novo, aceitar como parcial ou cancelar. O padrão de aprovação é descrito em Botões de aprovação no Slack para agentes de IA: decida antes de gravar.
O que uma ferramenta deve devolver para que a paginação seja honesta?
Muitos problemas de paginação começam no desenho da ferramenta, e não no modelo. Se a ferramenta devolve apenas uma lista de registros, o agente precisa deduzir o estado pela presença ou ausência de dados. Uma ferramenta melhor devolve a paginação como campos nomeados: os registros, um próximo cursor ou nulo, um indicador booleano de existirem mais resultados, a contagem retornada nesta página e um total apenas quando o sistema de origem o fornecer.
Os erros merecem o mesmo cuidado. Cursor expirado, limite de requisições e problema de permissão precisam de códigos distintos, porque cada um leva a uma ação diferente. A ferramenta também deve aceitar um número máximo explícito de páginas, e, ao atingir esse teto, a resposta deve dizer que a leitura está incompleta, em vez de devolver uma lista parcial com aparência de completa. Descrições e mensagens de erro fazem parte do contrato, e as escolhas de desenho são explicadas em Esquema de ferramentas para agentes de IA: campos tipados e erros claros.
Cenário ilustrativo: uma coleta de catálogo de fornecedor
O cenário a seguir é ilustrativo e não descreve um cliente real. Um responsável de operações pede a um agente que compare o catálogo atual de um fornecedor com os preços registrados na planilha de compras. A API do fornecedor devolve o catálogo em páginas e informa um próximo cursor em cada uma.
O agente lê as primeiras páginas sem problemas, salva os identificadores de cada uma e guarda todos os cursores. No meio do caminho, a conexão cai, e a nova tentativa devolve um cursor que o agente já tinha usado. Pelas regras acima, o agente não continua a partir desse ponto nem recomeça por conta própria. Ele salva um recibo listando as páginas confirmadas, marca a leitura como incompleta e envia a sinalização ao responsável de compras, indicando que a comparação está bloqueada.
O responsável decide repetir a leitura com a mesma chave de ordenação em um horário de menor movimento e comparar apenas os registros presentes nos dois recibos. A segunda leitura termina, as contagens batem, e a comparação é liberada com o recibo anexado. Nada foi resumido a partir de uma lista parcial, e ninguém precisou reconstruir o histórico de memória.
Como a Be Human trata a paginação em operações gerenciadas
Em uma primeira implantação da Be Human, a paginação é tratada como parte do contrato da ferramenta, e não como um detalhe escondido em um prompt. A equipe define quais sinais de continuação cada fonte usa, o que o recibo de conclusão contém, quais condições disparam uma sinalização e quem é o revisor nomeado, tudo antes de o agente ter permissão para agir sobre uma leitura. Em operações gerenciadas, o trabalho continua: os recibos são acompanhados, as sinalizações são revisadas quando disparam e a ferramenta é ajustada quando um fornecedor muda a forma de paginar seus resultados. O objetivo é um registro simples do que foi lido e do que não foi, para que a empresa decida com base em evidência. Para encontrar a primeira tarefa que vale entregar a um agente, faça o diagnóstico gratuito de IA da Be Human.
Perguntas frequentes
Como o agente deve agir se a API não tiver cursor seguinte nem total? O agente não deve concluir que o resultado está completo só porque a resposta chegou. Ele deve procurar outro sinal de fim documentado, como um link seguinte ou um campo de contagem, e, se nenhum existir, registrar que a completude não pode ser provada pela resposta. Essas leituras devem ser sinalizadas para revisão ou substituídas por uma segunda leitura cujos recibos sejam comparados.
Um agente pode estimar o número de páginas antecipadamente? Não. Uma estimativa baseada em total ou tamanho de página pode estar errada se os registros mudarem durante a leitura, e esconde a regra de parada real. O agente deve seguir o sinal de continuação e informar as páginas que de fato leu, usando qualquer total informado apenas como verificação do resultado.
O agente pode resumir uma leitura parcial? Pode, mas somente se o resumo for rotulado como parcial e disser quais páginas foram confirmadas e em que ponto a sequência quebrou. Apresentar uma lista parcial como resposta completa é o principal risco que este artigo busca evitar. Para qualquer coisa que dirija um pagamento, uma mensagem ou uma mudança de status, o resultado parcial deve continuar bloqueado até que uma pessoa o aceite ou uma leitura completa o substitua.
Quem deve revisar uma leitura sinalizada? O revisor deve ser a pessoa dona do processo de negócio, e não apenas o engenheiro que construiu o conector. Para dados de compras, costuma ser o responsável por compras, e para dados financeiros, a pessoa responsável pela contabilidade. A rota de revisão deve ser definida antes da entrada em produção, com uma lista curta de escolhas, como tentar de novo, aceitar como parcial ou cancelar, para que a decisão fique com o dono do processo.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


