Pi Durable와 Cloudflare Durable Objects를 결합해 여러 대화와 예약 작업을 처리하는 채팅 에이전트를 만드는 예제를 소개한다. 세션별 데이터를 저장하고, 유휴 상태에서 중단됐다가 다시 시작할 수 있으며, 대화 기록 검색은 하위 에이전트에 맡긴다.
Cloudflare Durable Objects는 요청, WebSocket 메시지 또는 알람이 도착하면 실행되고 유휴 상태에서는 중단될 수 있다. 이 예제에서는 Durable Object 하나를 Pi Durable 세션 하나에 대응시킨다. 각 세션은 SQLite 기반 저장소에 상태를 보존하며, 같은 세션 URL을 연 여러 참여자가 하나의 채팅 세션에서 대화할 수 있다. 세션 ID가 다르면 상태도 분리된다.
Pi Durable는 세션 저장소를 특정 방식으로 제한하지 않는다. 내장 메모리·JSONL·SQLite 지원 외에 자체 저장소를 사용할 수 있고, Cloudflare Durable Objects용 SQLite 어댑터도 제공한다. 자체 어댑터나 다른 저장소를 구현할 때는 Vitest 또는 Jest 호환 테스트 실행기에서 제공되는 적합성 테스트 모음으로 동작을 확인할 수 있다.
Durable Object가 시작될 때 Pi Durable 하니스를 초기화한다. 객체는 최초 생성 때뿐 아니라 절전 또는 제거 뒤 요청·알람·WebSocket 메시지로 다시 시작될 때도 생성자를 실행한다. 초기화가 끝날 때까지 이벤트 처리는 보류된다. WebSocket 연결이 유지되는 동안 객체가 절전 상태에 들어갈 수 있으며, 다시 시작하면 연결에 저장된 참여자 이름과 선택한 대화 정보를 바탕으로 이벤트 스트림을 복원한다.
한 세션 안에는 독립 대화를 여러 개 만들거나, 특정 사용자 또는 어시스턴트 메시지까지의 기록을 이어받는 분기 대화를 만들 수 있다. 요청 ID를 대화 생성과 같은 커밋에 저장해 연결이 끊긴 뒤 클라이언트가 요청을 재전송해도 중복 생성하지 않도록 한다. 여러 사람이 모델이나 도구가 실행되는 중 메시지를 보내면 Pi의 영속 인박스에 들어가 순서대로 처리된다.
예약 작업은 Pi의 작업 마감 시각을 Durable Object 알람에 반영한다. Pi는 여러 마감 시각을 추적하지만 Durable Object에는 알람이 하나뿐이므로, 세션은 작업 목록을 바탕으로 가장 이른 시각을 설정하고 객체가 깨어날 때 알람을 다시 계산한다. 진행 중인 작업에는 복구용 알람을 설정해 객체가 제거된 뒤에도 작업을 이어갈 수 있게 한다. 알람은 최소 한 번 실행될 수 있으므로 처리기는 멱등성을 갖춰야 하며, 예제는 저장된 작업을 다시 확인하고 안정적인 요청 ID로 중복 제출을 막는다.
대화 기록 검색은 search_history 도구가 하위 에이전트에 맡긴다. 하위 에이전트는 같은 세션의 다른 최상위 대화에서 사용자와 어시스턴트 메시지를 검색하며, 검색을 시작한 대화의 이전 메시지도 살펴본다. 자신의 대화나 이전 검색이 만든 메시지는 검색하지 않아 생성된 결과가 이후 검색의 근거가 되는 것을 막는다. 예제의 search_conversations 도구는 단순 부분 문자열 검색을 사용하며, 원시 검색 결과와 중간 도구 호출은 하위 대화에 남고 부모 대화에는 최종 답변만 전달된다.
로컬 실행 조건
Node.js 22.19 이상, pnpm 11, OpenAI API 키가 필요하다. 저장소를 복제하고 의존성을 설치한 뒤 환경 변수 파일을 준비해 실행한다.
git clone https://github.com/earendil-works/pi-durable-cloudflare.git
cd pi-durable-cloudflare
pnpm install
cp .dev.vars.example .dev.vars
OPENAI_API_KEY=your-key pnpm dev
세션을 만든 뒤 URL을 다른 브라우저에서 열어 같은 대화에 참여할 수 있다. 예제에서는 한 대화에 이벤트 저장소로 PostgreSQL을 쓰기로 했다고 입력하고, 새 대화에서 그 결정을 물어 기록 검색을 시험한다. 이어 사이드바에서 검색 하위 에이전트를 확인하고, 2분 뒤 날씨를 확인하도록 예약한 뒤 브라우저를 닫았다가 마감 뒤 다시 열어볼 수 있다. 데모에는 인증 기능이 없다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요