导航|地址|刷新
Callable methods

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Agents

/

Overview

Getting started

Quick start

Add to existing project

Testing your Agents

Concepts

What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows

Agentic patterns

Overview

Human-in-the-loop patterns

Long-running agents

Communication channels

Chat

Chat agents

Autonomous responses

Client SDK

Voice

Email

Slack

Webhooks

Overview

Push notifications

Tools

Sandbox

MCP

Browser

AI Search

Agentic Payments

Overview

Charge for HTTP content

x402

Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools

MPP (Machine Payments Protocol)

Code Mode

Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference

Harnesses

Overview

Think

Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery

Runtime

Agents API

Lifecycle

Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()

Communication

Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections

Execution

Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills

Operations

Configuration

Cross-domain authentication

Using AI Models

Observability

Examples

Chat agent

Slack agent

Voice agent

Browser agent

Email agent

Model Context Protocol (MCP)

Overview

APIs

MCP handler APIs

McpAgent

McpClient

Protocol

Tools

Authorization

Transport

MCP governance

Guides

Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server

Cloudflare

MCP server portals ↗

Cloudflare's own MCP servers

Overview

Cloudflare Community MCP Server

Code Mode MCP server patterns

Platform

Limits

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Agents

/…
Runtime

/Lifecycle

/Callable methods

Callable methods

Last updated Jun 3, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewOverview How it works When to use @callable()Basic usage Defining callable methods Calling from the clientMethod signatures Serializable types Async methods Void methodsStreaming responses Defining a streaming method Consuming streams on the client StreamingResponse APITypeScript integration Typed client calls Excluding non-callable methodsError handling Throwing errors in callable methods Client-side error handling Streaming error handling Connection errorsWhen NOT to use @callable Worker-to-Agent calls Agent-to-Agent calls Why the distinction?API reference @callable(metadata?) decorator CallableMetadata type StreamingResponse class Client methods CallOptions type getCallableMethods() methodTroubleshooting SyntaxError: Invalid or unexpected tokenNext steps

Callable methods let clients invoke agent methods over WebSocket using RPC (Remote Procedure Call). Mark methods with @callable() to expose them to external clients like browsers, mobile apps, or other services.

Overview

import { Agent, callable } from "agents";export class MyAgent extends Agent { @callable() async greet(name) { return `Hello, ${name}!`; }}

import { Agent, callable } from "agents";export class MyAgent extends Agent { @callable() async greet(name: string): Promise<string> { return `Hello, ${name}!`; }}

// Clientconst result = await agent.stub.greet("World");console.log(result); // "Hello, World!"

// Clientconst result = await agent.stub.greet("World");console.log(result); // "Hello, World!"

How it works

sequenceDiagram participant Client participant Agent Client->>Agent: agent.stub.greet("World") Note right of Agent: Check @callable<br/>Execute method Agent-->>Client: "Hello, World!"

When to use @callable()

Scenario Use
Browser/mobile calling agent @callable()
External service calling agent @callable()
Worker calling agent (same codebase) Durable Object RPC (no decorator needed)
Agent calling another agent Durable Object RPC via getAgentByName()

The @callable() decorator is specifically for WebSocket-based RPC from external clients. When calling from within the same Worker or another agent, use standard Durable Object RPC directly.

Basic usage

Defining callable methods

Add the @callable() decorator to any method you want to expose:

import { Agent, callable } from "agents";export class CounterAgent extends Agent { initialState = { count: 0, items: [] }; @callable() increment() { this.setState({ ...this.state, count: this.state.count + 1 }); return this.state.count; } @callable() decrement() { this.setState({ ...this.state, count: this.state.count - 1 }); return this.state.count; } @callable() async addItem(item) { this.setState({ ...this.state, items: [...this.state.items, item] }); return this.state.items; } @callable() getStats() { return { count: this.state.count, itemCount: this.state.items.length, }; }}

