building-ai-agent-on-cloudflare

Этот официальный skill предназначен для разработки AI-агентов на Cloudflare с использованием Agents SDK. Его задача — дать агенту проверяемый каркас для stateful-сервиса, который живёт не только в одном HTTP-запросе: экземпляр агента сохраняет состояние между запросами и переподключениями, принимает сообщения через WebSocket или HTTP, вызывает инструменты, планирует будущую работу и разворачивается на edge-инфраструктуре Cloudflare через Durable Objects. Источник отдельно предупреждает, что знания SDK быстро меняются, поэтому перед реализацией нужно обращаться к актуальной документации Agents SDK, Cloudflare Agents и Workers, а не полагаться только на предварительно известные примеры. Скилл подходит для нескольких близких задач: создания чат-агента, stateful AI-сервиса, real-time взаимодействия, WebSocket-коммуникации, фоновых и запланированных действий, tool calling и проектов, где нужно связать пользовательскую сессию с отдельным экземпляром агента. В качестве исходных условий он называет активированный Cloudflare Workers account, Node.js 18 или новее, npm, pnpm или yarn и установленный Wrangler CLI. Быстрый старт использует официальный шаблон cloudflare/agents-starter, после чего локальный процесс запускается через npm start и доступен на localhost:8787. Эти команды являются стартовой точкой; конфигурацию, секреты, лимиты и права окружения перед production-запуском нужно проверить отдельно. Основная модель кода строится вокруг класса, наследующего Agent<Env, State>. В State можно хранить историю сообщений, пользовательские предпочтения и другие данные, необходимые конкретному экземпляру. Метод onStart вызывается при запуске или восстановлении агента, onConnect отправляет подключившемуся клиенту приветствие и сохранённую историю, onMessage разбирает входное сообщение, а onClose фиксирует разрыв соединения. setState одновременно сохраняет новое состояние и синхронизирует его с подключёнными клиентами; источник также показывает вариант частичного обновления состояния. onStateUpdate позволяет отследить, какой источник инициировал изменение. Такой workflow полезен для диалога, в котором история и настройки должны переживать переподключение, но он не отменяет необходимость самостоятельно ограничивать размер состояния, проверять входной JSON и обрабатывать ошибки AI-вызова. Для маршрутизации используется routeAgentRequest: entry point принимает Request и Env, передаёт запрос роутеру Agents SDK, а при отсутствии подходящего маршрута возвращает ответ 404. В примере клиент подключается к адресу вида wss://my-agent.workers.dev/agents/MyAgent/session-id. Wrangler-конфигурация связывает имя Worker и src/index.ts с AI binding, Durable Object class и migration tag. В карточке важно различать эти части: один пример задаёт HTTP/WebSocket-маршрут, другой описывает привязки runtime, а сам skill не создаёт автоматически account, binding или production-политику. Для хранения более сложных данных источник показывает встроенное SQL-хранилище агента: таблица создаётся через this.sql, строки добавляются параметризованным INSERT, а поиск выполняется SELECT с параметром. Это подходит для документов и других структур, которым недостаточно простого объекта State. Для отложенной работы доступны schedule с задержкой в секундах, конкретной датой или cron-выражением, а также getSchedules и cancelSchedule. Обработчик запланированной задачи может отправить уведомление и обновить состояние. Такие примеры покрывают техническую механику, но бизнес-правила повторов, идемпотентность, авторизацию и контроль стоимости должны быть определены приложением. Для чат-сценариев skill предлагает AIChatAgent. Он автоматически ведёт историю сообщений, поддерживает возобновляемый streaming после отключения клиента и предоставляет saveMessages для сохранения. В базовом Agent-примере AI-вызов идёт через Workers AI binding, а в AIChatAgent-примере потоковый ответ возвращается клиенту. На стороне клиента показаны React-хук useAgent с agent, name, state, send и connected, а также минимальный vanilla JavaScript-клиент на WebSocket. Это полезные ориентиры для wiring, однако фактический формат сообщений, модель, схема Env и обработка ошибок должны совпадать с текущей версией SDK и документацией выбранного проекта. В разделе deployment приведены npx wrangler deploy, wrangler tail и curl-проверка endpoint. Поэтому skill можно использовать как маршрут от локального starter до Worker, но не как готовый security-аудит или гарантию production readiness. Сам источник направляет к отдельным материалам по tool calling, multi-agent orchestration, RAG, human-in-the-loop, state patterns и troubleshooting. Перед публикацией нужно прочитать соответствующие актуальные reference-файлы, проверить права доступа к WebSocket и HTTP, валидацию входных данных, секреты, Durable Objects migrations, наблюдаемость, квоты и поведение при повторном подключении. Для визуального качества chat UI, корректности пользовательского сценария и нагрузочных характеристик нужны отдельные тесты: описанный workflow их автоматически не выполняет.