导航|地址|刷新
Voice
图
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.



DocsDirectoryAPISDKsChangelog

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

/Communication channels

/Voice



Voice


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

OverviewOverviewQuick start Install Server Client (React) Wrangler configurationHow it worksServer API: withVoice Providers onTurn(transcript, context) Lifecycle hooks Pipeline hooks Convenience methods Configuration optionsServer API: withVoiceInput onTranscript(text, connection) HooksClient API: React hooks useVoiceAgent useVoiceInputClient API: VoiceClient Events Advanced optionsProviders Built-in (Workers AI) Third-party providersTelephony (Twilio)Text messagesCustom messagesSingle-speaker enforcementPipeline metricsConversation history




Build real-time voice agents with speech-to-text, text-to-speech, and conversation persistence. Audio streams over WebSocket — no SFU or meeting infrastructure required. Beta


Overview


@cloudflare/voice provides two server-side mixins and matching client libraries:


ExportImportPurpose
withVoice@cloudflare/voiceFull voice agent: STT, LLM, TTS, persistence
withVoiceInput@cloudflare/voiceSTT-only: transcription without response
useVoiceAgent@cloudflare/voice/reactReact hook for withVoice agents
useVoiceInput@cloudflare/voice/reactReact hook for withVoiceInput agents
VoiceClient@cloudflare/voice/clientFramework-agnostic client



Built on Cloudflare Durable Objects, you get:

Real-time audio — mic audio streams as binary WebSocket frames, TTS audio streams back

Automatic conversation persistence — messages stored in SQLite, survive restarts

Streaming TTS — LLM tokens are sentence-chunked and synthesized concurrently

Interruption handling — user speech during playback cancels the current response

Continuous STT — per-call transcriber session, model handles turn detection

Pipeline hooks — intercept and transform text at every stage


Quick start



Install

npm install @cloudflare/voice agents

Server







import { Agent } from "agents";import { withVoice, WorkersAIFluxSTT, WorkersAITTS } from "@cloudflare/voice";const VoiceAgent = withVoice(Agent);export class MyAgent extends VoiceAgent { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript, context) { return "Hello! I heard you say: " + transcript; }}

import { Agent } from "agents";import { withVoice, WorkersAIFluxSTT, WorkersAITTS, type VoiceTurnContext,} from "@cloudflare/voice";const VoiceAgent = withVoice(Agent);export class MyAgent extends VoiceAgent<Env> { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript: string, context: VoiceTurnContext) { return "Hello! I heard you say: " + transcript; }}





Client (React)

import { useVoiceAgent } from "@cloudflare/voice/react";function VoiceUI() { const { status, transcript, interimTranscript, audioLevel, isMuted, startCall, endCall, toggleMute, } = useVoiceAgent({ agent: "MyAgent" }); return ( <div> <p>Status: {status}</p> <button onClick={status === "idle" ? startCall : endCall}> {status === "idle" ? "Start Call" : "End Call"} </button> <button onClick={toggleMute}>{isMuted ? "Unmute" : "Mute"}</button> {interimTranscript && ( <p> <em>{interimTranscript}</em> </p> )} {transcript.map((msg, i) => ( <p key={i}> <strong>{msg.role}:</strong> {msg.text} </p> ))} </div> );}

Wrangler configuration






{ "ai": { "binding": "AI" }, "durable_objects": { "bindings": [ { "name": "MyAgent", "class_name": "MyAgent" } ] }, "migrations": [ { "tag": "v1", "new_sqlite_classes": ["MyAgent"] } ]}

[ai]binding = "AI"[[durable_objects.bindings]]name = "MyAgent"class_name = "MyAgent"[[migrations]]tag = "v1"new_sqlite_classes = [ "MyAgent" ]




How it works

Browser Durable Object (withVoice)┌──────────┐ ┌──────────────────────────┐│ Mic │ binary PCM (16kHz) │ Transcriber session ││ │ ──────────────────────► │ (per-call, continuous) ││ │ │ ↓ model detects turn ││ │ JSON: transcript │ onTurn() → your LLM code ││ │ ◄────────────────────── │ ↓ (sentence chunking) ││ │ binary: audio │ TTS ││ Speaker │ ◄────────────────────── │ │└──────────┘ └──────────────────────────┘
The client captures mic audio and sends it as binary WebSocket frames (16kHz mono 16-bit PCM).

Audio streams continuously to the transcriber session (created at start_call, lives for the entire call).

The STT model detects when the user finishes an utterance and fires onUtterance. All providers use model-driven turn detection — the client does not need to signal end-of-speech for STT.

Your onTurn() method runs — typically an LLM call.

The response is sentence-chunked and synthesized via TTS.

Audio streams back to the client for playback.

The client receives transcript_interim messages with partial results as the user speaks, so you can show real-time feedback in the UI.


Server API: withVoice


withVoice(Agent) adds the full voice pipeline to an Agent class.


Providers


