Quando uma ferramenta entrega apenas parte dos resultados, o agente precisa receber uma indicação explícita dessa limitação e um caminho para continuar a consulta. A solução é separar três situações: uma coleção paginada, um documento recortado e uma saída interrompida por limite de transporte. Cada uma exige um marcador diferente; nenhuma autoriza o agente a concluir que leu tudo.
Projete a ferramenta para devolver dados acompanhados de metadados verificáveis. Depois, faça o controlador da automação acompanhar páginas, identificadores e condições de parada. O modelo pode interpretar os registros recebidos, mas a confirmação de cobertura deve vir do código que executa a busca.
Resumo rápido
- Uma resposta curta não demonstra que a coleção terminou.
- Preserve o cursor fornecido pela API e siga o contrato do serviço.
- Diferencie cobertura parcial, conclusão confirmada e falha de leitura.
- Não envie documentos inteiros ao contexto quando bastam trechos identificados.
- Teste páginas vazias, cursores repetidos e cortes no meio de registros.
Onde o truncamento acontece
Imagine que uma ferramenta consulta chamados e devolve uma lista aparentemente válida. Ela pode ter retornado a primeira página da API, selecionado somente algumas colunas, cortado descrições longas ou sofrido um limite na camada que apresenta o resultado ao agente. Esses eventos têm consequências diferentes. Um chamado ausente da primeira página continua disponível. Uma frase cortada perdeu parte do conteúdo. Uma resposta JSON incompleta talvez nem possa ser interpretada.
Por isso, registre a fronteira do corte. O servidor consultou todos os registros? O adaptador recebeu a resposta integral? O componente que monta a mensagem reduziu o conteúdo? O modelo viu os metadados? Responder a essas perguntas localiza a correção. Aumentar indiscriminadamente o contexto não conserta uma consulta que nunca buscou a página seguinte.
Também separe intenção de cobertura. Para responder “mostre três exemplos”, uma amostra identificada pode bastar. Para responder “nenhum cliente ficou sem atendimento”, é necessário estabelecer quais clientes entraram no universo verificado. O segundo pedido envolve uma conclusão negativa e exige evidência de exaustividade. Uma busca parcial pode encontrar uma ocorrência, mas não demonstrar sua inexistência.
Essa distinção complementa o tratamento de fontes ausentes e fontes contraditórias: ausência no material recebido não equivale a ausência no sistema original. A resposta deve representar o alcance real da consulta.
Escolha marcadores que descrevam a cobertura
Adote um envelope próprio no adaptador, preservando os campos originais do serviço. Uma proposta é incluir items, coverage, continuation e source_query_id. São nomes ilustrativos, não um padrão universal. Em coverage, indique se a consulta está parcial, completa ou indeterminada. Use “completa” apenas quando o contrato da origem confirmar o fim e todas as páginas recebidas tiverem sido processadas.
| Situação | Marcador sugerido | Próxima ação |
|---|---|---|
| Coleção ainda paginada | Parcial com continuação | Solicitar a próxima página |
| Documento abreviado | Trecho com posição e versão | Ler intervalo específico |
| Transporte interrompido | Falha sem conteúdo validado | Repetir leitura segura |
| Fim confirmado pela origem | Completa para a consulta registrada | Consolidar resultados |
| Orçamento esgotado | Parcial com motivo de parada | Entregar ressalva ou encaminhar |
Para documentos, guarde referência, versão, intervalo e indicação de continuidade. “Linhas 120 a 180 de contrato X, versão Y” é mais útil que “conteúdo reduzido”. Se o documento mudar entre leituras, o intervalo poderá apontar para outro texto. A identificação de versões dos documentos citados ajuda a tornar essa recuperação auditável.
Não misture o resumo produzido pelo modelo com a marcação de integridade. O resumo pode estar correto sobre a parte lida e ainda assim representar cobertura parcial. Mantenha os dois resultados separados, inclusive no armazenamento.
Paginação: siga o contrato da origem
A AIP-158 do Google explica um contrato em que next_page_token indica continuação. Nesse desenho, uma página pode conter menos itens que o solicitado, inclusive nenhum, sem representar o fim. O cliente deve observar o marcador definido pela API. Se a equipe trabalha com esse fornecedor, o catálogo de integrações do Google reúne outros pontos de conexão do ecossistema.
No contrato de paginação do MCP, operações de listagem podem devolver nextCursor. O cursor é opaco: o cliente deve repassá-lo, sem deduzir sua estrutura. Essa especificação também orienta a não persistir cursores entre sessões. Portanto, um mecanismo de retomada durável precisa respeitar as regras específicas da integração; não basta gravar qualquer token e reutilizá-lo indefinidamente.
Já a documentação REST do GitHub mostra a continuação pelo cabeçalho Link. Um adaptador que guarda somente o corpo e descarta os cabeçalhos pode perder justamente a informação necessária para buscar a próxima página. Preserve o sinal original antes de convertê-lo para o envelope interno.
Na consulta a uma base própria, defina ordenação estável. A documentação do PostgreSQL alerta que LIMIT sem uma ordenação determinística pode selecionar subconjuntos imprevisíveis. Na aplicação, escolha uma chave de desempate e documente como alterações concorrentes afetam a leitura. Uma lista ordenada somente pela data pode ter vários registros com o mesmo horário.
Controle a coleta antes de pedir a síntese
Uma arquitetura simples tem duas fases. Primeiro, o coletor percorre as páginas e valida seus identificadores. Depois, a etapa de linguagem recebe o material necessário para interpretar o resultado. Essa separação facilita interromper a coleta sem produzir uma conclusão excessiva. Também permite fazer contagens e eliminar duplicidades por código, sem gastar contexto com todos os campos.
Defina limites explícitos de páginas, duração e volume. Quando um limite for atingido, preserve o motivo da parada e os registros já confirmados. A mensagem ao usuário pode dizer que a consulta analisou determinada parte e que a consolidação ainda está pendente. Não transforme uma proteção de custo em um atestado de conclusão.
Detecte cursor repetido e ausência de progresso. Se duas respostas sucessivas apontarem para o mesmo cursor e não trouxerem identificadores novos, interrompa com erro operacional. Contudo, não use “nenhum item novo” isoladamente como regra de fim: a origem pode devolver páginas sobrepostas e continuar validamente. A proteção precisa distinguir falha provável de encerramento comprovado.
Para cada página, registre identificador da consulta, filtros normalizados, horário da leitura, quantidade recebida e quantidade aproveitada. Evite incluir dados pessoais ou tokens completos em logs. Uma impressão digital do marcador pode ajudar a reconhecer repetição sem expor seu conteúdo. Para inspeção detalhada, use armazenamento com acesso restrito e retenção definida.
A síntese deve receber uma instrução curta e objetiva: conclusões globais dependem de cobertura completa. Se faltarem páginas, apresente achados locais e a ressalva correspondente. No fluxo que atualiza sistemas, use essa condição como bloqueio programático, não como preferência textual. A ferramenta de escrita só fica disponível quando o controlador valida os requisitos.
Exemplo: conciliação de chamados em Campinas
Considere uma assistência técnica de Campinas que usa um agente para localizar pedidos de orçamento sem retorno. Este é um cenário ilustrativo. A consulta busca chamados abertos em um período definido e recebe páginas com identificadores, status e última interação. O objetivo é preparar uma lista para revisão da supervisora, sem enviar mensagens automaticamente.
Na primeira página, todos os chamados encontrados já têm retorno. Se o agente concluir “não há pendências”, terá respondido antes de verificar o restante. O adaptador marca a cobertura como parcial e fornece a continuação ao coletor. Em uma página posterior, aparece um chamado sem resposta. Ele entra na lista, acompanhado da referência que permite à supervisora abrir o registro original.
Suponha agora que uma descrição termine no meio de uma frase. O coletor mantém o chamado, mas marca o campo como abreviado. O agente pede uma leitura específica antes de classificar o motivo da pendência. Assim, o sistema não precisa recarregar todos os chamados para recuperar apenas uma descrição.
Ao final, o relatório identifica filtros, período consultado e estado de cobertura. Caso a API falhe na continuação, a supervisora recebe uma lista parcial, claramente identificada. A equipe pode retomar com uma nova consulta compatível com o contrato da origem e reconciliar identificadores, sem supor que um cursor antigo continua válido.
O exercício de aceitação usa uma base sintética em que a pendência está deliberadamente depois da primeira página. O resultado esperado é sua descoberta ou uma declaração explícita de leitura incompleta. Uma resposta definitiva sem essa evidência reprova o teste, mesmo que a redação seja convincente.
Erros comuns
Usar o tamanho da página como prova de fim. Uma resposta menor que o limite solicitado pode continuar tendo próximas páginas. A regra deve vir da documentação do serviço, e não de uma suposição sobre volume.
Cortar o JSON antes de validar. Truncar bytes pode eliminar aspas, campos e indicadores de continuidade. Reduza registros ou campos de maneira estruturada, antes de serializar a resposta entregue ao agente.
Salvar um cursor como se fosse um checkpoint permanente. Marcadores podem ter restrições de validade e de sessão. O checkpoint durável deve registrar também o escopo e uma estratégia de reconciliação compatível com a origem.
Somar páginas sem deduplicar. Sobreposição pode inflar contagens. Use um identificador estável e estabeleça qual versão prevalece quando o mesmo registro aparece novamente.
Omitir ressalvas na última etapa. Faça um teste em que a coleta termine por orçamento. A resposta final deve preservar a limitação. O cuidado com preservação de compromissos no resumo do histórico complementa a revisão dessa passagem entre etapas.
Perguntas frequentes
Aumentar o limite de saída resolve?
Pode ajudar quando o problema está apenas no volume apresentado, mas não substitui paginação nem comprovação de cobertura. Primeiro identifique a camada que cortou o conteúdo. Depois ajuste seu contrato e mantenha um limite que a operação consiga processar.
Posso pedir ao modelo que invente o próximo cursor?
Não. O cursor deve vir da origem. Inventá-lo pode causar erro ou selecionar outra região dos dados. Se o marcador foi perdido, recupere a resposta original ou reinicie a consulta seguindo a estratégia documentada.
Como testar sem usar dados de clientes?
Crie registros sintéticos com identificadores conhecidos e distribua as ocorrências relevantes entre páginas. Inclua página vazia com continuação, registro repetido, erro intermediário e descrição cortada. Compare os identificadores coletados com o conjunto esperado.
Uma amostra pode ser suficiente?
Sim, quando a pergunta pede exemplos ou exploração e a amostra é identificada como tal. Ela não sustenta declarações sobre todos os registros. Registre o critério de seleção para que o leitor entenda o que ficou fora.
Qual indicador acompanhar em produção?
Acompanhe consultas concluídas, consultas parciais por motivo e respostas que indevidamente afirmam cobertura total. Relacione esses eventos à versão do adaptador. Isso permite verificar se uma mudança reduziu o problema observado sem esconder interrupções.
