Cloudflare Agents SDK 구조: Durable Object 기반 상태ful 에이전트를 설계하는 방법

요약: Cloudflare Agents SDK는 에이전트를 TypeScript class로 정의하고, Durable Object 위에서 상태, SQL 저장소, WebSocket 연결, 스케줄 작업을 제공하는 구조다. AI 앱을 stateless API 호출로만 만들면 대화 기록, 장기 작업, 승인 흐름, 재시도, 실시간 연결이 전부 별도 인프라가 된다. Cloudflare 방식의 핵심은 “에이전트 하나를 이름 있는 stateful instance로 본다”는 점이다.

검색 의도: Cloudflare Agents SDK, Durable Object AI agent, stateful AI agent 설계, AI agent WebSocket scheduling

stateless 챗봇이 먼저 막히는 지점

많은 AI 기능은 처음에 단순 API route로 시작한다. 사용자가 메시지를 보내면 서버가 모델을 호출하고 응답을 반환한다. 이 구조는 빠르게 만들 수 있지만 조금만 제품다운 기능을 붙이면 바로 한계가 온다.

예를 들어 다음 요구가 생긴다.

• 사용자가 브라우저를 닫았다가 돌아와도 대화가 이어져야 한다.
• 모델 응답이 1분 이상 걸려도 stream을 유지해야 한다.
• 도구 호출 중 민감 작업은 사람 승인을 받아야 한다.
• 사용자가 없어도 예약된 시간에 에이전트가 작업해야 한다.
• 여러 sub-agent가 같은 작업 상태를 공유해야 한다.
• 실패한 작업은 자동 재시도하고 로그를 남겨야 한다.

이 요구를 일반 serverless function만으로 처리하면 Redis, queue, DB, WebSocket server, scheduler, workflow engine을 하나씩 붙이게 된다. 작은 팀에게는 인프라 부담이 커진다.

Cloudflare Agents SDK는 이 문제를 Durable Object 기반 모델로 푼다. 에이전트는 전역적으로 배포되지만 각 named instance는 자기 상태와 연결을 가진다. 사용자의 workspace, 고객 계정, support ticket, long-running task 같은 실제 객체를 에이전트 instance 하나로 매핑할 수 있다.

Durable Object mental model

Cloudflare 문서의 설명은 단순하다. “define a TypeScript class, give each real-world thing a stable name.” 즉 에이전트를 class로 만들고, 현실 세계의 어떤 대상에 안정적인 이름을 부여한다. 그 이름으로 요청이나 WebSocket 연결을 route하면 같은 instance가 깨어나 상태를 읽고 작업한다.

이 mental model은 AI 제품에 잘 맞는다. 예를 들어 다음처럼 나눌 수 있다.

• UserAgent:user_123: 개인 사용자의 장기 대화와 선호 저장.
• ProjectAgent:repo_456: 특정 repo의 분석 상태와 작업 로그 저장.
• TicketAgent:ticket_789: 고객 문의 처리 상태와 초안 저장.
• ReportAgent:daily_sales_2026_05_23: 리포트 생성 작업 상태 저장.

각 instance는 자체 SQL database와 key-value state를 갖고, idle 상태에서는 hibernate했다가 이벤트가 오면 다시 깨어난다. 개발자는 세션 복원과 상태 외부화를 덜 고민해도 된다.

어떤 기능이 기본으로 제공되는가

Cloudflare Agents SDK 문서에서 강조하는 기능은 다음과 같다.

첫째, 상태 저장이다. 에이전트는 built-in SQL database와 key-value state를 사용한다. 대화, tool call 결과, 사용자 설정, 작업 진행률을 저장할 수 있다. 실시간으로 연결된 클라이언트에 state sync도 가능하다.

둘째, AI chat이다. AIChatAgent는 streaming chat, message persistence, resumable stream, tool support를 제공한다. React hook과 붙이면 기본 채팅 UI를 빠르게 만들 수 있다.

셋째, 모델 선택이다. Workers AI뿐 아니라 OpenAI, Anthropic, Google Gemini 같은 provider를 사용할 수 있다. 모델은 바꿀 수 있지만 에이전트 상태와 연결 구조는 유지된다.

넷째, 도구와 human-in-the-loop다. 서버 도구, 브라우저에서 실행되는 클라이언트 도구, 사람 승인 흐름을 정의할 수 있다. 에이전트 도구를 MCP로 외부에 노출하는 흐름도 제공된다.

다섯째, schedule task다. 에이전트가 특정 시간이나 delay 후 깨어나 작업할 수 있다. 사용자가 접속하지 않아도 follow-up, 리포트 생성, 상태 점검을 할 수 있다.

여섯째, WebSocket과 sub-agent다. 실시간 연결과 multi-step workflow, sub-agent coordination이 기본 설계 안에 들어간다.

설계할 때 가장 먼저 정할 단위