import { Agent, callable } from "agents";export type CounterState = { count: number; items: string[];};export class CounterAgent extends Agent<Env, CounterState> { initialState: CounterState = { count: 0, items: [] }; @callable() increment(): number { this.setState({ ...this.state, count: this.state.count + 1 }); return this.state.count; } @callable() decrement(): number { this.setState({ ...this.state, count: this.state.count - 1 }); return this.state.count; } @callable() async addItem(item: string): Promise<string[]> { this.setState({ ...this.state, items: [...this.state.items, item] }); return this.state.items; } @callable() getStats(): { count: number; itemCount: number } { return { count: this.state.count, itemCount: this.state.items.length, }; }}

Calling from the client

There are two ways to call methods from the client:

Using agent.stub (recommended):

// Clean, typed syntaxconst count = await agent.stub.increment();const items = await agent.stub.addItem("new item");const stats = await agent.stub.getStats();

// Clean, typed syntaxconst count = await agent.stub.increment();const items = await agent.stub.addItem("new item");const stats = await agent.stub.getStats();

Using agent.call():

// Explicit method name as stringconst count = await agent.call("increment");const items = await agent.call("addItem", ["new item"]);const stats = await agent.call("getStats");

// Explicit method name as stringconst count = await agent.call("increment");const items = await agent.call("addItem", ["new item"]);const stats = await agent.call("getStats");

The stub proxy provides better ergonomics and TypeScript support.

Method signatures

Serializable types

Arguments and return values must be JSON-serializable:

// Valid - primitives and plain objectsclass MyAgent extends Agent { @callable() processData(input) { return { result: true }; }}// Valid - arraysclass MyAgent extends Agent { @callable() processItems(items) { return items.map((item) => item.length); }}// Invalid - non-serializable types// Functions, Dates, Maps, Sets, etc. cannot be serialized

// Valid - primitives and plain objectsclass MyAgent extends Agent { @callable() processData(input: { name: string; count: number }): { result: boolean } { return { result: true }; }}// Valid - arraysclass MyAgent extends Agent { @callable() processItems(items: string[]): number[] { return items.map((item) => item.length); }}// Invalid - non-serializable types// Functions, Dates, Maps, Sets, etc. cannot be serialized

Async methods

Both sync and async methods work:

// Sync methodclass MyAgent extends Agent { @callable() add(a, b) { return a + b; }}// Async methodclass MyAgent extends Agent { @callable() async fetchUser(id) { const user = await this.sql`SELECT * FROM users WHERE id = ${id}`; return user[0]; }}

// Sync methodclass MyAgent extends Agent { @callable() add(a: number, b: number): number { return a + b; }}// Async methodclass MyAgent extends Agent { @callable() async fetchUser(id: string): Promise<User> { const user = await this.sql`SELECT * FROM users WHERE id = ${id}`; return user[0]; }}

Void methods

Methods that do not return a value:

class MyAgent extends Agent { @callable() async logEvent(event) { await this.sql`INSERT INTO events (name) VALUES (${event})`; }}

class MyAgent extends Agent { @callable() async logEvent(event: string): Promise<void> { await this.sql`INSERT INTO events (name) VALUES (${event})`; }}

On the client, these still return a Promise that resolves when the method completes:

await agent.stub.logEvent("user-clicked");// Resolves when the server confirms execution

await agent.stub.logEvent("user-clicked");// Resolves when the server confirms execution

Streaming responses

For methods that produce data over time (like AI text generation), use streaming:

Defining a streaming method

