pimenov.ai
Поиск Граф

База знаний

Cloudflare Agents SDK — stateful AI-агенты на Durable Objects

Cloudflare Agents SDK — фреймворк для stateful AI-агентов поверх Durable Objects: каждый агент — отдельный «микросервер» с SQLite, WebSocket, планировщиком и hibernation. Разбираем, как устроено, когда брать, как собирается с OpenAI Agents SDK и MCP.

Опубликовано
AI-агентыBackendDevTools

Cloudflare в марте 2025-го выкатила Agents SDK — это не «ещё одна LLM-обёртка», а способ запускать агентов как «живых» stateful-исполнителей на Durable Objects: у каждого своя идентичность, память, SQLite, WebSocket-соединения и встроенный планировщик. Когда агент ничего не делает — он спит и ничего не стоит. Когда входит HTTP, WebSocket, e-mail или будильник — просыпается вместе со своим состоянием.

📌
Коротко: Cloudflare Agents SDK — TypeScript-класс Agent, который распаковывается в Durable Object. На каждого юзера, сессию или «игру » вы получаете свою персистентную инстанцию с идентичностью, SQLite-базой (до 10 GB) и hibernation. Отлично комбинируется с OpenAI Agents SDK и работает как remote MCP-сервер.

Зачем вообще специальный фреймворк

Средний LLM-API сервер — stateless. На каждый запрос вы вынуждены вытаскивать history из базы, склеивать, отправлять в модель, разбирать ответ, записывать обратно. Агенты добавляют ещё:

  • долгие размышляющие циклы (5–20 tool calls);
  • «пробуждение по расписанию» («в понедельник в 9:00 отправь сводку»);
  • реальное время через WebSocket или phone call;
  • human-in-the-loop с ожиданием подтверждения от пользователя.

На stateless serverless-коде всё это вылезает в «бухгалтерию»: очереди, внешние базы, блокировки, retry-логика. Cloudflare предлагает другой подход: actor model поверх Durable Objects.

Что такое Durable Object в двух словах

Durable Object — это «микросервер» в сети Cloudflare:

  • уникальный адрес по имени (один инстанс на «ключ», например user:42 или session:abc);
  • все запросы с тем же ключом попадают в один и тот же инстанс (single-writer);
  • своя SQLite-база до 10 GB, прямо внутри объекта;
  • WebSocket hibernation: соединение живёт, инстанс спит;
  • встроенный планировщик (alarms);
  • глобальный деплой, без собственной инфры.

Это «прям ответственный инстанс для каждой сессии». Agents SDK берёт эту примитивную модель и даёт сверху API для агентов.

Как выглядит агент

import { Agent } from "agents"

export class SupportAgent extends Agent<Env> {
	initialState = { messages: [] as Message[] }

	async onMessage(message: string) {
		const next = [...this.state.messages, { role: "user", text: message }]
		const reply = await this.env.AI.run("@cf/meta/llama-3.3-70b-instruct", {
			messages: next,
		})
		this.setState({ messages: [...next, { role: "assistant", text: reply.response }] })
		return reply.response
	}

	async onConnect(connection: Connection) {
		connection.send(JSON.stringify(this.state))
	}
}

Что важно:

  • Agent<Env> — базовый класс. Env — это биндинги Workers (KV, R2, AI, секреты).
  • state хранится в SQLite, но вы работаете с ним как с обычным JSON.
  • setState автоматически рассылает изменения WebSocket-клиентам.
  • Обработчики onMessage, onConnect, onRequest, onEmail — входы в агента.
  • Для вызова с клиента есть useAgent/AgentClient на React.

Ключевые возможности

Персистентное состояние без внешней базы

this.state — это ваша «оперативная» память, а SQLite внутри Durable Object — «долгая». Можно хранить историю диалога, кэш эмбеддингов, свои данные пользователя — всё в одном месте.

Schedule и alarms

Расписание «подумай через час», «проверяй папку раз в день», «отправь напоминание в пятницу» — встроено в SDK. Это заменяет отдельный cron-сервис или «выделенный воркер для реминдеров».

WebSocket и real-time UI

Клиент и агент живут на одном «проводе». Обновление состояния приходит в UI без polling. Hibernation делает long-lived соединения дешёвыми: вы платите только за работу, не за идл.

Email-вход

Агент может «просыпаться на письмо» через Cloudflare Email Routing. Удобно для «отправьте нам письмо — вы получите сформированный ответ»-флоу.

