AI‑агент може перевіряти власні анотації, дивлячись на сторінку, яку він щойно позначив. За допомогою GroupDocs.Annotation.Mcp LLM у Claude, Cursor або GitHub Copilot анотує документ, просить сервер відрендерити сторінку у PNG з включеною анотацією та оцінює, чи правильне розташування. Сервер виконує роботу локально; запит — одне речення:

Highlight the payment clause on page 2, then show me the page.

Крок‑за‑кроком версія з конфігурацією та усуненням проблем у документації: How to let an AI agent see the document page it annotated.

Note: generate_pages_preview наразі не працює з PDF‑файлами на Linux, включаючи Docker‑образ; дивіться Чесні обмеження, перш ніж будувати на цьому.

Чому агент, який не може бачити свій вихід, помилково повідомляє про успіх?

Більшість інструментів для документів є лише записними. Агент викликає їх і каже «готово», бо виклик повернувся. Для анотації це твердження може бути хибним без жодного повідомлення про помилку: виклик успішний, а підсвічування знаходиться в неправильному абзаці. Координати x і y — це координати документа, і агенту, якому сказано підсвітити «пункт про оплату», доводиться вгадувати, де саме цей пункт, якщо йому нічого не підказати.

Різниця між «я додав підсвічування» і «підсвічування знаходиться в пункті про оплату». Лише друге твердження корисне, і лише перегляд сторінки може його підтвердити.

Як агент рендерить зображення анотованої сторінки та перевіряє його?

Інструменти утворюють короткий цикл.

  1. add_annotation записує анотацію і зберігає contract_annotated.pdf. Оригінальний файл не змінюється.
  2. generate_pages_preview рендерить сторінки цього файлу у PNG‑зображення, з вбудованими анотаціями, і повертає їх inline. Передайте pages як 2, 1-3 або 1,3,5. Якщо не вказати, отримаєте сторінку 1.
  3. Агент дивиться на зображення. Якщо підсвічування охоплює неправильний текст, update_annotation змінює його повідомлення або позицію й розмір без повторного створення.

Прев’ю повертає один текстовий блок, що описує, що було відрендерено, а потім один блок зображення для кожної сторінки. Один виклик рендерить максимум п’ять сторінок.

Встановіть GROUPDOCS_MCP_OUTPUT_PATH у папку, відмінну від папки сховища, перед ланцюжком правок над створеним файлом. За замовчуванням (виходи потрапляють у папку сховища) друге записування завершується помилкою being used by another process; при окремій папці виходів add_reply, update_annotation і remove_annotations над створеним файлом успішно виконуються. У Docker‑образі передайте -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output. Сесія нижче передбачає цей параметр, тому створений файл розташовується у output/.

Що агенту потрібно, щоб це працювало?

  • Клієнт, який показує вміст зображення. Claude Desktop це робить. Термінальний клієнт може лише повідомляти, що зображення повернулося. Інструмент поводиться однаково; зображення можуть просто не відображатися.
  • Модель, здатна працювати з візуальними даними. Зображення корисні лише для моделі, яка приймає вхід у вигляді зображень.
  • Невеликий діапазон сторінок. Рендеринг — найдорогоцінніший виклик цього сервера. Запитуйте лише потрібну сторінку, а не файл на п’ятдесят сторінок.

Які інші використання має прев’ю?

  • Знаходити перед анотуванням. Спочатку відрендерити, дозволити моделі прочитати сторінку, а потім розмістити анотацію з координатами, які вона отримала, а не вгадала.
  • Перевірити злиття. Після import_annotations у переформатований чернетковий документ прев’ю показує, чи залишилися імпортовані нотатки на потрібних місцях.
  • Показати рецензенту результат у чаті без відкриття файлу.
  • Помітити бейдж оцінки. У режимі оцінки пробний бейдж наноситься на кожну сторінку, тому його видно на відрендереному зображенні.

Приклад сесії (скорочений)

Це ілюстрація, побудована на задокументованій поведінці інструментів, а не захоплений скріншот. Припускає платформу, де рендерер прев’ю працює з PDF‑файлами, наприклад Windows з 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.)

Де виконується рендеринг і що залишає машину?

Двигун створює PNG‑файл на вашій машині. Потім зображення передається вашому постачальнику моделей так само, як будь‑який інший вміст повідомлення, тому при використанні хмарної моделі прев’ю надсилає картинку сторінки. Для конфіденційних документів використовуйте локально розгорнуту модель.

Чесні обмеження

  • Прев’ю на Linux. generate_pages_preview наразі не працює з PDF‑файлами на Linux, включаючи Docker‑образ (TypeInitializationException для Gdip: System.Drawing.Common не підтримується на не‑Windows платформах); Word та інші Office‑документи рендеряться, а на Windows з dnx рендериться будь‑який формат. Інші десять інструментів не постраждали.
  • Режим оцінки. Пробний бейдж наноситься у верхній частині кожної сторінки анотованого файлу та прев’ю. Перевірте get_license_status перед тим, як покладатися на результат.
  • Приблизне розташування залишається приблизним. Прев’ю дозволяє моделі помітити помилково розташовану анотацію; воно не перетворює вгадані координати у точні.
  • Текстова модель не може перевіряти. Вона все ще отримує текстовий блок, але не може сказати, як виглядає сторінка.

Часті питання

Чи може ШІ перевірити, де коментар розташувався на сторінці? Так, якщо модель приймає зображення. Агент рендерить анотовану сторінку за допомогою generate_pages_preview і аналізує картинку, потім, за потреби, коригує анотацію за допомогою update_annotation.

Як переглянути анотовану PDF‑сторінку для агента? Запитайте сторінку за номером, наприклад «Відрендерити сторінки 1‑3 анотованого контракту, щоб я міг перевірити коментарі». Агент передає pages як 1-3, і PNG‑файли повертаються вбудовано.

Чому прев’ю не працює в моєму Docker‑контейнері? Для PDF‑файлів інструмент не працює на Linux, включаючи Docker‑образ, з помилкою ініціалізації типу Gdip. Word та інші Office‑документи рендеряться, а на Windows з dnx рендериться будь‑який формат.

Поглиблене вивчення