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:

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

הערה: generate_pages_preview נכשל כרגע בקבצי PDF על לינוקס, כולל בתמונת Docker; ראו את המגבלות הכנות לפני השימוש.

למה סוכן שאינו רואה את הפלט שלו מדווח על הצלחה באופן שגוי?

רוב כלי המסמכים הם רק כתיבה. הסוכן קורא להם ומצהיר “הסתיים” מכיוון שהקריאה חזרה. עבור הערה, הצהרה זו יכולה להיות שגויה באופן שבו לא מופיעה הודעת שגיאה: הקריאה הצליחה, וההדגשה נמצאת בפסקה הלא נכונה. הקואורדינטות x ו‑y הן קואורדינטות של המסמך, וסוכן שנדרש להדגיש את “סעיף התשלום” צריך לנחש היכן נמצא הסעיף אלא אם כן משהו מודיע לו זאת.

ההבדל הוא בין “הוספתי הדגשה” ל‑“ההדגשה נמצאת על סעיף התשלום”. רק ההצהרה השנייה היא שימושית, ורק הסתכלות על העמוד יכולה לתמוך בכך.

איך סוכן מייצר תמונת עמוד עם הערה ובודק אותה?

הכלים יוצרים לולאה קצרה.

  1. add_annotation כותב את ההערה ושומר את contract_annotated.pdf. הקובץ המקורי אינו משתנה.
  2. generate_pages_preview מייצר עמודים של הקובץ הזה כתמונות PNG, עם ההערות משולבות, ומחזיר אותם באופן משולב. העבירו 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 במחשב שלך. לאחר מכן התמונה נשלחת לספק המודל שלך כמו כל תוכן הודעה אחר, ולכן עם מודל שמאוחסן בענן תצוגה מקדימה שולחת תמונה של העמוד. עבור מסמכים רגישים, השתמשו במודל שמאוחסן מקומית.

מגבלות כנות

  • תצוגה מקדימה בלינוקס. generate_pages_preview נכשל כרגע עם קבצי PDF בלינוקס, כולל בתמונת Docker (TypeInitializationException עבור Gdip: System.Drawing.Common אינו נתמך בפלטפורמות שאינן Windows); קבצי Word וקבצי Office אחרים מוצגים, וב‑Windows עם dnx כל פורמט מוצג. העשר כלים האחרים אינם מושפעים.
  • מצב הערכה. תג נסיון מודפס בחלק העליון של כל עמוד של הקובץ המוערך ושל התצוגות המקדימות. בדקו get_license_status לפני שאתם סומכים על הפלט.
  • מיקום משוער נשאר משוער. תצוגה מקדימה מאפשרת למודל לשים לב להערה ממוקמת לא נכון; היא אינה ממירה קואורדינטות משוערות למדויקות.
  • מודל טקסט בלבד אינו יכול לבדוק. הוא עדיין מקבל את בלוק הטקסט, אך אינו יכול לומר לך איך נראה העמוד.

שאלות נפוצות

האם AI יכול לבדוק היכן נחתה הערה על העמוד? כן, אם המודל מקבל תמונות. הסוכן מייצר את העמוד המוערך עם generate_pages_preview ובוחן את התמונה, ואז מתאם את ההערה עם update_annotation במידת הצורך.

איך אני מציג תצוגה מקדימה של עמוד PDF מוערך עבור הסוכן? בקשו את העמוד לפי מספר, לדוגמה “Render pages 1-3 of the annotated contract so I can check the comments”. הסוכן מעביר pages כ‑1-3 והקבצים PNG חוזרים משולבים.

למה התצוגה המקדימה נכשלת במכולת Docker שלי? עבור קבצי PDF הכלי נכשל בלינוקס, כולל בתמונת Docker, עם שגיאת אתחול מסוג Gdip. קבצי Word וקבצי Office אחרים מוצגים, וב‑Windows עם dnx כל פורמט מוצג.

להעמיק יותר