요약: 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
많은 AI 기능은 처음에 단순 API route로 시작한다. 사용자가 메시지를 보내면 서버가 모델을 호출하고 응답을 반환한다. 이 구조는 빠르게 만들 수 있지만 조금만 제품다운 기능을 붙이면 바로 한계가 온다.
예를 들어 다음 요구가 생긴다.
이 요구를 일반 serverless function만으로 처리하면 Redis, queue, DB, WebSocket server, scheduler, workflow engine을 하나씩 붙이게 된다. 작은 팀에게는 인프라 부담이 커진다.
Cloudflare Agents SDK는 이 문제를 Durable Object 기반 모델로 푼다. 에이전트는 전역적으로 배포되지만 각 named instance는 자기 상태와 연결을 가진다. 사용자의 workspace, 고객 계정, support ticket, long-running task 같은 실제 객체를 에이전트 instance 하나로 매핑할 수 있다.
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 하나가 모든 사용자의 대화를 처리하는 구조다. 구현은 쉬워 보이지만 상태 충돌, 권한 분리, 디버깅이 어려워진다.
좋은 예시는 작업 경계가 명확한 구조다.
기준은 세 가지다.
이 기준을 만족하면 운영이 쉬워진다.
AI 에이전트는 도구를 호출할 때 위험한 행동을 할 수 있다. 이메일 발송, 환불, 권한 변경, 외부 API 쓰기, 파일 삭제 같은 작업은 자동 실행하면 안 된다. Cloudflare Agents SDK가 human-in-the-loop를 언급하는 이유도 여기에 있다.
실무에서는 도구를 세 등급으로 나눈다.
승인 필요 도구는 UI에 명확한 confirmation을 보여줘야 한다. “이 이메일을 발송합니다”가 아니라 수신자, 제목, 본문 요약, 첨부, 취소 방법까지 보여주는 것이 좋다. 승인 이벤트도 agent state와 audit log에 저장한다.
스케줄 기능은 강력하지만 남용하면 디버깅이 어려워진다. 에이전트가 사용자가 없는 시간에 깨어나 작업한다면 idempotency와 retry 정책이 필수다.
예를 들어 매일 오전 9시에 리포트를 생성하는 agent라면 다음을 정해야 한다.
스케줄 작업은 “한 번 실행하면 끝”이 아니라 중간 실패와 재시작을 전제로 만들어야 한다. Durable state가 있는 구조는 이 점에서 유리하지만, 개발자가 상태 machine을 명확히 설계해야 한다.
stateful agent는 편하지만 비용 구조를 숨기면 안 된다. 모델 호출, WebSocket 연결, Durable Object 실행, 저장소, workflow 재시도, browser tool 사용이 모두 비용이 될 수 있다. 특히 long-running reasoning model을 사용하면 한 사용자의 작업이 몇 분 동안 이어질 수 있다.
초기부터 다음 로그를 남기는 편이 좋다.
관측성이 없으면 “AI가 가끔 이상하다”는 말밖에 남지 않는다. 에이전트 운영은 모델 품질과 시스템 품질이 섞여 있으므로 로그로 분리해야 한다.
Cloudflare Agents SDK의 장점은 AI 앱의 상태 관리 문제를 제품 설계 단위로 끌어올린다는 데 있다. 단순 챗봇을 넘어서 사용자별 작업 공간, 장기 작업, 승인 흐름, 예약 실행이 필요하다면 stateless API route만으로 버티기보다 stateful agent 구조를 검토할 시점이다.