Cloudflare Agents SDK를 쓴다고 모든 것을 하나의 거대한 agent class에 넣으면 안 된다. 가장 먼저 정해야 할 것은 instance 단위다. 어떤 현실 객체가 상태를 가져야 하는가를 정해야 한다.

나쁜 예시는 GlobalAgent 하나가 모든 사용자의 대화를 처리하는 구조다. 구현은 쉬워 보이지만 상태 충돌, 권한 분리, 디버깅이 어려워진다.

좋은 예시는 작업 경계가 명확한 구조다.

• 사용자별 장기 assistant는 user id 기준.
• 프로젝트 분석 agent는 project id 기준.
• 고객 문의 처리 agent는 ticket id 기준.
• 예약된 리포트 agent는 report id 기준.

기준은 세 가지다.

1. 상태가 자연스럽게 모이는 단위인가?
2. 권한을 독립적으로 적용할 수 있는가?
3. 문제가 생겼을 때 해당 instance만 재처리하거나 폐기할 수 있는가?

이 기준을 만족하면 운영이 쉬워진다.

승인 흐름을 제품 기능으로 넣기

AI 에이전트는 도구를 호출할 때 위험한 행동을 할 수 있다. 이메일 발송, 환불, 권한 변경, 외부 API 쓰기, 파일 삭제 같은 작업은 자동 실행하면 안 된다. Cloudflare Agents SDK가 human-in-the-loop를 언급하는 이유도 여기에 있다.

실무에서는 도구를 세 등급으로 나눈다.

• 자동 허용: 조회, 요약, 내부 상태 읽기, 임시 초안 생성.
• 승인 필요: 외부 전송, 결제 관련 변경, 사용자 데이터 수정.
• 금지: secret 출력, production DB 직접 변경, 대량 삭제.

승인 필요 도구는 UI에 명확한 confirmation을 보여줘야 한다. “이 이메일을 발송합니다”가 아니라 수신자, 제목, 본문 요약, 첨부, 취소 방법까지 보여주는 것이 좋다. 승인 이벤트도 agent state와 audit log에 저장한다.

scheduled agent를 쓸 때의 주의점

스케줄 기능은 강력하지만 남용하면 디버깅이 어려워진다. 에이전트가 사용자가 없는 시간에 깨어나 작업한다면 idempotency와 retry 정책이 필수다.

예를 들어 매일 오전 9시에 리포트를 생성하는 agent라면 다음을 정해야 한다.

• 같은 날짜 리포트가 이미 있으면 다시 만들지 않는다.
• 실패한 단계만 재시도한다.
• 외부 API rate limit에 걸리면 다음 실행 시간을 기록한다.
• 생성된 결과와 사용한 입력 데이터를 저장한다.
• 사람에게 보내는 알림은 중복 발송하지 않는다.

스케줄 작업은 “한 번 실행하면 끝”이 아니라 중간 실패와 재시작을 전제로 만들어야 한다. Durable state가 있는 구조는 이 점에서 유리하지만, 개발자가 상태 machine을 명확히 설계해야 한다.

비용과 관측성

stateful agent는 편하지만 비용 구조를 숨기면 안 된다. 모델 호출, WebSocket 연결, Durable Object 실행, 저장소, workflow 재시도, browser tool 사용이 모두 비용이 될 수 있다. 특히 long-running reasoning model을 사용하면 한 사용자의 작업이 몇 분 동안 이어질 수 있다.

초기부터 다음 로그를 남기는 편이 좋다.

• agent instance id.
• user id 또는 project id.
• 모델 이름과 토큰 사용량.
• tool call 이름과 결과 상태.
• 승인 대기 시간.
• retry 횟수.
• 최종 산출물 위치.
• 실패 error code.

관측성이 없으면 “AI가 가끔 이상하다”는 말밖에 남지 않는다. 에이전트 운영은 모델 품질과 시스템 품질이 섞여 있으므로 로그로 분리해야 한다.

실행 체크리스트

• 에이전트 instance 단위를 user, project, ticket, report 중 무엇으로 둘지 정했는가?
• 각 instance의 상태 보존 기간과 삭제 정책을 정했는가?
• 자동 허용, 승인 필요, 금지 도구를 분리했는가?
• 사람 승인 UI에 실행 대상과 취소 방법을 보여주는가?
• 스케줄 작업에 idempotency key를 넣었는가?
• 실패한 단계만 재시도하는 상태 machine을 설계했는가?
• 모델 호출, tool call, 승인, retry, 비용 로그를 남기는가?
• sub-agent를 쓰기 전에 단일 agent 흐름으로 먼저 검증했는가?

Cloudflare Agents SDK의 장점은 AI 앱의 상태 관리 문제를 제품 설계 단위로 끌어올린다는 데 있다. 단순 챗봇을 넘어서 사용자별 작업 공간, 장기 작업, 승인 흐름, 예약 실행이 필요하다면 stateless API route만으로 버티기보다 stateful agent 구조를 검토할 시점이다.