Agent 是由你的后端通过 WebSocket 控制的会议参与者。若要添加 Agent,请配置预设,将 Agent 作为参与者添加,然后使用该参与者令牌连接到 WebSocket 端点。
请决定会议参与者是否应该看到 Agent。本页介绍的两种模式都采用相同的步骤并接收相同事件,区别仅在于预设。
| 模式 | 预设 | 用途 |
|---|---|---|
| 隐藏 Agent | hidden_participant: true |
合规监控、实时分析 |
| 可见 Agent | hidden_participant: false |
参与者在会议中可以看到的会议记录机器人 |
如果不希望参与者看到 Agent,请使用隐藏 Agent。例如,可借此监控合规性、审核通话质量或收集实时会议分析数据。
- 参与者看不到。 RealtimeKit SDK 会从参与者列表和视频网格中过滤掉该 Agent。
- 仍会发送加入和离开事件。 每个已连接到会议的客户端都会收到这些事件,但 SDK 不会显示它们。不要依赖
hidden_participant对检查自己客户端的参与者保密。 - 事件和计费相同。 隐藏 Agent 会接收其订阅的所有事件,会按参与者计费,并且连接期间会使会话保持活动状态。
- 系统不会自动移除 Agent。 参与者看不到该 Agent,因此你的后端必须结束它。
- 是否披露由你决定。 隐藏 Agent 不会隐藏会议正在转录这一事实。如果你的政策要求,请告知参与者。
如果希望参与者知道 Agent 已加入,请使用可见 Agent。例如,名为“会议记录机器人”的 Agent 加入后即可开始记录。
- 以名称显示。 你在将 Agent 添加为参与者时传入的
name就是参与者看到的名称。 - 在网格中占据一个格子。 即使 Agent 不发送音频或视频,也会显示在视频网格中。如果你使用自定义 Core SDK 网格,可按
participant.presetName将其过滤掉。 - 加入后才开始。 Agent 加入前说的话不会被捕获。若要捕获整个会话,请在会议开始前添加 Agent。
- 一个 RealtimeKit 应用和会议。请参阅快速入门。
- 一个具有 RealtimeKit 访问权限的 Cloudflare API 令牌。
- 若要接收实时转录,请在需要转录的参与者预设中启用实时转录。否则 Agent 不会收到
transcript.received事件。
与其他参与者一样,Agent 使用预设加入会议。你可以使用现有预设,但专用的 Agent 预设能将 Agent 设置与人类参与者的设置分开。请在 RealtimeKit 控制面板 ↗中创建预设,或使用创建预设 API。
若要对其他参与者隐藏 Agent,请使用更新预设 API设置 hidden_participant:
Required API token permissions
At least one of the following token permissions is required:Realtime AdminRealtime
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/realtime/kit/$APP_ID/presets/$PRESET_ID" \
--request PATCH \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"permissions": {
"hidden_participant": true
}
}'hidden_participant 只会改变其他参与者看到的内容。无论如何设置,Agent 收到的事件都相同。有关其他参与者看到的隐藏 Agent,请参阅隐藏 Agent。
如果尚无会议,请使用创建会议 API创建会议:
Required API token permissions
At least one of the following token permissions is required:Realtime AdminRealtime
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/realtime/kit/$APP_ID/meetings" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"title": "Weekly product review"
}'响应中的 data.id 是会议 ID。在下一个请求中将其用作 $MEETING_ID。
然后,使用 Agent 预设通过添加参与者将 Agent 添加到会议:
Required API token permissions
At least one of the following token permissions is required:Realtime AdminRealtime
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/realtime/kit/$APP_ID/meetings/$MEETING_ID/participants" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"name": "Notes bot",
"preset_name": "agent",
"custom_participant_id": "notes-bot"
}'响应中的 data.token 是 Agent 的参与者令牌。会议的每次会话都重复使用同一参与者。参与者令牌默认有效期为 100 天。
使用参与者令牌和 realtimekit.v1 子协议连接到端点:
GET wss://api.realtime.cloudflare.com/agent-ws/v1?subscriptions=transcript,participant,broadcast
Authorization: Bearer <PARTICIPANT_TOKEN>
Sec-WebSocket-Protocol: realtimekit.v1令牌会指定会议。HTTP 101 表示连接已就绪。随后 Agent 会加入会议并发送 session.started。
| 参数 | 值 |
|---|---|
subscriptions |
可选。可以是 transcript、participant、broadcast 中的任意项,以逗号分隔。 |
connection_id |
可选。恢复先前的连接。请参阅重新连接。 |
subscriptions 决定 Agent 会收到哪些事件。始终会发送会话事件。
| 类别 | 事件 | 需要 |
|---|---|---|
transcript |
transcript.received |
发言者的预设中已启用实时转录。 |
participant |
participant.join, participant.leave |
无 |
broadcast |
broadcast.received |
你的应用发送广播。 |
请只订阅你会用到的事件。事件越少,重连期间需要排队的事件就越少。有关载荷和传递规则,请参阅事件。
此示例将步骤 1 到 4 组合起来。Worker 会将 Agent 添加到会议中,Durable Object 则持有 Agent 的 WebSocket,并记录最终转录内容和参与者加入事件。
Durable Object 适合运行 Agent:每个会议对应一个实例,支持长时间运行的出站 WebSocket,并可存储用于恢复连接的 connection_id。
-
配置 Worker。 绑定 Durable Object 并设置应用详细信息:
{ "name": "meeting-agent", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-11-14", "vars": { "ACCOUNT_ID": "<ACCOUNT_ID>", "APP_ID": "<APP_ID>", "AGENT_PRESET": "agent", }, "durable_objects": { "bindings": [{ "name": "MEETING_AGENT", "class_name": "MeetingAgent" }], }, "exports": { "MeetingAgent": { "type": "durable-object", "storage": "sqlite", }, }, }name = "meeting-agent" main = "src/index.ts" # Set this to today's date compatibility_date = "2026-11-14" [vars] ACCOUNT_ID = "<ACCOUNT_ID>" APP_ID = "<APP_ID>" AGENT_PRESET = "agent" [[durable_objects.bindings]] name = "MEETING_AGENT" class_name = "MeetingAgent" [exports.MeetingAgent] type = "durable-object" storage = "sqlite"将 API 令牌存储为机密:
npx wrangler secret put CLOUDFLARE_API_TOKENyarn wrangler secret put CLOUDFLARE_API_TOKENpnpm wrangler secret put CLOUDFLARE_API_TOKEN -
添加和移除 Agent。
POST会使用 Agent 预设添加参与者,并启动会议的 Durable Object。DELETE会从会议中移除 Agent:src/index.jsjs export { MeetingAgent } from "./agent"; export default { async fetch(request, env) { const url = new URL(request.url); const match = url.pathname.match(/^\/meetings\/([^/]+)\/agent$/); if (!match) return new Response("Not found", { status: 404 }); const meetingId = match[1]; const agent = env.MEETING_AGENT.getByName(meetingId); // Authenticate the caller before adding or removing an agent. if (request.method === "DELETE") { await agent.stop(); return new Response("Agent stopped", { status: 200 }); } if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); } const res = await fetch( `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/realtime/kit/${env.APP_ID}/meetings/${meetingId}/participants`, { method: "POST", headers: { Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Notes bot", preset_name: env.AGENT_PRESET, custom_participant_id: `agent-${meetingId}`, }), }, ); if (!res.ok) return new Response("Add participant failed", { status: 502 }); const { data } = await res.json(); await agent.start(data.token); return new Response("Agent started", { status: 202 }); }, };src/index.tsts export { MeetingAgent } from "./agent"; export default { async fetch(request, env): Promise<Response> { const url = new URL(request.url); const match = url.pathname.match(/^\/meetings\/([^/]+)\/agent$/); if (!match) return new Response("Not found", { status: 404 }); const meetingId = match[1]; const agent = env.MEETING_AGENT.getByName(meetingId); // Authenticate the caller before adding or removing an agent. if (request.method === "DELETE") { await agent.stop(); return new Response("Agent stopped", { status: 200 }); } if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); } const res = await fetch( `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/realtime/kit/${env.APP_ID}/meetings/${meetingId}/participants`, { method: "POST", headers: { Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Notes bot", preset_name: env.AGENT_PRESET, custom_participant_id: `agent-${meetingId}`, }), }, ); if (!res.ok) return new Response("Add participant failed", { status: 502 }); const { data } = await res.json<{ data: { token: string } }>(); await agent.start(data.token); return new Response("Agent started", { status: 202 }); }, } satisfies ExportedHandler<Env>; -
在 Durable Object 中建立 WebSocket。 Durable Object 会连接、存储
connection_id、处理事件、重新连接,并在调用stop()时离开会议:src/agent.jsjs import { DurableObject } from "cloudflare:workers"; const AGENT_WS = "https://api.realtime.cloudflare.com/agent-ws/v1"; const SUBSCRIPTIONS = "transcript,participant"; export class MeetingAgent extends DurableObject { ws; async start(token) { await this.ctx.storage.put("token", token); await this.ctx.storage.delete("connectionId"); await this.connect(); } async stop() { // Closing with 1000 makes the agent leave the meeting immediately. await this.ctx.storage.deleteAll(); await this.ctx.storage.deleteAlarm(); this.ws?.close(1000, "agent_stopped"); this.ws = undefined; } async connect() { const token = await this.ctx.storage.get("token"); if (!token || this.ws) return; const url = new URL(AGENT_WS); url.searchParams.set("subscriptions", SUBSCRIPTIONS); const connectionId = await this.ctx.storage.get("connectionId"); if (connectionId) url.searchParams.set("connection_id", connectionId); // Workers open outbound WebSockets with fetch and an Upgrade header. const res = await fetch(url, { headers: { Upgrade: "websocket", Authorization: `Bearer ${token}`, "Sec-WebSocket-Protocol": "realtimekit.v1", }, }); const ws = res.webSocket; if (!ws) { console.error("upgrade failed", res.status, await res.text()); if (res.status === 404) await this.ctx.storage.delete("connectionId"); if (res.status >= 500 || res.status === 404) this.retry(); return; } ws.accept(); this.ws = ws; ws.addEventListener("message", (e) => this.onFrame(JSON.parse(e.data))); ws.addEventListener("close", (e) => this.onClose(e.code, e.reason)); ws.send( JSON.stringify({ category: "request", request_id: "connection", name: "connection.get", data: {}, }), ); } async onFrame(frame) { if ( frame.category === "result" && frame.request_id === "connection" && frame.data ) { await this.ctx.storage.put("connectionId", frame.data.connection.id); return; } if (frame.category !== "message") return; switch (frame.name) { case "transcript.received": if (frame.data.is_final) { console.log(`${frame.data.speaker.display_name}: ${frame.data.text}`); } break; case "participant.join": console.log("joined", frame.data.participant.display_name); break; case "session.ended": console.log("session ended", frame.data.reason); break; } } async onClose(code, reason) { this.ws = undefined; if (code === 4409 || code === 4403) return; // replaced, or fix the token if (code === 1000 || reason === "queue_overflow") { // Start fresh next time. Call start() again for the next session. await this.ctx.storage.delete("connectionId"); if (code === 1000) return; } this.retry(); } retry() { // Resume within 5 seconds to avoid a gap. this.ctx.storage.setAlarm(Date.now() + 1000); } async alarm() { await this.connect(); } }src/agent.tsts import { DurableObject } from "cloudflare:workers"; const AGENT_WS = "https://api.realtime.cloudflare.com/agent-ws/v1"; const SUBSCRIPTIONS = "transcript,participant"; export class MeetingAgent extends DurableObject<Env> { ws?: WebSocket; async start(token: string) { await this.ctx.storage.put("token", token); await this.ctx.storage.delete("connectionId"); await this.connect(); } async stop() { // Closing with 1000 makes the agent leave the meeting immediately. await this.ctx.storage.deleteAll(); await this.ctx.storage.deleteAlarm(); this.ws?.close(1000, "agent_stopped"); this.ws = undefined; } async connect() { const token = await this.ctx.storage.get<string>("token"); if (!token || this.ws) return; const url = new URL(AGENT_WS); url.searchParams.set("subscriptions", SUBSCRIPTIONS); const connectionId = await this.ctx.storage.get<string>("connectionId"); if (connectionId) url.searchParams.set("connection_id", connectionId); // Workers open outbound WebSockets with fetch and an Upgrade header. const res = await fetch(url, { headers: { Upgrade: "websocket", Authorization: `Bearer ${token}`, "Sec-WebSocket-Protocol": "realtimekit.v1", }, }); const ws = res.webSocket; if (!ws) { console.error("upgrade failed", res.status, await res.text()); if (res.status === 404) await this.ctx.storage.delete("connectionId"); if (res.status >= 500 || res.status === 404) this.retry(); return; } ws.accept(); this.ws = ws; ws.addEventListener("message", (e) => this.onFrame(JSON.parse(e.data as string))); ws.addEventListener("close", (e) => this.onClose(e.code, e.reason)); ws.send( JSON.stringify({ category: "request", request_id: "connection", name: "connection.get", data: {}, }), ); } async onFrame(frame: any) { if (frame.category === "result" && frame.request_id === "connection" && frame.data) { await this.ctx.storage.put("connectionId", frame.data.connection.id); return; } if (frame.category !== "message") return; switch (frame.name) { case "transcript.received": if (frame.data.is_final) { console.log(`${frame.data.speaker.display_name}: ${frame.data.text}`); } break; case "participant.join": console.log("joined", frame.data.participant.display_name); break; case "session.ended": console.log("session ended", frame.data.reason); break; } } async onClose(code: number, reason: string) { this.ws = undefined; if (code === 4409 || code === 4403) return; // replaced, or fix the token if (code === 1000 || reason === "queue_overflow") { // Start fresh next time. Call start() again for the next session. await this.ctx.storage.delete("connectionId"); if (code === 1000) return; } this.retry(); } retry() { // Resume within 5 seconds to avoid a gap. this.ctx.storage.setAlarm(Date.now() + 1000); } async alarm() { await this.connect(); } } -
部署并启动 Agent。
npx wrangler deploy curl -X POST https://meeting-agent.<SUBDOMAIN>.workers.dev/meetings/<MEETING_ID>/agent使用浏览器加入会议并发言。运行
npx wrangler tail查看转录内容和参与者加入事件。会议结束后,移除 Agent:
curl -X DELETE https://meeting-agent.<SUBDOMAIN>.workers.dev/meetings/<MEETING_ID>/agent
Agent 是会议参与者,因此计费方式与其他参与者相同。从加入会话到离开会话期间,RealtimeKit 会按 Agent 的参与者分钟数收费。价格请参阅 RealtimeKit 定价,参与者分钟数的计算方式请参阅计费常见问题。
只要有任何参与者连接,会话就会保持活动状态,其中也包括 Agent。如果其他人都离开而 Agent 仍保持连接,会话不会结束。RealtimeKit 会持续按 Agent 的参与者分钟数计费;如果有录制正在进行,也会持续计费,直到 Agent 离开或有人结束会话。
使用以下任一方式结束会话:
| 方法 | 效果 |
|---|---|
使用代码 1000 关闭 WebSocket。 |
Agent 会立即离开。其他参与者全部离开后,会话结束。 |
| 调用踢出所有参与者 API。 | 此操作会移除所有参与者(包括 Agent)并结束会话。Agent 会收到 participant.kick_all 和 session.ended。 |
若要为所有人结束会话(例如预定会议时间已到),请调用踢出所有参与者 API:
Required API token permissions
At least one of the following token permissions is required:Realtime AdminRealtime
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/realtime/kit/$APP_ID/meetings/$MEETING_ID/active-session/kick-all" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"发送 { "category": "request", "request_id", "name", "data": {} }。每个请求都会收到一个 result,其中具有相同的 request_id,并包含 data 或 error。
| 名称 | 返回值 |
|---|---|
connection.get |
{ connection: { id, subscriptions } } |
connection.ping |
{} |
{
"category": "result",
"request_id": "r1",
"name": "connection.get",
"data": {
"connection": {
"id": "conn_6f1c2a7e",
"subscriptions": ["transcript", "participant"]
}
},
"error": null
}失败结果会包含 data: null,且 error.code 会设为 INVALID_REQUEST、UNSUPPORTED_REQUEST 或 INTERNAL_ERROR。连接会保持打开状态。
存储 connection.id,并将其作为 connection_id 传入以恢复连接。它标识的是 WebSocket 连接,而非参与者或会话。
- 使用
1000关闭会使 Agent 立即离开会议。 - 使用其他关闭代码时会启动 5 秒宽限期。Agent 会保持加入状态并将事件排队。
- Agent 离开会议期间发送的事件会丢失。第二个
session.started表示这段间隔。
| 关闭代码 | 原因 | 操作 |
|---|---|---|
1000 |
session_ended |
为下一个会话打开新连接 |
1013 |
queue_overflow |
不带 connection_id 打开新连接 |
1013 |
upstream_lost |
使用 connection_id 恢复连接 |
1013 |
upstream_unavailable |
使用 connection_id 和退避机制恢复连接 |
4403 |
upstream_rejected |
修复令牌或参与者 |
4409 |
replaced |
不重新连接 |
恢复操作的效果
始终会先按顺序传送尚未发送的事件。
| 状态 | 结果 |
|---|---|
| 处于宽限期内,或之前的 WebSocket 仍打开 | 相同连接会继续,不会产生间隔。之前的 WebSocket 会以 4409 关闭。 |
Agent 已离开,或连接以 upstream_lost 或 upstream_unavailable 关闭 |
Agent 会再次加入。你会收到新的 session.started,然后收到实时事件。 |
连接以 session_ended、queue_overflow 或 upstream_rejected 关闭 |
先收到 HTTP 101,然后再次收到相同的关闭代码。请在不带 connection_id 的情况下打开新连接。 |
- 恢复连接时如果包含
subscriptions,它会替换已存储的列表。已经排队的事件不会重新过滤。 - 同一参与者的新令牌也可接受。
connection_id不会过期。 - 如需发送心跳,请每 20 秒发送一次
connection.ping。如果 10 秒内未收到结果,请重新连接。
升级请求遭拒时,会返回 HTTP 错误,而不是 101:
{
"success": false,
"error": {
"code": "UNAUTHENTICATED",
"message": "Invalid participant token.",
"retryable": false
}
}| 状态 | 代码 | 原因 |
|---|---|---|
400 |
BAD_REQUEST |
缺少 realtimekit.v1 子协议 |
400 |
INVALID_QUERY |
参数或订阅未知,或者 connection_id 为空 |
401 |
UNAUTHENTICATED |
令牌缺失、无效或已过期 |
404 |
CONNECTION_NOT_FOUND |
connection_id 未知,或属于另一位参与者 |
| 限制 | 值 |
|---|---|
| 每个连接尚未发送的事件数 | 10,000 |
| 重新连接宽限期 | 5 秒 |
request_id 长度 |
1–128 个字符 |
目前计划支持从 Agent 发送聊天消息和广播。当前 Agent 仅接收事件。如需立即对会议执行操作,请在 Worker 中调用 RealtimeKit REST API,例如踢出参与者。