Set providers as class properties. Class field initializers run after super(), so this.env is available.


PropertyTypeRequiredDescription
transcriberTranscriberYesContinuous per-call STT provider
ttsTTSProviderYesText-to-speech








import { withVoice, WorkersAIFluxSTT, WorkersAITTS } from "@cloudflare/voice";const VoiceAgent = withVoice(Agent);export class MyAgent extends VoiceAgent { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI);}

import { withVoice, WorkersAIFluxSTT, WorkersAITTS } from "@cloudflare/voice";const VoiceAgent = withVoice(Agent);export class MyAgent extends VoiceAgent<Env> { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI);}




For runtime model switching (for example, a Flux vs Nova 3 dropdown), override createTranscriber:






export class MyAgent extends VoiceAgent { tts = new WorkersAITTS(this.env.AI); createTranscriber(connection) { return new WorkersAIFluxSTT(this.env.AI); }}

export class MyAgent extends VoiceAgent<Env> { tts = new WorkersAITTS(this.env.AI); createTranscriber(connection: Connection): Transcriber { return new WorkersAIFluxSTT(this.env.AI); }}





onTurn(transcript, context)


Required. Called when the user finishes speaking and the transcript is ready.

Return a string, AsyncIterable<string>, or ReadableStream for streaming responses.

Simple response:






export class MyAgent extends VoiceAgent { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript, context) { return "You said: " + transcript; }}

export class MyAgent extends VoiceAgent<Env> { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript: string, context: VoiceTurnContext) { return "You said: " + transcript; }}




Streaming response (recommended for LLM):






import { streamText } from "ai";import { createWorkersAI } from "workers-ai-provider";export class MyAgent extends VoiceAgent { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript, context) { const workersai = createWorkersAI({ binding: this.env.AI }); const result = streamText({ model: workersai("@cf/moonshotai/kimi-k2.6"), system: "You are a helpful voice assistant. Keep responses concise.", messages: [ ...context.messages.map((m) => ({ role: m.role, content: m.content, })), { role: "user", content: transcript }, ], abortSignal: context.signal, }); return result.textStream; }}

import { streamText } from "ai";import { createWorkersAI } from "workers-ai-provider";export class MyAgent extends VoiceAgent<Env> { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript: string, context: VoiceTurnContext) { const workersai = createWorkersAI({ binding: this.env.AI }); const result = streamText({ model: workersai("@cf/moonshotai/kimi-k2.6"), system: "You are a helpful voice assistant. Keep responses concise.", messages: [ ...context.messages.map((m) => ({ role: m.role as "user" | "assistant", content: m.content, })), { role: "user", content: transcript }, ], abortSignal: context.signal, }); return result.textStream; }}




The context object provides:


FieldTypeDescription
connectionConnectionThe WebSocket connection
messagesArray<{ role: string; content: string }>Conversation history from SQLite
signalAbortSignalAborted on interrupt or disconnect




Lifecycle hooks



MethodDescription
beforeCallStart(connection)Return false to reject the call
onCallStart(connection)Called after a call is accepted
onCallEnd(connection)Called when a call ends
onInterrupt(connection)Called when user interrupts during playback




Pipeline hooks


Intercept and transform data at each pipeline stage. Return null to skip the current utterance.


MethodReceivesCan skip?
afterTranscribe(transcript, connection)STT textYes
beforeSynthesize(text, connection)Text before TTSYes
afterSynthesize(audio, text, connection)Audio after TTSYes








import {} from "agents";export class MyAgent extends VoiceAgent { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); afterTranscribe(transcript, connection) { if (transcript.length < 3) return null; return transcript; } beforeSynthesize(text, connection) { return text.replace(/\bAI\b/g, "A.I."); } async onTurn(transcript, context) { return transcript; }}

import { type Connection } from "agents";export class MyAgent extends VoiceAgent<Env> { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); afterTranscribe(transcript: string, connection: Connection) { if (transcript.length < 3) return null; return transcript; } beforeSynthesize(text: string, connection: Connection) { return text.replace(/\bAI\b/g, "A.I."); } async onTurn(transcript: string, context: VoiceTurnContext) { return transcript; }}





Convenience methods



MethodDescription
speak(connection, text)Synthesize and send audio to one connection
speakAll(text)Synthesize and send audio to all connections
forceEndCall(connection)Programmatically end a call
saveMessage(role, text)Persist a message to conversation history
getConversationHistory()Retrieve conversation history from SQLite




Configuration options


Pass options to withVoice() as the second argument:






const VoiceAgent = withVoice(Agent, { historyLimit: 20, audioFormat: "mp3", maxMessageCount: 1000,});

const VoiceAgent = withVoice(Agent, { historyLimit: 20, audioFormat: "mp3", maxMessageCount: 1000,});





OptionTypeDefaultDescription
historyLimitnumber20Max messages loaded for context
audioFormatstring"mp3"
…(内容过长已截断)

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