PDF 도구

pdf는 하나 이상의 PDF 문서를 분석하고 텍스트를 반환합니다.

주요 동작:

  • Anthropic 및 Google 모델 프로바이더를 위한 네이티브 프로바이더 모드.
  • 다른 프로바이더를 위한 추출 폴백 모드 (텍스트를 먼저 추출한 후 필요 시 페이지 이미지 사용).
  • 단일(pdf) 또는 다중(pdfs) 입력 지원, 호출당 최대 10개 PDF.

사용 가능 조건

에이전트에 대해 PDF 지원 모델 설정을 해석할 수 있을 때만 도구가 등록됩니다:

  1. agents.defaults.pdfModel
  2. agents.defaults.imageModel로 폴백
  3. 사용 가능한 인증을 기반으로 한 최선 노력 프로바이더 기본값으로 폴백

사용 가능한 모델이 해석되지 않으면 pdf 도구는 노출되지 않습니다.

입력 참조

  • pdf (string): 하나의 PDF 경로 또는 URL
  • pdfs (string[]): 여러 PDF 경로 또는 URL, 최대 총 10개
  • prompt (string): 분석 프롬프트, 기본값 Analyze this PDF document.
  • pages (string): 1-5 또는 1,3,7-9와 같은 페이지 필터
  • model (string): 선택적 모델 재정의 (provider/model)
  • maxBytesMb (number): PDF당 크기 제한 (MB)

입력 참고:

  • pdf와 pdfs는 로딩 전에 병합 및 중복 제거됩니다.
  • PDF 입력이 제공되지 않으면 도구가 오류를 반환합니다.
  • pages는 1 기반 페이지 번호로 파싱되며, 중복 제거, 정렬 후 설정된 최대 페이지 수로 제한됩니다.
  • maxBytesMb는 agents.defaults.pdfMaxBytesMb 또는 10이 기본값입니다.

지원되는 PDF 참조 형식

  • 로컬 파일 경로 (~ 확장 포함)
  • file:// URL
  • http:// 및 https:// URL

참조 참고:

  • 다른 URI 스킴(예: ftp://)은 unsupported_pdf_reference로 거부됩니다.
  • 샌드박스 모드에서는 원격 http(s) URL이 거부됩니다.
  • 워크스페이스 전용 파일 정책이 활성화된 경우, 허용된 루트 외부의 로컬 파일 경로가 거부됩니다.

실행 모드

네이티브 프로바이더 모드

anthropic과 google 프로바이더에 사용됩니다. 원시 PDF 바이트를 프로바이더 API에 직접 전송합니다.

네이티브 모드 제한:

  • pages는 지원되지 않습니다. 설정하면 오류를 반환합니다.

추출 폴백 모드

네이티브가 아닌 프로바이더에 사용됩니다.

흐름:

  1. 선택된 페이지에서 텍스트를 추출합니다(최대 agents.defaults.pdfMaxPages, 기본값 20).
  2. 추출된 텍스트 길이가 200자 미만이면 선택된 페이지를 PNG 이미지로 렌더링하여 포함합니다.
  3. 추출된 콘텐츠와 프롬프트를 선택된 모델에 전송합니다.

폴백 세부 사항:

  • 페이지 이미지 추출은 4,000,000 픽셀 예산을 사용합니다.
  • 대상 모델이 이미지 입력을 지원하지 않고 추출 가능한 텍스트가 없으면 오류가 발생합니다.
  • 추출 폴백에는 pdfjs-dist(이미지 렌더링을 위한 @napi-rs/canvas)가 필요합니다.

설정

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}

전체 필드 상세 정보는 설정 참조를 참고하세요.

출력 상세

도구는 content[0].text에 텍스트를, details에 구조화된 메타데이터를 반환합니다.

일반적인 details 필드:

  • model: 해석된 모델 참조 (provider/model)
  • native: 네이티브 프로바이더 모드는 true, 폴백은 false
  • attempts: 성공 전 실패한 폴백 시도 횟수

경로 필드:

  • 단일 PDF 입력: details.pdf
  • 다중 PDF 입력: details.pdfs[] 내 pdf 항목
  • 샌드박스 경로 재작성 메타데이터 (해당 시): rewrittenFrom

오류 동작

  • PDF 입력 누락: pdf required: provide a path or URL to a PDF document 오류 발생
  • PDF 수 초과: details.error = "too_many_pdfs"로 구조화된 오류 반환
  • 지원되지 않는 참조 스킴: details.error = "unsupported_pdf_reference" 반환
  • pages가 있는 네이티브 모드: pages is not supported with native PDF providers 오류 발생

예시

단일 PDF:

{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}

다중 PDF:

{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}

페이지 필터링된 폴백 모델:

{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5-mini",
  "prompt": "Extract only customer-impacting incidents"
}
arrow_back
이전
Diffs
다음
Elevated
arrow_forward