Migrating to Simplified Cloudflare FrontendHandler

Overview

The Cloudflare DO integration has been simplified. Just pass your DO namespace and agent name - the handler creates all necessary clients internally.

Breaking Changes

1. DOClient removed - The HTTP-based DOClient and related adapters have been deleted
2. Simple namespace API - Just pass namespace and agentName instead of creating clients
3. Same-worker requirement - FrontendHandler must be in the same Worker as AgentServer DO

Migration Guide

Before (v0.14 and earlier)

import { createFrontendHandler } from '@helix-agents/ai-sdk';
import { DOClient } from '@helix-agents/ai-sdk/cloudflare';

const stub = getDOStub(sessionId);

const client = new DOClient({
  baseUrl: 'https://do',
  fetch: (url, init) => stub.fetch(url, init),
  routePattern: () => '',
});

const handler = createFrontendHandler({
  client,
  agentName: 'chat-agent',
});

After (v0.15+)

import { createFrontendHandler } from '@helix-agents/ai-sdk';

const handler = createFrontendHandler({
  namespace: env.AGENTS,
  agentName: 'chat-agent',
});

That's it! No need to import or instantiate any DO clients.

Advanced Usage

If you need direct access to the DO clients for custom scenarios, they're still available from @helix-agents/ai-sdk/cloudflare:

import {
  DOFrontendExecutor,
  DOStateStoreClient,
  DOStreamManagerClient,
} from '@helix-agents/ai-sdk/cloudflare';

// Or from runtime-cloudflare directly
import {
  DOFrontendExecutor,
  DOStateStoreClient,
  DOStreamManagerClient,
} from '@helix-agents/runtime-cloudflare/do-clients';

Custom FrontendHandler Setup

import { createFrontendHandler } from '@helix-agents/ai-sdk';
import {
  DOFrontendExecutor,
  DOStateStoreClient,
  DOStreamManagerClient,
} from '@helix-agents/ai-sdk/cloudflare';

const executor = new DOFrontendExecutor({
  namespace: env.AGENTS,
  agentName: 'chat-agent',
});

const stateStore = new DOStateStoreClient({ namespace: env.AGENTS });
const streamManager = new DOStreamManagerClient({ namespace: env.AGENTS });

const handler = createFrontendHandler({
  executor,
  stateStore,
  streamManager,
  agent: MyAgent,
});

Cross-Worker Scenarios

The simplified API requires the FrontendHandler to be in the same Worker as the AgentServer Durable Object. If you need cross-worker HTTP communication (e.g., separate frontend and backend workers), you'll need to implement your own HTTP client that calls the DO endpoints.

Removed Components

The following HTTP-based components have been removed:

• DOClient - HTTP client for cross-worker DO communication
• DOStreamAdapter - SSE stream transformation for HTTP responses
• DORequestHandler - High-level HTTP route handler

These were removed because the recommended pattern is to deploy the FrontendHandler in the same Worker as the AgentServer DO, which is simpler and more efficient.

Type Changes

Old Type	New Type
FrontendHandlerDOOptions	Removed
FrontendHandlerNamespaceOptions	FrontendHandlerCloudflareOptions
isNamespaceOptions()	isCloudflareOptions()
isDOOptions()	Removed

FAQ

Why was DOClient removed?

DOClient was designed for scenarios where the FrontendHandler ran in a different Cloudflare Worker than the AgentServer DO. This added HTTP overhead and complexity. The recommended pattern is to deploy FrontendHandler in the same Worker as the DO, which is simpler and more efficient.

Can I still access DOs from a different Worker?

Yes, but you'll need to implement your own HTTP client. The built-in handler requires the same-worker pattern for efficient stub access.