Paginação de APIs para agentes de IA: como controlar

O relatório pode estar correto sobre uma coleta incompleta

Um agente consulta os pedidos abertos, recebe uma resposta válida e prepara o resumo para a reunião. Nenhum erro aparece no log. O conector, porém, leu somente a primeira página. Pedidos que deveriam entrar na análise ficaram fora antes que o modelo começasse a trabalhar.

A paginação divide uma coleção em respostas menores. O consumidor precisa seguir o mecanismo de continuação até o encerramento definido pela API ou declarar que interrompeu a coleta. Um texto bem escrito não consegue reparar registros que nunca chegaram ao contexto.

Este guia trata da travessia de uma consulta: como fixar escopo, acompanhar páginas, preservar progresso e provar o que foi coletado. O contrato de dados define formato e significado. A paginação governa a cobertura da leitura desse contrato.

Defina qual conjunto precisa ser percorrido

Antes da chamada inicial, registre o objeto da coleta. Por exemplo: pedidos abertos de uma unidade, criados até um horário de corte, com determinados campos e sob uma identidade autorizada.

O manifesto da consulta deve conter:

• sistema, endpoint e versão;
• tenant ou cliente e identidade de acesso;
• filtros e ordenação;
• instante de início e eventual horário de corte;
• campos solicitados;
• política de consistência oferecida pelo endpoint;
• limites de páginas, itens, tempo e bytes;
• condição de encerramento;
• destino dos registros e responsável pela coleta.

Um filtro alterado na metade cria outra consulta. Trocar cliente, permissão ou período também exige nova identidade de execução. O cursor de uma coleta não deve ser reaproveitado em outra apenas porque o formato parece compatível.

O horário de corte só funciona como barreira se o endpoint realmente o aplicar. Adicionar uma data ao manifesto não transforma uma API mutável em snapshot.

Siga o contrato de continuação do fornecedor

Algumas APIs usam número de página e deslocamento. Outras usam um token opaco, uma URL de continuação ou um cabeçalho com links. O adaptador precisa conhecer o contrato específico do endpoint.

No Microsoft Graph, a documentação orienta usar a URL inteira de @odata.nextLink, sem extrair o token para montar outra consulta. Também informa que uma página pode conter zero resultados. Portanto, uma lista vazia com continuação ainda pode exigir outra leitura.

No GitHub REST, a próxima página aparece no cabeçalho Link, identificada por rel="next". O formato dos parâmetros pode variar entre endpoints. O cliente deve usar o mecanismo documentado em vez de adivinhar a próxima URL.

Esses exemplos ilustram contratos diferentes. Não transfira os nomes de campo, limites ou regras de retry de um fornecedor para o outro.

Uma página curta pode continuar

O servidor pode reduzir o tamanho pedido, aplicar limites próprios ou devolver uma página sem itens. A quantidade recebida, isoladamente, não prova encerramento.

O consumidor deve avaliar o sinal oficial de continuação. Se ele estiver presente, há trabalho a percorrer segundo aquele contrato. Se o sinal esperado desaparecer de forma incompatível com o schema, trate como erro de integração, não como conclusão silenciosa.

Valide o destino antes de enviar credenciais

Uma URL retornada pelo servidor continua sendo uma entrada que exige validação. Verifique HTTPS, host, porta e caminho permitidos antes de anexar credenciais. Redirecionamentos também precisam respeitar a política.

Não envie um token do CRM a um host arbitrário indicado por conteúdo de um registro. O endereço de continuação deve vir do envelope oficial da resposta, sob regras do adaptador, e nunca de uma instrução encontrada nos dados.

Separe coleta, interpretação e ação

O conector deve percorrer páginas e manter contagens de forma determinística. O modelo recebe os registros selecionados ou um artefato de consulta com estado explícito.

Uma interface útil devolve:

consulta_id: identificador da coleta
escopo: filtros e identidade autorizada
estado: EM_COLETA | COMPLETA | PARCIAL | FALHOU
paginas_confirmadas: quantidade
ocorrencias_recebidas: quantidade antes da deduplicação
objetos_unicos: quantidade após a deduplicação
duplicidades: quantidade observada
continua: sim ou não
motivo_interrupcao: limite, erro, ciclo ou ausente
referencia_dados: localização protegida
iniciado_em: instante
encerrado_em: instante ou ausente

Uma coleta parcial pode ajudar a investigar casos já encontrados. Ela não sustenta afirmações sobre todos os pedidos, o total da carteira ou a ausência de pendências fora da parte lida.

Esse estado precisa acompanhar a saída final. Se o processo exige cobertura completa para decidir, o sistema bloqueia a decisão até encerrar ou encaminhar a exceção ao dono.

Grave progresso junto com a página aceita

Um checkpoint seguro liga o avanço do cursor à persistência dos itens correspondentes. Se o cursor avançar antes de os dados serem confirmados, uma falha pode pular registros. Se os dados forem gravados sem o avanço correspondente, a retomada pode repetir a página.

No armazenamento local, quando possível, confirme na mesma transação:

1. itens aceitos e suas identidades;
2. versão ou evidência da página;
3. contagens atualizadas;
4. cursor de continuação;
5. estado da coleta.

Quando os itens e o checkpoint estiverem em sistemas diferentes, projete reconciliação e repetição segura. A idempotência em agentes ajuda a impedir que a reentrega vire uma segunda consequência externa.