MCP-сервер из агента

Агент легко «выворачивается» наружу как remote MCP-сервер. Например, Knock используют Cloudflare Agents SDK как раз для remote MCP, который подключают клиенты из ChatGPT или Claude.

Workflows для длинных живых задач

Для long-running исследовательских агентов («сравни все GitHub-репо в теме X») Cloudflare предлагает Workflows — durable execution с retry, step.sleep, waitForEvent. Каждый LLM-вызов и tool call — индивидуальный checkpoint, падение не убивает всю задачу.

Как это собирается с OpenAI Agents SDK

Cloudflare прямо предлагает разделение ролей:

  • OpenAI Agents SDK отвечает за «мышление» — reasoning loop, выбор инструментов, планирование.
  • Cloudflare Agents SDK отвечает за «тело» — идентичность, память, runtime, расписание.

Вы пишете «реальные мысли агента» на OpenAI SDK, внутри метода onMessage вашего Cloudflare-агента. State и history берёте из this.state. Глухой абстракции над LLM при этом нет — можете взять любой другой фреймворк (Vercel AI SDK, LangGraph) или fetch вручную.

Когда брать

  • Да. Чаты с памятью на каждого клиента.
  • Да. Real-time коллаборация, multiplayer или «один инстанс на комнату».
  • Да. Агенты, которым нужны cron или «подумай через два часа».
  • Да. Remote MCP-сервер с hibernation и SQLite «из коробки».
  • Осторожно. Если ваш агент явно живёт в vendor-lock по данным (PostgreSQL в АВС, Redis в GCP и т.д.) — выигрыш от выноса state на Cloudflare будет меньше.
  • Нет. Одноразовые stateless «дерни один вызов LLM»-функции. Там это overkill: обычный Worker дешевле и проще.
⚠️
Vendor lock. Агенты SDK живут внутри Cloudflare. Перевезти логику «без боли» нельзя — SQLite, hibernation, alarms и actor-модель это инфраструктурная особенность этой платформы. Трезво оценивайте риск, если ваш продукт «агент внутри» — это важнее, чем «агент в углу».

Практические сценарии

Customer-success бот с памятью. Один агент на клиента. История переписки, предпочтения, текущие тикеты в SQLite. Отвечает в real time в веб-виджете и одновременно в e-mail.

Исследовательский агент. Запускается Workflows: выполняет 60+ вызовов, падает на 30-ом, поднимается с него же без «начали с нуля». Промежуточные результаты стримир в веб-UI.

Multi-agent system. Один Triage agent (router) раскидывает задачи по специализированным (Sales, Billing, Tech). Каждый — свой Durable Object с собственной памятью.

Phone-call агент. WebSocket от Twilio Media Streams прямо в Cloudflare-агент. Обработка аудио в потоке, фиксация результатов в SQLite.

«Один агент на AI-сгенерированное приложение.» Свежий Durable Object Facets (апрель 2026) позволяет изолированно хранить state каждого «под-приложения» в dynamic worker.

Старт за десять минут

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

Или в существующий проект:

npm install agents

Настройка wrangler.toml для Durable Object с SQLite:

[[durable_objects.bindings]]
name = "AGENT"
class_name = "SupportAgent"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["SupportAgent"]

Клиент на React:

import { useAgent } from "agents/react"

const agent = useAgent({ agent: "support-agent", name: "user:42" })
await agent.send({ type: "message", text: "Как отменить подписку?" })

Цена и лимиты

  • Hibernation. Idle Durable Object почти ничего не стоит. Платите за wall-time и память во время работы.
  • SQLite. До 10 GB на объект. Биллинг по операциям.
  • Скейл. Один Durable Object — до ~1000 RPS. Горизонтально масштабируете разбивкой на ключи (уже бив «один на юзера»).
  • AI-вызовы. Отдельно по Workers AI или вашему внешнему провайдеру.

Ссылки

По теме

Если вы выбираете рунтайм для своих агентов или думаете, стоит ли отдавать memory на Cloudflare — напишите в Telegram, разберём вместе.

Если хотите разобрать свою задачу — напишите мне

Можно прийти с идеей, черновым контекстом или уже живой задачей. Помогу быстро понять, где реальный следующий шаг, а где лишний шум.

Напишите мне в Телеграм Мой Телеграм канал

Обычно хватает 2–3 сообщений, чтобы понять, могу ли я здесь реально помочь и в каком формате лучше двигаться дальше.

Связанные материалы