Пошук

Як запустити Codex agent loop у Cloudflare Workers з Durable Objects

·

Cloudflare у changelog описує експериментальний приклад, де Codex agent loop запускається всередині Durable Object і користується можливостями Agents SDK для збереження стану. Такий підхід дозволяє агенту продовжити роботу після перезапусків, не втрачаючи контекст розмови, файли та результати попередніх викликів моделей і тулів.

1. Що саме запускається в Durable Object

У прикладі використовується Codex agent loop, адаптований до WebAssembly на основі Rust-коду обробки turn-ів. Цей цикл виконання бере на себе:

  • обробку кроків агента (model call, інструменти, файлові операції)
  • відновлення після переривань за даними зі сховищ Agents SDK
  • управління розмовою між користувачем, моделлю та тулінгом

Агент запускається всередині Cloudflare Durable Object. Це означає, що один екземпляр обробляє пов'язаний стан (розмову, workspace, історію завдань), а Agents SDK дає окремі «капабіліті» для різних типів стійкого зберігання.

2. Роль Tasks, Sessions, Streams і Workspace

Harness об'єднує кілька частин Agents SDK, кожна з яких відповідає за окрему сторону довготривалого виконання:

  • Tasks — журналює виклики моделі та виконання тулів. Після перезапуску:
    • вже завершені кроки не перераховуються, а беруться з журналу
    • перервані кроки можна запустити повторно
  • Sessions — зберігає історію розмови й відповідає за компактний контекст для моделі. Це потрібно, щоб не передавати модельній API всю історію підряд.
  • Streams — зберігає впорядковані події, які можна відтворити при перепідключенні клієнта. Корисно для стрімінгу відповідей і відновлення UI після розриву з'єднання.
  • Workspace — надає інструменти для читання та запису стійких файлів. Це файловий контекст агента, де можна тримати проміжні артефакти, скрипти тощо.

Таке розділення спрощує контроль за поведінкою агента після збоїв: код Codex harness покладається на те, що Tasks, Sessions, Streams і Workspace самі коректно відновлять потрібні дані.

3. Підключення моделі через AI Gateway та createAI

У прикладі використовується OpenAI GPT-6.1 Sol, доступний через Cloudflare AI Gateway. Для інтеграції моделі застосовується функція createAI з Agents SDK.

Схема така:

  1. AI Gateway налаштовується з gateway id default.
  2. У цьому gateway або вмикають Unified Billing, або зберігають OpenAI API key як bring your own key.
  3. У коді Durable Object викликається createAI({ binding: this.env.AI, id: "default" })("openai/gpt-6.1-sol"). Так з'являється об'єкт моделі, який можна передати в CodexHarness.

Ключовий момент: this.env.AI має відповідати binding-у AI Gateway у конфігурації Workers, а id: "default" — id потрібного gateway.

4. Як виглядає Durable Object з CodexHarness

Cloudflare показує приклад класу Durable Object, який поєднує всі капабіліті в одному агенті. У TypeScript-версії це виглядає так:

import { DurableObject } from "cloudflare:workers";
import { Workspace } from "@cloudflare/computer";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/ai-sdk";
import { Sessions } from "agents/sessions";
import { Streams } from "agents/streams";
import { Tasks } from "agents/tasks";
import { CodexHarness } from "./codex-harness";

export class Coder extends DurableObject<Env> {
	tasks = new Tasks();
	streams = new Streams();
	sessions = new Sessions();
	workspace = new Workspace({ storage: this.ctx.storage });

	codex = new CodexHarness({
		tasks: this.tasks,
		streams: this.streams,
		sessions: this.sessions,
		workspace: this.workspace,
		model: createAI({ binding: this.env.AI, id: "default" })("openai/gpt-6.1-sol"),
	});
	lifecycle = Lifecycle.install(this)
		.use(this.tasks)
		.use(this.streams)
		.use(this.sessions)
		.use(this.codex);
}

Суттєві деталі цього класу:

  • tasks, streams, sessions, workspace створюються як поля екземпляра.
  • workspace отримує storage з контексту Durable Object, щоб писати у стійке сховище об'єкта.
  • codex = new CodexHarness({...}) збирає всі капабіліті й модель в один harness, який реалізує agent loop.
  • lifecycle = Lifecycle.install(this).use(...) підключає Tasks, Streams, Sessions і Codex до життєвого циклу Durable Object, щоб обробляти запити та події через Agents SDK.

Є й варіант без явного generic-параметра <Env>, він майже ідентичний і відрізняється лише сигнатурою класу:

import { DurableObject } from "cloudflare:workers";
import { Workspace } from "@cloudflare/computer";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/ai-sdk";
import { Sessions } from "agents/sessions";
import { Streams } from "agents/streams";
import { Tasks } from "agents/tasks";
import { CodexHarness } from "./codex-harness";

export class Coder extends DurableObject {
	tasks = new Tasks();
	streams = new Streams();
	sessions = new Sessions();
	workspace = new Workspace({ storage: this.ctx.storage });

	codex = new CodexHarness({
		tasks: this.tasks,
		streams: this.streams,
		sessions: this.sessions,
		workspace: this.workspace,
		model: createAI({ binding: this.env.AI, id: "default" })(
			"openai/gpt-6.1-sol",
		),
	});
	lifecycle = Lifecycle.install(this)
		.use(this.tasks)
		.use(this.streams)
		.use(this.sessions)
		.use(this.codex);
}

У своїх проєктах варто дотримуватися того варіанту, який відповідає вашій типізації Env у Workers.

5. Що потрібно налаштувати перед запуском

Щоб приклад з Codex agent loop реально працював на Cloudflare Workers, з опису випливають такі обов'язкові кроки:

  • Налаштувати AI Gateway з id default, прив'язавши його як binding AI у конфігурації Workers.
  • У AI Gateway вибрати спосіб оплати:
    • або ввімкнути Unified Billing для OpenAI
    • або зберегти OpenAI API key як stored key для gateway
  • Підняти Durable Object-клас за зразком Coder і зареєструвати його у Workers (binding Durable Object до імені класу).
  • Підключити Codex harness та залежності з репозиторію прикладу: experimental Agents SDK example.

Детальніше про структуру моделей, налаштування тулів і варіанти відновлення після збоїв описано в офіційному Codex harness guide. Там же є додаткові вказівки щодо того, як налаштувати поведінку агента у власному середовищі.

6. Для чого такий підхід може бути корисним

З матеріалу випливає кілька практичних сценаріїв, де Codex harness на Durable Object спрощує роботу:

  • інструментальні агенти, які довго виконують задачі й залежать від файлового контексту (через Workspace)
  • асистенти, що підтримують тривалі розмови й мають зберігати узгоджену історію діалогу (Sessions)
  • UI додатки, де важливо після перепідключення відтворити хронологію подій (Streams)
  • workflows, яким потрібне надійне відновлення кроків після перезапуску (Tasks)

Авторський приклад не претендує на універсальне рішення для всіх сценаріїв, але демонструє, як комбінація Agents SDK та Durable Objects дозволяє винести agent loop в керовану, стійку до переривань інфраструктуру Cloudflare.

Джерело: Cloudflare Changelog

Пошук

Закрити