KuralleAgent

Abstract base class for running Kuralle agents on Cloudflare.

Example

import { KuralleAgent } from '@kuralle-agents/cf-agent';
import { openai } from '@ai-sdk/openai';

class MyAgent extends KuralleAgent<Env> {
  protected getAgents(): HarnessConfig['agents'] {
    return [{
      id: 'assistant',
      name: 'Assistant',
      model: openai('gpt-4o', { apiKey: this.env.OPENAI_API_KEY }),
      instructions: 'You are a helpful assistant.',
    }];
  }

  protected getDefaultAgentId() { return 'assistant'; }
}

Extends

• AIChatAgent<Env, State>

Extended by

• KuralleThreadAgent

Type Parameters

Type Parameter	Default type
Env	unknown
State	unknown

Constructors

Constructor

new KuralleAgent<Env, State>(ctx, env): KuralleAgent<Env, State>;

Parameters

Parameter	Type
ctx	DurableObjectState
env	Env

Returns

KuralleAgent<Env, State>

Inherited from

AIChatAgent<Env, State>.constructor

Methods

onChatMessage()

onChatMessage(onFinish, options?): Promise<Response>;

Called by CF when a chat message arrives.

CF has already:

1. Received the WebSocket message from the client
2. Parsed and validated it
3. Persisted the user message to cf_ai_chat_agent_messages
4. Populated this.messages with the full conversation history

We:

1. Create a BridgeSessionStore (CF messages + orchestration state)
2. Build and run Kuralle Runtime
3. Return an SSE Response

CF then:

1. Reads the SSE stream via _reply()
2. Builds assistant message parts via applyChunkToParts()
3. Persists the assistant message
4. Broadcasts to all connected clients
5. Handles stream resumability

Parameters

Parameter	Type
onFinish	GenerateTextOnFinishCallback<ToolSet>
options?	OnChatMessageOptions

Returns

Promise<Response>

Overrides

AIChatAgent.onChatMessage

---

onRequest()

onRequest(request): Promise<Response>;

HTTP endpoint handler. Adds Kuralle-specific endpoints on top of CF’s defaults.

Parameters

Parameter	Type
request	Request

Returns

Promise<Response>

Overrides

AIChatAgent.onRequest

---

runScheduledKuralleJob()

runScheduledKuralleJob(job): Promise<void>;

DO-alarm callback for scheduled jobs. Wake jobs run an agent-initiated turn and persist + broadcast the assistant reply through CF’s machinery (same path as resumeWithSignal); other job kinds go to onScheduledJob for subclasses to handle.

Parameters

Parameter	Type
job	ScheduledJob

Returns

Promise<void>