An AI agent can verify its own annotations by looking at the page it just marked up. With GroupDocs.Annotation.Mcp the LLM in Claude, Cursor or GitHub Copilot annotates a document, asks the server to render the page as a PNG with the annotation included, and judges whether the placement is right. The server does the work locally; the prompt is one sentence:

Podświetl klauzulę płatności na stronie 2, a następnie pokaż mi tę stronę.

The step-by-step version with config and troubleshooting is in the documentation: How to let an AI agent see the document page it annotated.

Note: generate_pages_preview currently fails for PDF files on Linux, including the Docker image; see Honest limits before you build on it.

Dlaczego agent, który nie może zobaczyć swojego wyniku, błędnie zgłasza sukces?

Większość narzędzi do dokumentów jest tylko do zapisu. Agent wywołuje je i mówi „gotowe”, ponieważ wywołanie zwróciło wynik. W przypadku adnotacji to stwierdzenie może być fałszywe w sposób, w którym nie pojawia się żaden komunikat o błędzie: wywołanie zakończyło się sukcesem, a podświetlenie znajduje się w niewłaściwym paragrafie. Współrzędne x i y są współrzędnymi dokumentu, a agent poproszony o podświetlenie „klauzuli płatności” musi zgadnąć, gdzie ta klauzula się znajduje, chyba że coś mu to wskaże.

Różnica polega na tym, czy mówimy „dodałem podświetlenie”, czy „podświetlenie znajduje się przy klauzuli płatności”. Tylko drugie stwierdzenie jest użyteczne i tylko spojrzenie na stronę może je potwierdzić.

Jak agent renderuje obraz strony z adnotacją i sprawdza go?

Narzędzia tworzą krótką pętlę.

  1. add_annotation zapisuje adnotację i zapisuje contract_annotated.pdf. Oryginalny plik nie jest modyfikowany.
  2. generate_pages_preview renderuje strony tego pliku jako obrazy PNG, z wbudowanymi adnotacjami, i zwraca je w treści. Przekaż pages jako 2, 1-3 lub 1,3,5. Jeśli pominiesz, otrzymasz stronę 1.
  3. Agent patrzy na obraz. Jeśli podświetlenie obejmuje niewłaściwy tekst, update_annotation zmienia jego treść lub pozycję i rozmiar bez rozpoczynania od nowa.

Podgląd zwraca jeden blok tekstowy opisujący, co zostało wyrenderowane, a następnie jeden blok obrazu dla każdej strony. Jedno wywołanie renderuje maksymalnie pięć stron.

Ustaw GROUPDOCS_MCP_OUTPUT_PATH na folder inny niż folder przechowywania przed łączeniem edycji na wygenerowanym pliku. Przy domyślnym ustawieniu (wyniki trafiają do folderu przechowywania) drugie zapisanie kończy się błędem being used by another process; przy osobnym folderze wyjściowym add_reply, update_annotation i remove_annotations na wygenerowanym pliku zakończą się sukcesem. W obrazie Docker przekaż -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output. Sesja poniżej zakłada to ustawienie, więc wygenerowany plik znajduje się w output/.

Czego agent potrzebuje, aby to działało?

  • Klient wyświetlający zawartość obrazu. Claude Desktop to robi. Klient terminalowy może jedynie zgłosić, że obraz został zwrócony. Narzędzie zachowuje się tak samo w obu przypadkach; obrazy mogą po prostu nie być wyświetlane.
  • Model zdolny do przetwarzania wizualnego. Obrazy pomagają tylko modelowi, który akceptuje wejście obrazowe.
  • Mały zakres stron. Renderowanie jest najdroższym wywołaniem, które wykonuje ten serwer. Poproś o stronę, której potrzebujesz, a nie o pięćdziesięciostronicowy plik.

Jakie inne zastosowania ma podgląd?

  • Zlokalizuj przed adnotacją. Najpierw renderuj, pozwól modelowi przeczytać stronę, a następnie umieść adnotację z wyprowadzonymi współrzędnymi zamiast zgadywanych.
  • Sprawdź scalanie. Po import_annotations na przetworzonym szkicu podgląd pokazuje, czy zaimportowane notatki nadal znajdują się tam, gdzie powinny.
  • Pokaż recenzentowi wynik w czacie bez otwierania pliku.
  • Wykryj odznakę ewaluacji. W trybie oceny odznaka trial jest nanoszona na każdą stronę, więc jest widoczna w wyrenderowanym obrazie.

Przykładowa sesja (skrótowo)

To ilustracja zbudowana na podstawie udokumentowanego zachowania narzędzi, a nie przechwycony zrzut ekranu. Zakłada platformę, na której renderer podglądu działa dla plików PDF, np. Windows z 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.)

Gdzie odbywa się renderowanie i co opuszcza maszynę?

Silnik generuje PNG na Twoim komputerze. Obraz następnie trafia do dostawcy modelu jak każda inna treść wiadomości, więc przy modelu hostowanym w chmurze podgląd wysyła zdjęcie tej strony. W przypadku wrażliwych dokumentów użyj modelu hostowanego lokalnie.

Ograniczenia Honest

  • Podgląd na Linuxie. generate_pages_preview obecnie nie działa dla plików PDF na Linuxie, w tym obrazu Docker (TypeInitializationException dla Gdip: System.Drawing.Common nie jest obsługiwany na platformach nie‑Windows); dokumenty Word i inne dokumenty Office są renderowane, a na Windows z dnx każdy format jest renderowany. Pozostałe dziesięć narzędzi nie jest dotkniętych.
  • Tryb ewaluacji. Odznaka trial jest nanoszona na górze każdej strony adnotowanego pliku oraz podglądów. Sprawdź get_license_status przed poleganiem na wyniku.
  • Przybliżone położenie pozostaje przybliżone. Podgląd pozwala modelowi zauważyć nieprawidłowo umieszczoną adnotację; nie zamienia zgadywanych współrzędnych na dokładne.
  • Model tylko tekstowy nie może sprawdzić. Nadal otrzymuje blok tekstowy, ale nie może powiedzieć, jak wygląda strona.

FAQ

Czy AI może sprawdzić, gdzie komentarz znalazł się na stronie? Tak, jeśli model akceptuje obrazy. Agent renderuje stronę z adnotacją przy użyciu generate_pages_preview i analizuje obraz, a w razie potrzeby dostosowuje adnotację przy pomocy update_annotation.

Jak podglądam stronę PDF z adnotacją dla agenta? Poproś o stronę według numeru, np. „Renderuj strony 1-3 adnotowanego kontraktu, abym mógł sprawdzić komentarze”. Agent przekazuje pages jako 1-3, a PNG‑y zwracane są w treści.

Dlaczego podgląd nie działa w moim kontenerze Docker? Dla plików PDF narzędzie nie działa na Linuxie, w tym w obrazie Docker, z błędem inicjalizacji typu Gdip. Dokumenty Word i inne dokumenty Office są renderowane, a na Windows z dnx każdy format jest renderowany.

Zagłęb się