import { Agent, callable } from "agents";export class AIAgent extends Agent { @callable({ streaming: true }) async generateText(stream, prompt) { // First parameter is always StreamingResponse for streaming methods for await (const chunk of this.llm.stream(prompt)) { stream.send(chunk); // Send each chunk to the client } stream.end(); // Signal completion } @callable({ streaming: true }) async streamNumbers(stream, count) { for (let i = 0; i < count; i++) { stream.send(i); await new Promise((resolve) => setTimeout(resolve, 100)); } stream.end(count); // Optional final value }}

import { Agent, callable, type StreamingResponse } from "agents";export class AIAgent extends Agent { @callable({ streaming: true }) async generateText(stream: StreamingResponse, prompt: string) { // First parameter is always StreamingResponse for streaming methods for await (const chunk of this.llm.stream(prompt)) { stream.send(chunk); // Send each chunk to the client } stream.end(); // Signal completion } @callable({ streaming: true }) async streamNumbers(stream: StreamingResponse, count: number) { for (let i = 0; i < count; i++) { stream.send(i); await new Promise((resolve) => setTimeout(resolve, 100)); } stream.end(count); // Optional final value }}

Consuming streams on the client

// Preferred format (supports timeout and other options)await agent.call("generateText", [prompt], { stream: { onChunk: (chunk) => { // Called for each chunk appendToOutput(chunk); }, onDone: (finalValue) => { // Called when stream ends console.log("Stream complete", finalValue); }, onError: (error) => { // Called if an error occurs console.error("Stream error:", error); }, },});// Legacy format (still supported for backward compatibility)await agent.call("generateText", [prompt], { onChunk: (chunk) => appendToOutput(chunk), onDone: (finalValue) => console.log("Done", finalValue), onError: (error) => console.error("Error:", error),});

// Preferred format (supports timeout and other options)await agent.call("generateText", [prompt], { stream: { onChunk: (chunk) => { // Called for each chunk appendToOutput(chunk); }, onDone: (finalValue) => { // Called when stream ends console.log("Stream complete", finalValue); }, onError: (error) => { // Called if an error occurs console.error("Stream error:", error); }, },});// Legacy format (still supported for backward compatibility)await agent.call("generateText", [prompt], { onChunk: (chunk) => appendToOutput(chunk), onDone: (finalValue) => console.log("Done", finalValue), onError: (error) => console.error("Error:", error),});

StreamingResponse API

Method Description
send(chunk) Send a chunk to the client
end(finalChunk?) End the stream, optionally with a final value
error(message) Send an error to the client and close the stream

class MyAgent extends Agent { @callable({ streaming: true }) async processWithProgress(stream, items) { for (let i = 0; i < items.length; i++) { await this.process(items[i]); stream.send({ progress: (i + 1) / items.length, item: items[i] }); } stream.end({ completed: true, total: items.length }); }}

class MyAgent extends Agent { @callable({ streaming: true }) async processWithProgress(stream: StreamingResponse, items: string[]) { for (let i = 0; i < items.length; i++) { await this.process(items[i]); stream.send({ progress: (i + 1) / items.length, item: items[i] }); } stream.end({ completed: true, total: items.length }); }}

TypeScript integration

Typed client calls

Pass your agent class as a type parameter for full type safety:

import { useAgent } from "agents/react";function App() { const agent = useAgent({ agent: "MyAgent", name: "default", }); async function handleGreet() { // TypeScript knows the method signature const result = await agent.stub.greet("World"); // ^? string } // TypeScript catches errors // await agent.stub.greet(123); // Error: Argument of type 'number' is not assignable // await agent.stub.nonExistent(); // Error: Property 'nonExistent' does not exist}

import { useAgent } from "agents/react";import type { MyAgent } from "./server";function App() { const agent = useAgent<MyAgent>({ agent: "MyAgent", name: "default", }); async function handleGreet() { // TypeScript knows the method signature const result = await agent.stub.greet("World"); // ^? string } // TypeScript catches errors // await agent.stub.greet(123); // Error: Argument of type 'number' is not assignable // await agent.stub.nonExistent(); // Error: Property 'nonExistent' does not exist}

Excluding non-callable methods

If you have methods that are not decorated with
…(内容过长已截断)

------
导航页打开网址

Scenario	Use
Browser/mobile calling agent	@callable()
External service calling agent	@callable()
Worker calling agent (same codebase)	Durable Object RPC (no decorator needed)
Agent calling another agent	Durable Object RPC via getAgentByName()

Method	Description
send(chunk)	Send a chunk to the client
end(finalChunk?)	End the stream, optionally with a final value
error(message)	Send an error to the client and close the stream