AI 에이전트는 방금 주석을 단 페이지를 확인함으로써 자신의 주석을 검증할 수 있습니다. GroupDocs.Annotation.Mcp를 사용하면 Claude, Cursor 또는 GitHub Copilot의 LLM이 문서에 주석을 달고, 서버에 주석이 포함된 페이지를 PNG로 렌더링하도록 요청한 뒤, 배치가 올바른지 판단합니다. 서버는 로컬에서 작업을 수행합니다; 프롬프트는 한 문장입니다:

페이지 2의 결제 조항을 강조 표시하고, 그 페이지를 보여 주세요.

구성 및 문제 해결이 포함된 단계별 버전은 문서에 있습니다: 문서 페이지를 에이전트가 볼 수 있게 하는 방법.

※ generate_pages_preview는 현재 Linux(도커 이미지 포함)에서 PDF 파일에 대해 실패합니다. 사용하기 전에 Honest limits를 확인하세요.

출력물을 볼 수 없는 에이전트가 성공을 잘못 보고하는 이유는?

대부분의 문서 도구는 쓰기 전용입니다. 에이전트는 도구를 호출하고 호출이 반환되었기 때문에 “완료”라고 말합니다. 주석의 경우, 오류 메시지가 표시되지 않는 방식으로 진술이 거짓일 수 있습니다: 호출은 성공했지만 강조 표시가 잘못된 단락에 놓여 있습니다. 좌표 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가 모두 성공합니다. 도커 이미지에서는 -e GROUPDOCS_MCP_OUTPUT_PATH=/data/output을 전달하십시오. 아래 세션은 이 설정을 전제로 하며, 생성된 파일은 output/ 아래에 위치합니다.

이 기능이 작동하려면 에이전트에 무엇이 필요할까?

  • 이미지 내용을 표시할 수 있는 클라이언트. Claude Desktop이 해당 기능을 제공합니다. 터미널 클라이언트는 이미지가 반환되었다는 사실만 보고할 수 있습니다. 도구는 두 경우 모두 동일하게 동작하지만, 이미지가 표시되지 않을 수 있습니다.
  • 시각 인식이 가능한 모델. 이미지는 이미지 입력을 받는 모델에게만 도움이 됩니다.
  • 작은 페이지 범위. 렌더링은 서버가 수행하는 가장 비용이 많이 드는 호출입니다. 필요한 페이지만 요청하고, 50페이지 파일 전체를 요청하지 마세요.

프리뷰의 다른 활용 사례는?

  • 주석을 달기 전에 위치 파악. 먼저 렌더링하고 모델이 페이지를 읽게 한 뒤, 추측이 아닌 도출된 좌표로 주석을 배치합니다.
  • 병합 확인. 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를 사용자의 머신에서 생성합니다. 그 이미지가 모델 제공자에게 다른 메시지 내용과 마찬가지로 전송되므로, 클라우드 기반 모델을 사용할 경우 프리뷰는 해당 페이지의 사진을 전송합니다. 민감한 문서의 경우 로컬에 호스팅된 모델을 사용하십시오.

Honest limits

  • Linux에서의 프리뷰. generate_pages_preview는 현재 Linux(도커 이미지 포함)에서 PDF 파일에 대해 실패합니다(Gdip에 대한 TypeInitializationException: System.Drawing.Common이 비 Windows 플랫폼을 지원하지 않음). Word 및 기타 Office 문서는 렌더링되며, Windows + dnx에서는 모든 형식이 렌더링됩니다. 다른 열 개 도구는 영향을 받지 않습니다.
  • 평가 모드. 시험 배지가 주석이 달린 파일 및 프리뷰의 모든 페이지 상단에 찍히므로, 출력에 의존하기 전에 get_license_status를 확인하십시오.
  • 대략적인 위치는 대략적으로 유지됩니다. 프리뷰는 모델이 잘못 배치된 주석을 인식하도록 도와주지만, 추측 좌표를 정확한 좌표로 바꾸지는 않습니다.
  • 텍스트 전용 모델은 확인할 수 없습니다. 텍스트 블록은 받지만 페이지가 어떻게 보이는지는 알 수 없습니다.

FAQ

AI가 주석이 페이지 어디에 배치됐는지 확인할 수 있나요?
예, 모델이 이미지를 받아들일 경우 가능합니다. 에이전트는 generate_pages_preview로 주석이 달린 페이지를 렌더링하고 이미지를 검사한 뒤, 필요하면 update_annotation으로 주석을 조정합니다.

에이전트를 위해 주석이 달린 PDF 페이지를 어떻게 프리뷰하나요?
페이지 번호를 지정해 요청합니다. 예: “주석이 달린 계약서의 1‑3 페이지를 렌더링해서 댓글을 확인하고 싶어요.” 에이전트는 pages를 1-3으로 전달하고 PNG가 인라인으로 반환됩니다.

Docker 컨테이너에서 프리뷰가 왜 실패하나요?
PDF 파일의 경우 도구가 Linux(도커 이미지 포함)에서 Gdip 초기화 오류로 실패합니다. Word 및 기타 Office 문서는 렌더링되며, Windows + dnx에서는 모든 형식이 정상적으로 렌더링됩니다.

더 깊이 파고들기