← Создание агентов на Cloudflare / agents / examples
Голосовой агент
Создайте голосового агента, который слушает пользователей, думает с помощью LLM и отвечает голосом: всё это в реальном времени через WebSocket. Бета
К концу этого руководства у вас будет:
- Серверный голосовой агент с распознаванием речи и синтезом речи
- На основе LLM
onTurnобработчик, который передаёт ответы потоково - Инструменты, которые агент может вызывать во время беседы
- React-клиент с интерфейсом в стиле push-to-talk
Предварительные требования
- Аккаунт Cloudflare с Workers AI доступ
- Node.js 18+
1. Создайте проект
Создайте новый проект Workers с помощью Vite и React, а затем добавьте зависимости для голоса:
npm create cloudflare@latest voice-agent -- --template cloudflare/agents-starter
cd voice-agent
npm install @cloudflare/voiceСтартовый шаблон даёт вам рабочую настройку Vite + React + Cloudflare Workers. В следующих шагах вы замените серверный и клиентский код.
2. Настройте wrangler
Обновите wrangler.jsonc чтобы включить привязку Workers AI и Durable Object для вашего голосового агента:
{
"name": "voice-agent",
// Set this to today's date
"compatibility_date": "2026-08-28",
"compatibility_flags": ["nodejs_compat"],
"main": "src/server.ts",
"ai": {
"binding": "AI"
},
"durable_objects": {
"bindings": [
{
"name": "MyVoiceAgent",
"class_name": "MyVoiceAgent"
}
]
},
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": ["MyVoiceAgent"]
}
]
}name = "voice-agent"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]
main = "src/server.ts"
[ai]
binding = "AI"
[[durable_objects.bindings]]
name = "MyVoiceAgent"
class_name = "MyVoiceAgent"
[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyVoiceAgent" ]3. Соберите сервер
Замените src/server.ts со следующим. withVoice миксин добавляет полный голосовой конвейер: STT, сегментация по предложениям, TTS и сохранение диалога, к стандартному Agent в качестве класса.
import { Agent, routeAgentRequest } from "agents";
import { withVoice, WorkersAIFluxSTT, WorkersAITTS } from "@cloudflare/voice";
import { streamText, tool, stepCountIs } from "ai";
import { createWorkersAI } from "workers-ai-provider";
import { z } from "zod";
const VoiceAgent = withVoice(Agent);
export class MyVoiceAgent 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 — you are being spoken aloud.",
messages: [
...context.messages.map((m) => ({
role: m.role,
content: m.content,
})),
{ role: "user", content: transcript },
],
tools: {
get_current_time: tool({
description: "Get the current date and time.",
inputSchema: z.object({}),
execute: async () => ({
time: new Date().toLocaleTimeString("en-US", {
hour: "2-digit",
minute: "2-digit",
}),
}),
}),
},
stopWhen: stepCountIs(3),
abortSignal: context.signal,
});
return result.textStream;
}
async onCallStart(connection) {
await this.speak(connection, "Hi there! How can I help you today?");
}
}
export default {
async fetch(request, env) {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
},
};import { Agent, routeAgentRequest, type Connection } from "agents";
import {
withVoice,
WorkersAIFluxSTT,
WorkersAITTS,
type VoiceTurnContext,
} from "@cloudflare/voice";
import { streamText, tool, stepCountIs } from "ai";
import { createWorkersAI } from "workers-ai-provider";
import { z } from "zod";
const VoiceAgent = withVoice(Agent);
export class MyVoiceAgent 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 — you are being spoken aloud.",
messages: [
...context.messages.map((m) => ({
role: m.role as "user" | "assistant",
content: m.content,
})),
{ role: "user" as const, content: transcript },
],
tools: {
get_current_time: tool({
description: "Get the current date and time.",
inputSchema: z.object({}),
execute: async () => ({
time: new Date().toLocaleTimeString("en-US", {
hour: "2-digit",
minute: "2-digit",
}),
}),
}),
},
stopWhen: stepCountIs(3),
abortSignal: context.signal,
});
return result.textStream;
}
async onCallStart(connection: Connection) {
await this.speak(connection, "Hi there! How can I help you today?");
}
}
export default {
async fetch(request: Request, env: Env) {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
},
} satisfies ExportedHandler<Env>;Основные моменты:
WorkersAIFluxSTTобеспечивает непрерывное преобразование речи в текст: модель определяет, когда пользователь закончил говорить.WorkersAITTSпреобразует ответ LLM в аудио, предложение за предложением.onTurnполучает транскрипт и возвращает поток. Mixin разбивает поток на чанки по предложениям и синтезирует каждое из них.onCallStartотправляет приветствие при подключении пользователя.context.messagesсодержит полную историю разговора из SQLite.context.signalпрерывается, если пользователь прерывает выполнение или отключается.
4. Создайте клиент
Замените src/client.tsx с React-компонентом с использованием useVoiceAgent хук. Этот хук управляет подключением WebSocket, захватом микрофона, воспроизведением звука и обнаружением прерываний.
import { useVoiceAgent } from "@cloudflare/voice/react";
function App() {
const {
status,
transcript,
interimTranscript,
metrics,
audioLevel,
isMuted,
startCall,
endCall,
toggleMute,
} = useVoiceAgent({ agent: "MyVoiceAgent" });
return (
<div>
<h1>Voice Agent</h1>
<p>Status: {status}</p>
<div>
<button onClick={status === "idle" ? startCall : endCall}>
{status === "idle" ? "Start Call" : "End Call"}
</button>
{status !== "idle" && (
<button onClick={toggleMute}>{isMuted ? "Unmute" : "Mute"}</button>
)}
</div>
{interimTranscript && (
<p>
<em>{interimTranscript}</em>
</p>
)}
{transcript.map((msg, i) => (
<p key={i}>
<strong>{msg.role}:</strong> {msg.text}
</p>
))}
{metrics && (
<p>
LLM: {metrics.llm_ms}ms | TTS: {metrics.tts_ms}ms | First audio:{" "}
{metrics.first_audio_ms}ms
</p>
)}
</div>
);
} status поле циклически перебирает "idle" → "listening" → "thinking" → "speaking" → "listening", предоставляя всё необходимое для создания отзывчивого UI.
5. Запустите
npm run devОткройте приложение в браузере, выберите Начать вызов, и говорите. Транскрипт будет появляться в реальном времени, а ответ агента прозвучит через ваши динамики.
Добавление хуков конвейера
Вы можете перехватывать и преобразовывать данные на каждом этапе конвейера. Например, отфильтровать короткие транскрипты (шум) и скорректировать произношение перед TTS:
export class MyVoiceAgent 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 "You said: " + transcript;
}
}export class MyVoiceAgent 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 "You said: " + transcript;
}
}Возврат null от afterTranscribe полностью отбрасывает высказывание: это полезно для отсеивания шума или очень коротких транскриптов.
Использование сторонних провайдеров
Подключайте сторонние провайдеры STT или TTS, не меняя логику агента:
import { ElevenLabsTTS } from "@cloudflare/voice-elevenlabs";
import { DeepgramSTT } from "@cloudflare/voice-deepgram";
export class MyVoiceAgent extends VoiceAgent {
transcriber = new DeepgramSTT({
apiKey: this.env.DEEPGRAM_API_KEY,
});
tts = new ElevenLabsTTS({
apiKey: this.env.ELEVENLABS_API_KEY,
voiceId: "21m00Tcm4TlvDq8ikWAM",
});
async onTurn(transcript, context) {
return "You said: " + transcript;
}
}import { ElevenLabsTTS } from "@cloudflare/voice-elevenlabs";
import { DeepgramSTT } from "@cloudflare/voice-deepgram";
export class MyVoiceAgent extends VoiceAgent<Env> {
transcriber = new DeepgramSTT({
apiKey: this.env.DEEPGRAM_API_KEY,
});
tts = new ElevenLabsTTS({
apiKey: this.env.ELEVENLABS_API_KEY,
voiceId: "21m00Tcm4TlvDq8ikWAM",
});
async onTurn(transcript: string, context: VoiceTurnContext) {
return "You said: " + transcript;
}
}