cloudflare/agents

Cloudflare Agents – 상태 유지형 서버 사이드 AI/도구 에이전트

무엇인가요 – Cloudflare Workers에서 Durable Objects를 작성할 수 있는 TypeScript/JavaScript SDK입니다. 각 객체를 독립적이고 장기간 유지되는 "에이전트"로 취급할 수 있습니다. 에이전트는 자체적인 영구 저장소를 가지며, 스케줄된 작업을 실행하고, WebSocket 연결을 유지하며, AI 모델을 호출하고, MCP(다중 채널 프로토콜) 서버 또는 클라이언트로 작동하며, @callable() 데코레이터를 사용해 타입 안전한 RPC 메서드를 노출할 수 있습니다. 런타임은 유휴 상태의 에이전트를 자동으로 절전 모드로 전환하고 필요 시 다시 깨우므로, 사용자 또는 세션 단위로 수백만 개의 에이전트를 거의 제로의 유휴 비용으로 구동할 수 있습니다.

핵심 개념

개념	제공되는 기능
영구 상태	상태는 Cloudflare Durable Object에 저장되며 재시작 후에도 유지됩니다. 변경 사항은 모든 연결된 클라이언트에 자동으로 동기화됩니다.
호출 가능한 메서드	`@callable()`로 클래스 메서드를 데코레이트하면, 브라우저나 다른 워커에서 호출 가능한 타입 안전한 RPC 엔드포인트가 됩니다.
서브 에이전트	에이전트는 패싯과 중첩 라우팅을 통해 다른 에이전트(부모/자식)를 조합할 수 있어 계층적 워크로드를 가능하게 합니다.
스케줄링	한 번만 실행, 반복 또는 cron 스타일의 작업을 에이전트 내부에서 스케줄링할 수 있습니다.
WebSocket	라이프사이클 훅이 내장된 실시간 양방향 채널이 제공됩니다.
AI 채팅 및 도구	메시지를 영구 저장하고 재개 가능한 스트리밍을 지원하는 채팅 레이어(`@cloudflare/ai-chat`)가 내장되어 있으며, 하위 에이전트를 "도구"로 실행할 수 있습니다.
MCP / WebMCP	에이전트는 다중 채널 프로토콜(HTTP, SSE, RPC 등)을 공개하거나 사용할 수 있으며, 브라우저와 도구를 연결할 수 있습니다.
워크플로우	일시 중지/재개 및 승인 단계를 포함한 인간이 개입하는 다단계 프로세스를 모델링할 수 있습니다.
이메일 및 음성	Cloudflare Email Service 및 음성 파이프라인(STT/TTS, VAD, SFU)과 직접 통합됩니다.
코드 모드	LLM이 도구를 호출하는 TypeScript 코드를 생성하고, 생성된 코드는 사전 처리된 워커(`@cloudflare/shell`)에서 사전 환경에서 실행됩니다.
결제(x402)	호출당 요금이 부과되는 API를 x402 프로토콜로 청구할 수 있습니다.
관측성	자동으로 추적, 메트릭, 구조화된 로그가 생성됩니다.
SQL	에이전트는 Durable Object 내에서 직접 SQLite 쿼리를 실행할 수 있습니다.
프론트엔드 훅	React 훅(`useAgent`, `useAgentChat`, `useVoiceAgent`)과 범용 JS 클라이언트(`AgentClient`)를 통해 통합이 간편합니다.

모노레포 내 패키지

패키지	역할
`agents`	핵심 SDK – 에이전트, 라우팅, 스케줄링, MCP, 워크플로우, 음성, 브라우저 에이전트 등
`@cloudflare/ai-chat`	영구 메시지와 도구 실행을 지원하는 고수준 채팅 추상화
`@cloudflare/think`	"에이전트 루프"와 워크스페이스 유틸리티를 추가하는 의견 있는 채팅 에이전트 기반
`@cloudflare/codemode`	LLM 출력을 실행 가능한 TypeScript로 변환하여 도구를 호출
`@cloudflare/shell`	가상 파일 시스템을 갖춘 사전 처리된 JS 실행 환경으로 안전한 코드 모드 실행
`@cloudflare/voice`	음성 API 호환성 래퍼(핵심 `agents/voice` 내보내기로 이전되어 비추천)
`@cloudflare/worker-bundler`	런타임에서 워커를 번들링하며, Worker-Loader 바인딩과 함께 사용
`hono-agents`	Hono 웹 프레임워크 앱에 에이전트를 추가하는 미들웨어

