Cloudflare Agents – Durable Objects 기반 영속 상태 AI 에이전트 SDK

왜 Cloudflare Agents인가
핵심 기능
빠른 시작 예시
패키지 구성
누구에게, 어떤 케이스에 적합한가
예제
설치 및 배포
라이선스
관련 문서

Cloudflare Agents는 Cloudflare의 Durable Objects 위에서 동작하는 영속 상태 AI 에이전트 SDK다. 각 에이전트는 독립된 상태·스토리지·생명주기를 갖고, 유휴 시 자동 휴면(hibernate)했다가 요청이 오면 즉시 깨어난다. 사용자 1명당, 세션당, 게임룸당 에이전트 수백만 개를 비활성 상태에서는 비용 없이 운영할 수 있다.

npm create cloudflare@latest -- --template cloudflare/agents-starter
# 또는 기존 프로젝트에 추가
npm install agents

왜 Cloudflare Agents인가

기존 AI 에이전트 구현의 공통 문제는 무상태(stateless) 서버리스 함수와 장기 실행 에이전트 사이의 불일치다. 일반 Cloudflare Worker는 요청 단위로 실행되어 상태를 유지할 수 없지만, Durable Objects는 액터(actor) 모델로 메모리·SQLite·WebSocket 연결을 영속적으로 보유한다. Cloudflare Agents는 이 Durable Objects 위에 에이전트 패턴을 추상화해 상태 동기화, RPC, 스케줄링, MCP 연동을 모두 제공한다.

핵심 기능

기능	설명
Persistent State	상태 변경이 연결된 모든 클라이언트에 자동 동기화, 재시작 후에도 유지
Callable Methods	`@callable()` 데코레이터로 타입 안전 RPC 노출
Sub-agents	부모/자식 Durable Object 합성, 중첩 라우팅
Scheduling	일회성, 반복, cron 기반 작업 예약
WebSockets	양방향 실시간 통신, 생명주기 훅 포함
AI Chat	메시지 영속화, 재개 가능한 스트리밍, 서버/클라이언트 툴 실행
MCP	MCP 서버 및 클라이언트 역할 수행 (HTTP·SSE·RPC·elicitation)
WebMCP	브라우저 측 툴을 WebSocket으로 에이전트에 노출
Workflows	인간 승인(human-in-the-loop)을 포함한 내구성 멀티스텝 작업
Email	Cloudflare Email Service로 이메일 발송·수신·회신
Voice	연속 STT, 스트리밍 TTS, VAD, 끼어들기, SFU 유틸리티
Browser Agents	`agents/browser`로 브라우저 탭 내에서 에이전트 실행
Code Mode	LLM이 툴 호출 대신 실행 가능한 TypeScript를 생성
Sandboxed Execution	가상 파일시스템을 가진 격리된 Worker에서 코드 실행
x402 Payments	x402 프로토콜 기반 호출당 결제 API/툴
SQL	Durable Objects SQLite 직접 쿼리
React Hooks	`useAgent`, `useAgentChat`, `useVoiceAgent`

빠른 시작 예시

상태를 유지하고 React 프론트엔드와 실시간 동기화되는 카운터 에이전트:

// server.ts
import { Agent, routeAgentRequest, callable } from "agents";

export type CounterState = { count: number };

export class CounterAgent extends Agent<Env, CounterState> {
  initialState = { count: 0 };

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};

// client.tsx
import { useAgent } from "agents/react";

function Counter() {
  const [count, setCount] = useState(0);
  const agent = useAgent<CounterAgent, CounterState>({
    agent: "CounterAgent",
    onStateUpdate: (state) => setCount(state.count)
  });
  return <button onClick={() => agent.stub.increment()}>{count}</button>;
}

상태 변경은 연결된 모든 클라이언트에 자동 반영된다.

패키지 구성

패키지	역할
`agents`	코어 SDK — `Agent` 클래스, 라우팅, 상태, 스케줄링, MCP, 이메일, 워크플로
`@cloudflare/ai-chat`	고수준 AI 채팅 — 메시지 영속화, 재개 스트리밍, 툴 실행
`@cloudflare/think`	의견 반영 채팅 에이전트 기반 — 에이전트 루프, 스트림 재개, 클라이언트 툴
`@cloudflare/codemode`	Code Mode — LLM이 툴 호출 대신 코드를 작성
`@cloudflare/shell`	샌드박스 실행 + 가상 파일시스템(`Workspace`)
`@cloudflare/voice`	음성 파이프라인 — STT·TTS·VAD·스트리밍·SFU
`hono-agents`	Hono 앱에 에이전트를 추가하는 미들웨어

누구에게, 어떤 케이스에 적합한가

Cloudflare Workers 기반 SaaS 개발자: 사용자별·세션별 AI 에이전트를 대규모로 실행해야 할 때. Durable Objects의 액터 모델 덕분에 DB 없이 영속 상태 관리 가능.
MCP 생태계 통합 팀: 에이전트가 MCP 서버이자 클라이언트로 동작해야 할 때. WebMCP로 브라우저 툴도 에이전트에 노출 가능.
음성·실시간 AI 앱 빌더: 내장 Voice 파이프라인(STT·TTS·VAD)으로 복잡한 음성 에이전트를 빠르게 구축.
결제 통합 AI 서비스: x402 프로토콜로 API 호출당 결제 모델 구현.

예제

examples/ 디렉터리에 30개 이상의 독립 실행 데모가 있다. 주요 카테고리:

Showcase: playground/ — 상태·스케줄링·채팅·MCP·워크플로·이메일·음성을 한 UI에서
Chat & 어시스턴트: assistant/, resumable-stream-chat/, dynamic-tools/
MCP: mcp/, mcp-client/, webmcp/, mcp-elicitation/
Code Mode & 샌드박스: codemode/, dynamic-workers/
Voice: voice-agent/, elevenlabs-starter/
인증·결제·이메일: auth-agent/, x402/, email-agent/

설치 및 배포

# 신규 프로젝트
npm create cloudflare@latest -- --template cloudflare/agents-starter

# wrangler.jsonc — Durable Objects 바인딩 필수
{
  "durable_objects": {
    "bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }]
}

Node.js 24+ 필요. 문서: developers.cloudflare.com/agents/

라이선스

Apache-2.0

AI Sparkup