Un agente IA può verificare le proprie annotazioni osservando la pagina che ha appena contrassegnato. Con GroupDocs.Annotation.Mcp il LLM in Claude, Cursor o GitHub Copilot annota un documento, chiede al server di renderizzare la pagina come PNG con l’annotazione inclusa e giudica se il posizionamento è corretto. Il server esegue il lavoro localmente; il prompt è una sola frase:

Evidenzia la clausola di pagamento a pagina 2, poi mostrami la pagina.

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: Come far vedere a un agente IA la pagina del documento che ha annotato.

Nota: generate_pages_preview attualmente fallisce per file PDF su Linux, inclusa l’immagine Docker; consulta i Limiti onesti prima di costruire su di esso.

Perché un agente che non può vedere il proprio output segnala erroneamente il successo?

La maggior parte degli strumenti per documenti è a sola scrittura. L’agente li chiama e dice “fatto” perché la chiamata è tornata. Per un’annotazione quella affermazione può essere falsa in un modo in cui non appare alcun messaggio di errore: la chiamata è riuscita, ma l’evidenziazione si trova nel paragrafo sbagliato. Le coordinate x e y sono coordinate del documento, e un agente a cui viene chiesto di evidenziare “la clausola di pagamento” deve indovinare dove si trovi quella clausola a meno che qualcosa non glielo dica.

La differenza è tra “ho aggiunto un’evidenziazione” e “l’evidenziazione è sulla clausola di pagamento”. Solo la seconda affermazione è utile, e solo uno sguardo alla pagina può supportarla.

Come rende un agente un’immagine della pagina annotata e la controlla?

Gli strumenti formano un breve ciclo.

  1. add_annotation scrive l’annotazione e salva contract_annotated.pdf. Il file originale non viene modificato.
  2. generate_pages_preview renderizza le pagine di quel file come immagini PNG, con le annotazioni incorporate, e le restituisce inline. Passa pages come 2, 1-3 o 1,3,5. Omettendolo ottieni la pagina 1.
  3. L’agente guarda l’immagine. Se l’evidenziazione copre il testo sbagliato, update_annotation ne modifica il messaggio o la posizione e le dimensioni senza ricominciare da capo.

L’anteprima restituisce un blocco di testo che descrive ciò che è stato renderizzato, seguito da un blocco immagine per ogni pagina. Una chiamata renderizza al massimo cinque pagine.

Imposta GROUPDOCS_MCP_OUTPUT_PATH su una cartella diversa da quella di storage prima di concatenare modifiche su un file prodotto. Con l’impostazione predefinita (gli output atterrano nella cartella di storage) la seconda scrittura fallisce con being used by another process; con una cartella di output separata add_reply, update_annotation e remove_annotations sul file prodotto hanno tutti successo. Con l’immagine Docker, passa -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output. La sessione sotto assume tale impostazione, così il file prodotto si trova sotto output/.

Di cosa ha bisogno l’agente per far funzionare tutto questo?

  • Un client che mostri contenuti immagine. Claude Desktop lo fa. Un client terminale può solo segnalare che è tornata un’immagine. Lo strumento si comporta allo stesso modo in entrambi i casi; le immagini potrebbero semplicemente non essere visualizzate.
  • Un modello in grado di elaborare la visione. Le immagini sono utili solo a un modello che accetta input immagine.
  • Un intervallo di pagine ridotto. Il rendering è la chiamata più costosa che questo server effettua. Richiedi la pagina di cui hai bisogno, non un file di cinquanta pagine.

Quali altri usi ha l’anteprima?

  • Localizzare prima di annotare. Renderizza prima, lascia che il modello legga la pagina, poi posiziona l’annotazione con le coordinate che ha derivato anziché indovinate.
  • Verificare un merge. Dopo import_annotations su una bozza riformattata, un’anteprima mostra se le note importate sono ancora dove dovrebbero essere.
  • Mostrare al revisore il risultato nella chat senza aprire il file.
  • Individuare il badge di valutazione. In modalità valutazione un badge di prova è stampato su ogni pagina, quindi è visibile nell’immagine renderizzata.

Sessione di esempio (abbreviata)

Nota: questo è un esempio illustrativo basato sul comportamento documentato degli strumenti, non uno screenshot catturato. Assume una piattaforma in cui il renderer di anteprima funziona per file PDF, ad esempio Windows con 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.)

Dove avviene il rendering e cosa lascia la macchina?

Il motore produce il PNG sulla tua macchina. L’immagine poi viaggia verso il provider del modello come qualsiasi altro contenuto di messaggio, quindi con un modello ospitato nel cloud un’anteprima invia una foto di quella pagina. Per documenti sensibili, usa un modello ospitato localmente.

Limiti onesti

  • Anteprima su Linux. generate_pages_preview attualmente fallisce per file PDF su Linux, inclusa l’immagine Docker (TypeInitializationException per Gdip: System.Drawing.Common non è supportato su piattaforme non‑Windows); i documenti Word e altri Office vengono renderizzati, e su Windows con dnx ogni formato viene renderizzato. Gli altri dieci strumenti non sono interessati.
  • Modalità valutazione. Un badge di prova è stampato in cima a ogni pagina del file annotato e delle anteprime. Controlla get_license_status prima di fare affidamento sull’output.
  • Il posizionamento approssimativo rimane approssimativo. Un’anteprima permette al modello di notare un’annotazione fuori posto; non trasforma coordinate indovinate in coordinate esatte.
  • Un modello solo testo non può verificare. Riceve comunque il blocco di testo, ma non può dirti come appare la pagina.

Domande frequenti

Un’IA può verificare dove è atterrato un commento sulla pagina? Sì, se il modello accetta immagini. L’agente renderizza la pagina annotata con generate_pages_preview ed esamina l’immagine, poi regola l’annotazione con update_annotation se necessario.

Come faccio a vedere in anteprima una pagina PDF annotata per l’agente? Chiedi la pagina per numero, ad esempio “Renderizza le pagine 1‑3 del contratto annotato così posso controllare i commenti”. L’agente passa pages come 1-3 e i PNG tornano inline.

Perché l’anteprima fallisce nel mio contenitore Docker? Per i file PDF lo strumento fallisce su Linux, inclusa l’immagine Docker, con un errore di inizializzazione del tipo Gdip. I documenti Word e altri Office vengono renderizzati, e su Windows con dnx ogni formato viene renderizzato.

Approfondisci