NextPDF Connect를 통한 휴먼 인 더 루프 파일 출력

한눈에 보기

휴먼 인 더 루프(HITL) 확인 게이트는 의도하지 않은 파일 시스템 쓰기를 방지합니다. output_pdf가 file_path와 함께 호출되면, 게이트는 호출을 가로채고 파일을 쓰는 대신 일회용 챌린지를 반환합니다. 사람이 승인하면 에이전트가 토큰을 포함해 다시 호출하며, 그때서야 파일이 쓰입니다. Base64 출력(file_path 없음)은 게이트를 거치지 않습니다.

설치

composer require nextpdf/server

트랜스포트를 바인딩합니다. 기본적으로 output_pdf는 Approval Required 위험 수준입니다.

개념 개요

게이트는 구성 또는 호출자 신원 오버라이드가 적용된 뒤 남는 유효 위험 수준을 평가합니다. Approval Required 도구의 경우:

base64 모드 — output_pdf에 file_path가 없으면 Review로 강등되어 확인 없이 허용됩니다. 파일 시스템 부작용은 발생하지 않습니다.
file 모드 — output_pdf에 file_path가 있으면 Approval Required로 유지됩니다. 게이트는 도구 이름에 바인딩된 일회용 토큰을 저장하고 챌린지를 반환합니다. 대상 파일이 이미 존재하면, 챌린지 텍스트에 덮어쓰기 경고가 포함됩니다. 토큰은 정해진 시간 창이 지나면 만료됩니다.

모든 트랜스포트에서 게이트 결과는 정상 응답으로 처리됩니다. 대기 중인 승인은 워크플로의 일시 정지이지 트랜스포트 실패가 아닙니다(PSR-18 §3; PSR-18 §p2).

API 표면

도구	역할	위험 등급
`create_pdf`	세션 열기	Safe
`set_font`, `add_text`	콘텐츠 구성	Caution
`output_pdf` (base64)	인라인으로 반환; 게이트 없음	Review
`output_pdf` (file)	디스크에 쓰기; 게이트됨	Approval Required

도구 카탈로그가 기준 카탈로그이며, 사용 가능한 도구는 설치된 등급에 따라 달라집니다. 위험 사다리와 게이트는 HITL 위험 등급 레퍼런스에 정의되어 있습니다.

코드 샘플 — 빠른 시작

create_pdf → set_font/add_text로 콘텐츠를 구성합니다.
output_pdf를 file_path와 함께 호출 → 게이트가 챌린지 봉투를 반환합니다(파일은 쓰이지 않습니다).
챌린지를 사람에게 전달합니다.
승인되면, 동일한 인수에 챌린지의 토큰으로 설정한 _confirmation_token을 추가하여 output_pdf를 다시 호출 → 파일이 쓰이고 세션이 파괴됩니다.

코드 샘플 — 프로덕션

챌린지는 항상 일시 정지로 취급합니다. 루프에서 재시도하지 말고, 토큰을 조작하지 마십시오.
토큰은 일회용이며 도구 이름에 바인딩됩니다. output_pdf에 대해 발급된 토큰은 다른 도구를 인가할 수 없습니다.
사람이 거부하면 다시 호출하지 마십시오. 파일을 쓰지 않고 바이트를 복구하려면, 대신 output_pdf를 base64 모드로 호출합니다. 이렇게 하려면 세션이 여전히 존재해야 하므로, 필요할 것으로 예상되면 게이트된 시도에서 destroy: false를 사용합니다.
승인 전에 토큰이 만료되면, 게이트가 새 챌린지를 발급합니다. 새 챌린지를 전달합니다.

엣지 케이스 & 주의 사항

토큰이 전혀 제공되지 않음. 작업이 대기 상태로 유지됩니다. 사람이 승인한 다음 토큰을 전달하고 다시 호출해야 합니다.
만료된 토큰. 새 챌린지가 발급됩니다. 새 챌린지를 다시 전달합니다.
잘못된 도구. 토큰은 도구에 바인딩됩니다. 다른 도구에 재사용하면 실패하고, 새 챌린지가 발급됩니다.
절대 경로가 아님. 잘못된 경로로 간주되어 게이트 이전에 거부됩니다.
쓰기 권한 없음 / 디스크 가득 참. 이는 승인 이후 발생하는 파일 쓰기 실패입니다. 이 실패를 표면화합니다. 무작정 재시도하지 마십시오.
재호출 전에 세션이 파괴됨. 이전 output_pdf가 destroy: true를 사용했다면, 세션이 사라집니다. 승인 왕복을 예상할 때는 destroy: false를 사용합니다.

성능

게이트는 토큰 저장소 조회와 사람 승인을 위한 왕복을 추가합니다. 전체 경과 시간을 좌우하는 것은 사람이지 서버가 아닙니다. 프로파일은 structural입니다.

보안 참고 사항

게이트는 에이전트와 서버의 파일 시스템 사이에 있는 경계입니다. 게이트는 파일 쓰기가 사람이 인가해야 하는 되돌릴 수 없는 부작용이기 때문에 존재합니다. 토큰은 일회용이고, 도구에 바인딩되며, 시간 제한이 있습니다. 클라이언트가 JSON을 다른 키 순서로 다시 직렬화할 수 있기 때문에, 인수는 의도적으로 토큰에 해싱되지 않습니다. 따라서 바인딩은 인수 일치가 아니라 도구 + 논스 + TTL입니다. 토큰을 로그에 기록하지 마십시오. 토큰을 일회용 비밀로 취급하십시오.

준수

진술	사양	조항	reference_id
대기 중인 승인은 실패가 아니라 정상 응답입니다.	PSR-18	§3
트랜스포트는 결과와 무관하게 응답을 반환합니다.	PSR-18	§p2

이 레시피는 게이트 메커니즘을 설명합니다. 게이트가 어떤 작업을 “안전하게” 만든다고 주장하지는 않습니다. 게이트는 부작용을 사람이 인가하도록 만듭니다.

상용 컨텍스트

해당 없음 — 게이트와 output_pdf는 Core입니다.

트랜스포트 가용성

트랜스포트	사용 가능	참고
MCP (stdio)	예	챌린지는 사람이 확인할 수 있도록 도구 결과로 호스트에 표면화됩니다.
REST	예	챌린지는 응답 본문으로 반환됩니다. 토큰과 함께 다시 호출합니다.
gRPC	예	단항(Unary)입니다. 챌린지가 응답 메시지입니다. 토큰과 함께 다시 호출합니다.

HITL 위험 등급

위험 사다리는 Safe (0) → Caution (1) → Review (2) → Approval Required (3)입니다. Approval Required 도구만 사람 확인이 필요합니다. output_pdf는 Approval Required입니다. base64 모드는 이를 Review로 강등하고 게이트를 건너뜁니다. file 모드는 Approval Required를 유지하고 게이트를 적용합니다. 기준이 되는 사다리와 정책 해석은 HITL 위험 등급 레퍼런스에 있습니다.

확인 게이트 JSON 봉투

게이트 결과는 서버의 확인 게이트가 노출하는 정확히 두 가지 형태입니다:

허용됨(Safe/Caution/Review, 또는 유효한 토큰이 소비됨):

{ "allowed": true }

챌린지(유효한 토큰이 없는 Approval Required):

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

대상 파일이 이미 존재하면, challenge 텍스트에 덮어쓰기 경고 줄도 포함됩니다. 동일한 도구를 다시 호출하되 _confirmation_token을 token 값으로 설정하면 { "allowed": true }가 반환되고, 작업이 진행됩니다. 토큰은 일회용이며 챌린지에 명시된 시간 창이 지나면 만료됩니다.