cloudflare/agents
Build and deploy AI Agents on Cloudflare
Cloudflare Agents
정의 – Cloudflare Durable Objects 위에 영구적이고 상태를 유지하는 "에이전트"를 구축할 수 있게 해주는 TypeScript/JavaScript SDK입니다. 각 에이전트는 자체 Durable Object로 실행되어 격리된 스토리지, 수명 주기 훅, 유휴 시 절전 기능을 제공합니다. 플랫폼은 실시간 동기화, 스케줄링, AI 모델 호출, 도구 실행, MCP(멀티채널 프로토콜), 음성, 이메일, 결제 등을 일급 지원합니다.
핵심 개념
| 개념 | 제공 기능 |
|---|---|
| 영구 상태 | 에이전트는 재시작 후에도 데이터를 유지하고 연결된 모든 클라이언트에 자동으로 동기화합니다. |
| @callable() RPC | 클래스 메서드를 데코레이트하면 브라우저에서 로컬 함수처럼 호출할 수 있는 타입 안전 원격 프로시저가 됩니다. |
| 하위 에이전트 | 구성 및 라우팅을 위한 에이전트 계층(부모/자식)을 구축합니다. |
| 스케줄링 | 에이전트 내에서 실행되는 일회성, 반복 또는 cron 스타일 작업. |
| WebSockets | 수명 주기 이벤트가 있는 양방향 실시간 채널. |
| AI 채팅 및 도구 | 메시지를 저장하고, 재개 가능한 스트리밍을 지원하며, 다른 에이전트를 도구로 실행할 수 있는 내장 채팅 레이어(@cloudflare/ai-chat). |
| MCP / WebMCP | HTTP, SSE, RPC 또는 브라우저 측 도구 브리징을 위한 일반 멀티채널 프로토콜. |
| 워크플로 | 인간 승인을 위해 일시 중지할 수 있는 다단계 영구 작업. |
| 음성 및 이메일 | 스트리밍 음성-텍스트 / 텍스트-음성 파이프라인 및 Cloudflare Email Service 통합. |
| 결제 (x402) | x402 프로토콜을 통한 호출당 과금 API. |
| 관찰 가능성 | 추적, 메트릭, 구조화된 로그가 내장되어 있습니다. |
| SQLite | 에이전트별 SQLite DB에 대한 직접 쿼리. |
| React 훅 및 vanilla 클라이언트 | React용 useAgent, useAgentChat, useVoiceAgent; 일반 JS용 AgentClient. |
일반적인 사용 사례
- 사용자별 또는 세션별 상태 – 예: 방문 간 사용자 선호도를 기억하는 개인 비서.
- 실시간 협업 앱 – 모든 클라이언트가 동일한 상태를 즉시 확인하는 게임 룸, 공유 화이트보드 또는 대시보드.
- AI 기반 어시스턴트 – LLM을 호출하고, 대화 기록을 유지하며, 도구 에이전트(검색, 데이터베이스 등)를 호출하는 채팅 에이전트.
- 예약된 백그라운드 작업 – 사용자 데이터에 가까운 곳에서 실행되는 알림, 주기적 데이터 가져오기 또는 cron 스타일 작업.
- 음성 봇 – 에이전트와 오디오를 주고받을 수 있는 종단 간 음성 파이프라인.
- 워크플로 엔진 – 인간 개입 승인이 필요한 다단계 프로세스.
- 사용량 기반 API – 함수를 x402 가격 엔드포인트로 노출.
시작하기 (빠른 단계)
- 프로젝트 생성
npm create cloudflare@latest -- --template cloudflare/agents-starter - 기존 저장소에 SDK 추가
npm install agents - 에이전트 작성 –
Agent를 확장하고@callable()로 메서드를 표시합니다(README 카운터 예제 참조). wrangler.jsonc에서 Durable Objects 구성 (바인딩 이름, 클래스 이름, 필요한 경우 SQLite 마이그레이션).- 배포 –
wrangler publish사용(표준 Cloudflare Workers 워크플로). - 프론트엔드에서 사용 –
useAgentReact 훅 또는 vanillaAgentClient를 사용하여 메서드를 호출하고 실시간 상태 업데이트를 수신합니다.
모노레포의 패키지
| 패키지 | 역할 |
|---|---|
agents |
핵심 SDK – 에이전트, 라우팅, 스케줄링, MCP, 워크플로 등. |
@cloudflare/ai-chat |
영속성과 도구 실행을 갖춘 고수준 채팅 추상화. |
@cloudflare/think |
채팅 어시스턴트 구축을 위한 의견 기반 "에이전틱 루프" 베이스. |
@cloudflare/codemode |
LLM이 샌드박스 처리된 Worker 내부에서 실행되는 실행 가능한 TypeScript를 생성하도록 합니다. |
@cloudflare/worker-bundler |
동적 코드 로딩을 위해 런타임에 Workers를 번들링합니다. |
hono-agents |
Hono 웹 프레임워크 앱에 에이전트를 연결하는 미들웨어. |
(더 이상 사용되지 않음) @cloudflare/shell, @cloudflare/voice |
이전 API용 호환성 래퍼. |
문서 및 학습 리소스
- 전체 문서 – https://developers.cloudflare.com/agents/ (시작하기, API 참조, 가이드).
- 예제 –
examples/아래 30개 이상의 데모(플레이그라운드, 채팅 어시스턴트, MCP, 음성 파이프라인, 워크플로, 결제, 게임 등). - 가이드 – Anthropic 패턴, 인간-인-더-루프 워크플로,
design/의 설계 결정. - OpenAI SDK 예제 –
openai-sdk/는 OpenAI Agents JS SDK를 Cloudflare Agents와 함께 사용하는 방법을 보여줍니다.
누가 유지 관리하나요?
Cloudflare에서 개발했습니다. 이 저장소는 pnpm 워크스페이스와 Nx를 사용하여 빌드 및 테스트합니다. 현재 기여는 내부 기여자로 제한되지만, 이슈와 토론은 커뮤니티에 열려 있습니다.
라이선스
MIT (LICENSE 참조).
문서 및 학습 리소스
- 전체 문서 – https://developers.cloudflare.com/agents/ (시작하기, API 참조, 가이드).
- 예제 –
examples/아래 30개 이상의 데모(플레이그라운드, 채팅 어시스턴트, MCP, 음성 파이프라인, 워크플로, 결제, 게임 등). - 가이드 –
design/의 Anthropic 패턴, 인간-중심 워크플로, 설계 결정. - OpenAI SDK 예제 –
openai-sdk/는 OpenAI Agents JS SDK를 Cloudflare Agents와 함께 사용하는 방법을 보여줍니다.
누가 유지 관리하나요?
Cloudflare에서 개발했습니다. 이 저장소는 pnpm 워크스페이스와 Nx를 사용하여 빌드 및 테스트합니다. 현재 기여는 내부 기여자로 제한되지만, 이슈와 토론은 커뮤니티에 열려 있습니다.
라이선스
MIT (LICENSE 참조).
문서 및 학습 리소스
- 전체 문서 – https://developers.cloudflare.com/agents/ (시작하기, API 참조, 가이드).
- 예제 –
examples/아래 30개 이상의 데모(플레이그라운드, 채팅 어시스턴트, MCP, 음성 파이프라인, 워크플로, 결제, 게임 등). - 가이드 –
design/의 Anthropic 패턴, 인간-인-더-루프 워크플로, 설계 결정. - OpenAI SDK 예제 –
openai-sdk/는 OpenAI Agents JS SDK를 Cloudflare Agents와 함께 사용하는 방법을 보여줍니다.
누가 유지 관리하나요?
Cloudflare에서 개발했습니다. 이 저장소는 pnpm 워크스페이스와 Nx를 사용하여 빌드 및 테스트합니다. 현재 기여는 내부 기여자로 제한되지만, 이슈와 토론은 커뮤니티에 열려 있습니다.
라이선스
MIT (LICENSE 참조).
관련
- 프로젝트
- Dispatch
- 프로젝트
- 프로젝트
- 프로젝트