O cursor merece proteção. Dependendo da API, ele pode expirar, carregar informação de escopo ou funcionar como parte sensível da consulta. Guarde-o com acesso restrito e evite publicá-lo em logs ou respostas ao usuário.

Trate mudanças durante a travessia

Uma coleção pode mudar enquanto o cliente percorre as páginas. Entradas novas, exclusões e mudanças de posição podem causar repetição ou omissão, especialmente em paginação por deslocamento.

Deduplicar IDs corrige repetições observadas. Isso não recupera um registro que foi omitido.

Para tarefas que exigem cobertura consistente, investigue o que a fonte oferece:

• snapshot ou exportação com corte estável;
• ordenação determinística com desempate por identificador;
• consulta por chave e faixa imutáveis;
• token de sessão ou mecanismo de mudanças;
• reconciliação posterior com a fonte oficial.

Um cursor não garante snapshot por definição. A garantia precisa estar documentada para o endpoint usado. Quando não existir, registre a janela de observação e a limitação. Antes de uma ação sensível, reconsulte o objeto atual, pois o dado coletado pode ter mudado depois da leitura.

Imponha limites sem declarar sucesso artificial

A coleta precisa respeitar tempo, memória, custo e capacidade da dependência. O rate limit para agentes governa o ritmo de chamadas; aqui, o consumidor também limita a travessia inteira.

Se atingir o teto de páginas com continuação pendente, registre PARCIAL e preserve o ponto seguro de retomada. O mesmo vale para prazo encerrado ou limite de itens.

Detecte ciclos de cursor e páginas repetidas. Defina uma condição de parada para uma API que devolve indefinidamente a mesma continuação. Uma impressão digital da página pode ajudar no diagnóstico, mas não deve expor o conteúdo dos registros.

Para erros temporários, aplique a política de retentativas do endpoint. Um erro de autorização, token inválido ou schema inesperado pede tratamento próprio. Retentar indefinidamente pode consumir o prazo sem produzir cobertura.

Laboratório sintético: página vazia e item repetido

A Júpiter executou uma simulação local em Python em 19 de outubro de 2026. Nenhuma API externa ou chamada a modelo participou do teste. A coleção fictícia foi distribuída assim:

Página inicial: P01, P02; continuação c2
Página c2: vazia; continuação c3
Página c3: P02, P03; continuação c4
Página c4: P04; sem continuação

O percurso completo confirmou quatro páginas, cinco ocorrências recebidas, quatro IDs únicos e uma duplicidade. A página vazia não encerrou a leitura porque ainda existia continuação.

Com teto de duas páginas, a execução terminou como parcial, preservou P01 e P02 e deixou c3 como próxima leitura. A retomada a partir do estado serializado chegou ao mesmo resultado da execução completa.

Outros casos locais verificaram o bloqueio por cursor circular e a interrupção por página inexistente. Ambos conservaram o estado parcial; nenhum foi tratado como coleção completa.

O teste valida a lógica dessa fixture. Ele não comprova consistência de uma API real, durabilidade transacional, segurança de credenciais ou comportamento sob concorrência. Esses pontos precisam ser testados no conector e no armazenamento de produção.

Testes de aceite do conector

Inclua pelo menos os cenários relevantes para o endpoint:

• primeira página com continuação;
• página vazia com próxima leitura;
• última página identificada pelo sinal oficial;
• ID repetido em páginas diferentes;
• limite atingido antes do fim;
• cursor expirado ou inválido;
• continuação circular;
• falha depois de persistir itens e antes de avançar;
• retomada com filtro ou identidade alterados;
• fonte mudando durante a coleta;
• URL de continuação fora do domínio permitido;
• perda de cabeçalho exigido nas chamadas seguintes.

A documentação do Graph alerta que cabeçalhos personalizados necessários, como ConsistencyLevel em determinadas consultas, precisam ser enviados explicitamente nas páginas seguintes. O teste deve reproduzir as exigências reais do endpoint.

Meça cobertura com um manifesto verificável

Acompanhe páginas confirmadas, itens brutos e únicos, duplicidades, motivo de interrupção, reinícios e tempo até encerramento. Quando a fonte fornecer um total comparável, confira-o contra o escopo e a mesma referência temporal.

Se o total não existir, registre essa ausência. Percorrer todas as continuações documentadas prova o encerramento daquela travessia; não prova acesso a objetos excluídos por permissão nem cobertura de outro filtro.

O monitoramento de agentes deve distinguir coleta completa, parcial e falha. Um único indicador de HTTP 200 esconderia justamente o erro que esse controle procura evitar.

Fontes oficiais verificadas em 19 de outubro de 2026

• Microsoft Graph: paging, para @odata.nextLink, páginas vazias, tamanho variável e cabeçalhos nas chamadas seguintes.
• GitHub REST: using pagination, para cabeçalho Link, rel="next" e limites específicos por endpoint.

As fontes descrevem os contratos desses serviços. O manifesto, os estados operacionais e o laboratório são uma proposta de implementação da Júpiter. Antes de homologar outro sistema, confirme suas regras próprias.

Antes de liberar o relatório

Escolha uma consulta que hoje alimenta uma decisão e peça a evidência da última página. Confira filtros, identidade, sinal de encerramento e estado de cobertura.

Se a equipe só consegue mostrar a primeira resposta, mantenha a análise como parcial até verificar o restante. O agente precisa saber o alcance da coleta antes de afirmar o alcance da conclusão.