Pi 1.5 업데이트 전 확인할 것: 스트리밍 저장과 대화 호환성 변경

흐르는 출력을 묶어 저장하는 과정을 표현한 생성형 개념 이미지다. 실제 제품 화면이나 시스템 구성도는 아니다.

에이전트 SDK를 업데이트한 뒤 문제가 생기면 이전 버전을 다시 배포하면 될까. Cloudflare의 PiHarness를 사용한다면 이번에는 대화 데이터까지 확인해야 한다. Pi 1.5에서 실행한 대화는 Pi 1.4가 읽지 못하므로, 전환 전에 복구 계획을 정해야 한다.

Cloudflare는 2026년 11월 3일 Agents SDK 0.33.0의 Pi 1.5 지원을 발표했다. 이 글은 공식 문서에서 확인한 변경과 이를 바탕으로 제안하는 배포 점검을 구분한다. 실제 서비스나 유료 모델 호출로 성능을 측정하지 않았다.

먼저 영향 범위를 찾는다

PiHarness, agents/models/pi-ai 또는 Pi 도구를 쓰는 코드가 대상이다. Agents SDK를 사용한다는 사실만으로 모든 앱에 같은 수정이 필요한 것은 아니다.

프로젝트 루트에서 다음 명령으로 검토할 파일을 찾을 수 있다. 읽기 전용 검색이며, 문자열을 조립하는 코드나 별도 패키지는 추가 확인이 필요하다.

공식 업그레이드 안내는 Pi 패키지의 1.5 계열 정렬과 pi-schema 의존성, 이벤트 소비 코드 변경을 요구한다. 배포 코드와 lockfile을 함께 검토한다. Agents SDK 변경 기록

화면에 보인 출력과 저장된 출력의 간격

이번 변경은 스트리밍 조각마다 저장하던 작업을 배치로 묶는다. 화면에는 진행 상황이 바로 보이지만 저장은 늦을 수 있다.

공식 문서는 기본 저장 간격이 1,000ms이며, 스트리밍 도중 충돌하면 그만큼의 최근 출력이 사라질 수 있다고 설명한다. Harness.open의 settings.progress.persistWithinMs를 0으로 설정하면 매 업데이트를 저장하지만 쓰기 작업이 늘어난다. 서비스가 허용하는 복구 지점과 저장 비용을 함께 결정해야 한다. Pi 복구 문서

공식 발표의 SQLite 벤치마크에는 긴 답변의 저장 트랜잭션 감소가 보고돼 있다. 이는 특정 조건의 결과다. 내 서비스의 지연 시간이나 청구 금액이 같은 비율로 줄어든다는 근거로 사용하지 않는다. 11월 3일 발표

여기서 실무적으로 점검할 항목은 재접속한 화면이다. 끊기기 직전에 표시된 텍스트와 재시작 후 복원된 텍스트가 달라도, 프런트엔드가 과거 조각을 무조건 덧붙이면 중복이나 잘못된 완료 표시가 생길 수 있다. 재연결 테스트에서 서버가 돌려준 상태를 기준으로 화면을 다시 맞추는지 확인한다.

이벤트 처리와 실패 표시를 함께 바꾼다

session.events()는 session.watch()로 바뀐다. 이름만 교체하는 작업으로 끝내지 말고, 화면이 개별 이벤트를 누적하는 방식인지 현재 대화 상태를 그리는 방식인지 검토한다.

Pi Durable 1.5는 watch 호출과 종료 형식, 대화 항목의 창 구조도 바꿨다. 사용자 정의 저장소나 저수준 API를 직접 연결했다면 상위 SDK 안내만으로 끝내지 말고 해당 변경 목록을 대조한다. Pi Durable 1.5.0 변경 기록

실패한 실행의 runFailure는 유휴 상태에도 남을 수 있다. 따라서 빈 객체인지 비교하는 코드 대신 실제 실행 상태를 확인해야 한다. 오래된 대화를 표시하는 기능과 실패 메시지가 사라지는 시점도 회귀 테스트에 포함한다. Agents SDK 업그레이드 절차

반복 충돌 작업을 parked 상태에 두던 흐름과 retry()도 제거됐다. 이제 실패를 화면과 운영 기록에 드러내고, 원인을 해결한 뒤 새 실행을 시작하는 흐름이 필요하다.

계속하기는 실패 원인을 해결한 뒤 실행한다

session.continue()는 새 사용자 메시지를 붙이지 않고 기존 대화로 실행을 시작한다. 세션은 유휴 상태여야 한다. 이미 답변으로 끝난 대화라면 nothing_to_answer로 끝날 수 있다. 이를 일반 성공으로 뭉뚱그리지 않는다. 세션 사용 문서

운영 UI에서는 마지막 작업의 결과와 원인을 먼저 조회하고, 사용 가능한 모델이나 도구 상태가 복구됐는지 확인한 뒤 계속하기를 제공하는 편이 안전하다. 버튼 연타와 네트워크 재시도도 별도 시험한다.

외부 쓰기 작업은 더 신중해야 한다. 복구 후 도구를 다시 호출할 수 있다는 가정 아래, 작업 식별자와 처리 결과 조회를 설계한다. 주문이나 메시지 전송을 수행하는 도구에는 단순한 텍스트 생성 테스트만으로 충분하지 않다. 이는 이 글의 설계 권고이며, 이번 릴리스가 외부 작업의 중복 방지를 자동 보장한다는 뜻은 아니다.

배포 전에 통과시킬 검증

다음은 제안하는 검증 절차다. 이 글에서 실행한 결과는 아니다.

1. 운영과 분리된 테스트 대화로 변경된 의존성과 UI를 빌드한다.

2. 긴 스트림 도중 연결을 끊고 복구된 텍스트·실행 상태를 확인한다.

3. 모델 오류와 실행 횟수 제한을 각각 만들고, 실패 이유와 계속하기 동작을 확인한다.

4. 과거 대화의 페이지 이동, 재접속, reset·compaction 이후 표시를 검사한다.

5. 도구 실행 중 중단을 재현하고 외부 작업이 중복되지 않는지 별도로 확인한다.

마지막으로 전환된 저장소를 예전 실행 파일이 다시 열게 하는 배포 절차를 막는다. 공식 안내는 1.5로 진행한 대화에 대해 이전 버전으로 내리는 대신 수정 버전으로 전진할 것을 요구한다. 백업의 존재만 확인하지 말고, 복원 대상·복구 시점·복원 뒤 손실되는 대화의 범위를 테스트 환경에서 검증한다.

이번 업데이트의 도입 판단은 성능 수치보다 이 복구 절차에서 시작하는 편이 좋다. 화면, 저장, 외부 도구의 상태를 각각 확인해야 업데이트 뒤에도 대화를 안전하게 이어갈 수 있다.