일반적인 사용 사례

사용자별 어시스턴트 – 각 사용자마다 하나의 에이전트가 대화 기록, 선호 설정, 스케줄된 알림을 저장합니다.
실시간 멀티플레이어 룸 – 각 게임 룸이 에이전트로, WebSocket을 통해 모든 플레이어와 상태를 동기화합니다.
도구 호출 AI 어시스턴트 – LLM이 하위 에이전트(예: 캘린더 에이전트, 검색 에이전트)를 호출하고 결과를 사용자에게 스트리밍합니다.
워크플로우 자동화 – 복잡한 다단계 프로세스(예: 티켓 트라이아지 → 인간 승인 → 실행)를 지속 가능한 워크플로우로 모델링합니다.
음성 봇 – STT/TTS 서비스와 에이전트를 결합해 대화 상태를 유지하고 다른 도구를 호출할 수 있습니다.
호출당 결제 API – 함수를 x402 기반 청구 엔드포인트로 공개하고, 에이전트가 청구 및 제한 처리를 담당합니다.

시작하기 (README에서)

스타터 프로젝트 생성

npm create cloudflare@latest -- --template cloudflare/agents-starter

기존 워커에 SDK 추가
```
npm install agents
```
에이전트 작성 – Agent를 상속하고 @callable()로 메서드를 표시 (README의 카운터 예제 참조).
wrangler.jsonc에서 Durable Objects 구성 (바인딩 이름, 클래스 이름, SQLite 마이그레이션 태그).
Cloudflare Wrangler로 배포 – 일반 워커와 동일하게.
브라우저에서 사용 – React 훅 useAgent (또는 범용 AgentClient)를 사용해 메서드를 호출하고 실시간 상태 업데이트를 수신합니다.

문서 및 학습 리소스

완전한 문서 – https://developers.cloudflare.com/agents/ (시작 가이드, API 참조, 튜토리얼).
예제 – examples/에 30개 이상의 자가 포함된 데모 (플레이그라운드, 채팅 어시스턴트, MCP 서버/클라이언트, 코드 모드, 음성 파이프라인, 워크플로우 등).
설계 문서 – design/에는 아키텍처 결정 기록과 패턴 가이드(Anthropic 패턴, 인간이 개입하는 프로세스 등) 포함.
OpenAI SDK 예제 – openai-sdk/에서는 Cloudflare 에이전트와 함께 OpenAI Agents JavaScript SDK를 사용하는 방법을 보여줍니다.

개발 워크플로우 (기여자용)

Node 24+, pnpm 워크스페이스, Nx로 작업 오케스트레이션.
빌드: pnpm run build (Nx가 종속성 순서로 패키지 빌드하고 결과를 캐시).
린트/타입 체크: pnpm run check.
테스트: pnpm run test (Vitest + Workers 런타임) 및 pnpm run test:react (Playwright React 훅 테스트).
패키지 변경 시 changeset 필요 (pnpm exec changeset).
외부 PR은 현재 수락하지 않음. 팀은 내부 반복을 선호하지만, 이슈 및 토론은 환영합니다.

라이선스

MIT – 허용적인 오픈소스 라이선스.

결론 – Cloudflare Agents는 Cloudflare의 엣지 네트워크에서 대규모로 실행 가능한 상태 유지형 서버 사이드 AI 에이전트를 구축하기 위한 프로덕션 수준의 프레임워크이며, 실시간 동기화, 스케줄링, 도구 호출, 음성, 이메일, 결제 등에 대해 최고 수준의 지원을 제공합니다.

cloudflare/agents