Cloudflare Agents SDK의 Pi 1.6: 응답을 기다리는 도구와 재실행 설계
사람의 답이나 기한까지 도구를 대기시키는 Pi 1.6의 동작과 중복 신호·재실행·Pi 1.5 롤백 제약을 점검한다.
대기 중인 작업을 신호가 다시 깨우는 구조를 표현한 AI 생성 개념 이미지. 실제 제품 화면은 아니다.
에이전트가 사람의 확인을 기다린다고 실행 호출을 계속 붙잡아 둘 필요는 없다. Cloudflare가 11월 20일 발표한 Agents SDK 0.34.0의 Pi 1.6에서는 도구가 대기 상태를 반환하고, 지정한 신호가 도착하거나 기한이 지나면 다시 실행될 수 있다. 이때 대기 중인 도구의 실행 호출 점유는 끝나지만 세션의 작업은 끝난 게 아니다. 공식 업데이트
응답을 기다리는 대신, 다시 실행할 조건을 반환한다
예를 들어 문서 제목을 정하는 도구가 두 가지 후보 중 하나를 사람에게 물을 수 있다. 첫 실행에선 답이 저장된 신호가 있는지 확인하고, 없다면 질문을 표시한 뒤 대기 상태를 반환한다. 대기 중에는 실행 호출을 점유하지 않아 Durable Object가 유휴 상태로 들어가거나 메모리에서 내려갈 수 있다.
사용자가 답하면 애플리케이션이 harness.signal()로 대상 작업에 신호를 전달한다. 등록한 신호가 도착하거나 설정한 기한이 지나면 도구 함수가 다시 실행된다. 중단됐던 자바스크립트 함수가 같은 줄에서 이어 실행되는 구조가 아니다. 재실행된 도구는 신호를 확인해 결과를 반환하거나, 기한이 먼저 지났다면 앱에서 정한 만료 처리를 한다. 도구 대기 문서
아래는 상태 전이를 보여 주는 의사코드다. 함수명은 설명용이며, 그대로 SDK에 붙여 넣는 예제가 아니다.
‘아직 작업 중’과 ‘지금 CPU를 점유 중’을 구분한다
대기하는 동안 작업은 진행 중으로 남는다. UI에서는 이를 로딩만 계속되는 상태보다 응답 대기로 보여 주는 편이 명확하다. 새로고침·재연결 뒤에는 현재 상태를 다시 조회하고, 만료와 취소도 따로 표시한다.
공식 문서는 harness.signal()의 결과로 delivered 외에 duplicate, invalid, closed, not_found를 안내한다. 신호 전달 성공이 도구 실행이나 사용자 작업 완료까지 뜻하는 것은 아니다. 답변을 처음 수락했는지, 작업이 실제로 끝났는지 따로 표시한다. 도구나 훅이 다시 호출될 수 있으므로 질문 표시는 작업 ID 기준으로 중복되지 않게 설계한다.
사람의 승인이 필요한 작업이라면 beforeTool에서 도구 실행 전에 대기시킬 수 있다. 다만 PiHarness에 승인이 자동으로 들어 있는 것은 아니다. 앱이 승인과 거절을 구분하고, 어떤 요청의 어떤 작업을 누가 승인했는지 확인해야 한다. 기한 만료나 잘못된 신호를 승인으로 처리하지 않는다. 공식 PiHarness 문서
업그레이드 전에는 대기 중인 대화까지 점검한다
공식 가이드는 대화가 Pi 1.6에서 실행된 뒤 Worker를 Pi 1.5 기반 SDK로 되돌리면 그 대화의 도구 호출과 모델 요청을 처리할 수 없다고 설명한다. 모든 1.5 대화가 1.6에서 열리지 않는다는 말이 아니다. 문제의 방향은 1.6에서 실행된 대화를 1.5로 되돌리는 경우다. Cloudflare는 문제가 생기면 이전 버전으로 내리기보다 수정본으로 전진 배포하라고 권고한다. Pi 설치·호환성 문서
배포 전에 실제 권한이나 데이터를 쓰지 않는 테스트 대화로 다음을 확인한다.
- 첫 실행에서 질문이 한 번만 표시되고, 답 전에는 작업이 완료되지 않는가.
- 신호가 들어오면 도구가 재실행되고, 응답을 두 번 보내도 같은 결과가 중복 처리되지 않는가.
- 신호 없이 기한이 지나거나 사용자가 취소하면 완료가 아닌 별도 상태로 끝나는가.
- 재접속 후 대기 상태를 표시할 수 있고, 장애 시에는 기존 대화가 영향을 받지 않도록 전진 수정안을 적용할 수 있는가.
이 글은 공식 문서를 바탕으로 대기와 재실행을 구분한 안내다. 실제 배포, 하이버네이션 실측이나 요금 검증은 하지 않았다.