Um agente de IA pode verificar suas próprias anotações observando a página que acabou de marcar. Com GroupDocs.Annotation.Mcp o LLM em Claude, Cursor ou GitHub Copilot anota um documento, pede ao servidor que renderize a página como PNG com a anotação incluída e julga se o posicionamento está correto. O servidor realiza o trabalho localmente; o prompt é uma frase:

Destaque a cláusula de pagamento na página 2, então mostre‑me a página.

A versão passo a passo com configuração e solução de problemas está na documentação: Como permitir que um agente de IA veja a página do documento que anotou.

Observação: generate_pages_preview atualmente falha para arquivos PDF no Linux, inclusive na imagem Docker; veja os limites Honest antes de construir sobre ele.

Por que um agente que não pode ver sua saída relata sucesso incorretamente?

A maioria das ferramentas de documentos é somente escrita. O agente as chama e diz “concluído” porque a chamada retornou. Para uma anotação, essa afirmação pode ser falsa de modo que nenhuma mensagem de erro aparece: a chamada teve sucesso, mas o destaque fica no parágrafo errado. As coordenadas x e y são coordenadas do documento, e um agente solicitado a destacar “a cláusula de pagamento” precisa adivinhar onde essa cláusula está, a menos que algo o indique.

A diferença está entre “Eu adicionei um destaque” e “O destaque está na cláusula de pagamento”. Apenas a segunda afirmação é útil, e só um olhar na página pode confirmá‑la.

Como um agente renderiza a imagem da página anotada e a verifica?

As ferramentas formam um pequeno loop.

  1. add_annotation grava a anotação e salva contract_annotated.pdf. O arquivo original não é modificado.
  2. generate_pages_preview renderiza as páginas desse arquivo como imagens PNG, com as anotações incorporadas, e as devolve inline. Passe pages como 2, 1-3 ou 1,3,5. Omitindo‑o, você obtém a página 1.
  3. O agente observa a imagem. Se o destaque cobre o texto errado, update_annotation altera sua mensagem ou sua posição e tamanho sem recomeçar.

A pré‑visualização devolve um bloco de texto descrevendo o que foi renderizado, seguido de um bloco de imagem para cada página. Uma chamada renderiza no máximo cinco páginas.

Defina GROUPDOCS_MCP_OUTPUT_PATH para uma pasta diferente da pasta de armazenamento antes de encadear edições em um arquivo produzido. Com o padrão (as saídas ficam na pasta de armazenamento) a segunda gravação falha com being used by another process; com uma pasta de saída separada add_reply, update_annotation e remove_annotations no arquivo produzido funcionam todas. Na imagem Docker, passe -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output. A sessão abaixo assume essa configuração, de modo que o arquivo produzido fica em output/.

O que o agente precisa para que isso funcione?

  • Um cliente que mostre conteúdo de imagem. Claude Desktop faz isso. Um cliente de terminal pode apenas relatar que uma imagem foi retornada. A ferramenta se comporta da mesma forma em ambos os casos; as imagens podem simplesmente não ser exibidas.
  • Um modelo capaz de visão. As imagens ajudam apenas um modelo que aceita entrada de imagem.
  • Um intervalo de páginas pequeno. Renderizar é a chamada mais cara que este servidor faz. Solicite apenas a página que você precisa, não um arquivo de cinquenta páginas.

Que outros usos a pré‑visualização tem?

  • Localizar antes de anotar. Renderize primeiro, deixe o modelo ler a página e, então, coloque a anotação com as coordenadas que ele derivou em vez de adivinhar.
  • Verificar uma mesclagem. Após import_annotations em um rascunho reformatado, uma pré‑visualização mostra se as notas importadas ainda estão onde deveriam estar.
  • Mostrar ao revisor o resultado no chat sem abrir o arquivo.
  • Detectar a marca de avaliação. No modo de avaliação, uma marca de avaliação de teste é estampada em cada página, de modo que ela fica visível na imagem renderizada.

Sessão de exemplo (abreviada)

Esta é uma ilustração construída a partir do comportamento documentado das ferramentas, não uma captura de tela. Assume‑se uma plataforma onde o renderizador de pré‑visualização funciona para arquivos PDF, como Windows com dnx.

You:   Highlight the payment clause on page 2 of contract.pdf, then show me the page.

Agent: [calls add_annotation: type=highlight, page=2, x=100, y=250,
        text="Payment clause"]
       Added highlight annotation to contract.pdf on page 2.
       [calls generate_pages_preview on output/contract_annotated.pdf, pages="2"]
       (image: page 2, rendered with the highlight)
       The highlight sits on the "Delivery" paragraph, one block above the
       payment clause. Moving it down.
       [calls get_annotations, then update_annotation: y=330]
       Updated annotation 1 in output/contract_annotated.pdf.
       (The agent passes the saved file name from each result to the next call.)

Onde a renderização ocorre e o que sai da máquina?

O mecanismo produz o PNG na sua máquina. A imagem então viaja para o provedor do seu modelo como qualquer outro conteúdo de mensagem, de modo que, com um modelo hospedado na nuvem, uma pré‑visualização envia uma foto daquela página. Para documentos sensíveis, use um modelo hospedado localmente.

Limites Honest

  • Pré‑visualização no Linux. generate_pages_preview atualmente falha para arquivos PDF no Linux, inclusive na imagem Docker (TypeInitializationException para Gdip: System.Drawing.Common não é suportado em plataformas não‑Windows); documentos Word e outros do Office são renderizados, e no Windows com dnx todos os formatos são renderizados. As outras dez ferramentas não são afetadas.
  • Modo de avaliação. Uma marca de avaliação é estampada no topo de cada página do arquivo anotado e das pré‑visualizações. Verifique get_license_status antes de confiar na saída.
  • Posicionamento aproximado permanece aproximado. Uma pré‑visualização permite que o modelo perceba uma anotação fora do lugar; ela não transforma coordenadas adivinhadas em coordenadas exatas.
  • Um modelo somente‑texto não pode verificar. Ele ainda recebe o bloco de texto, mas não pode dizer como a página se parece.

Perguntas Frequentes

Um IA pode verificar onde um comentário foi colocado na página? Sim, se o modelo aceita imagens. O agente renderiza a página anotada com generate_pages_preview e examina a imagem, então ajusta a anotação com update_annotation se necessário.

Como faço para pré‑visualizar uma página PDF anotada para o agente? Peça a página por número, por exemplo “Renderize as páginas 1‑3 do contrato anotado para que eu possa verificar os comentários”. O agente passa pages como 1-3 e os PNGs são devolvidos inline.

Por que a pré‑visualização falha no meu contêiner Docker? Para arquivos PDF a ferramenta falha no Linux, inclusive na imagem Docker, com um erro de inicialização de tipo Gdip. Documentos Word e outros do Office são renderizados, e no Windows com dnx todos os formatos são renderizados.

Aprofunde