跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

构建 Agent

最后更新 查看 MarkdownAgent 设置

Agent 是由你的后端通过 WebSocket 控制的会议参与者。若要添加 Agent,请配置预设,将 Agent 作为参与者添加,然后使用该参与者令牌连接到 WebSocket 端点。

我的 Worker
我的 Durable Object
Agent Participant
RealtimeKit 会议
使用 agent 预设添加参与者
start(token)
携带 token + 订阅进行升级
以可见或隐藏参与者身份加入
session.started
转录、加入、广播
以 JSON 形式发送已订阅事件

选择 Agent 模式

请决定会议参与者是否应该看到 Agent。本页介绍的两种模式都采用相同的步骤并接收相同事件,区别仅在于预设。

模式 预设 用途
隐藏 Agent hidden_participant: true 合规监控、实时分析
可见 Agent hidden_participant: false 参与者在会议中可以看到的会议记录机器人

隐藏 Agent

如果不希望参与者看到 Agent,请使用隐藏 Agent。例如,可借此监控合规性、审核通话质量或收集实时会议分析数据。

用户使用 RealtimeKit SDK 的浏览器或应用
音频、视频、聊天
RealtimeKit 会议
用户看到的内容
Alice
Bob
隐藏的 Agent监控器从列表和网格中筛除
转录、加入、广播
我的代码Durable ObjectWebSocket ↔ JSON
用户音频、视频、聊天 ↔RealtimeKit 会议
监控器对用户隐藏RealtimeKit 会议
监控器转录、加入、广播 →Durable Object
  • 参与者看不到。 RealtimeKit SDK 会从参与者列表和视频网格中过滤掉该 Agent。
  • 仍会发送加入和离开事件。 每个已连接到会议的客户端都会收到这些事件,但 SDK 不会显示它们。不要依赖 hidden_participant 对检查自己客户端的参与者保密。
  • 事件和计费相同。 隐藏 Agent 会接收其订阅的所有事件,会按参与者计费,并且连接期间会使会话保持活动状态。
  • 系统不会自动移除 Agent。 参与者看不到该 Agent,因此你的后端必须结束它。
  • 是否披露由你决定。 隐藏 Agent 不会隐藏会议正在转录这一事实。如果你的政策要求,请告知参与者。

可见 Agent

如果希望参与者知道 Agent 已加入,请使用可见 Agent。例如,名为“会议记录机器人”的 Agent 加入后即可开始记录。

用户使用 RealtimeKit SDK 的浏览器或应用
音频、视频、聊天
RealtimeKit 会议
用户看到的内容
Alice
Bob
笔记机器人
可见的 Agent笔记机器人显示为图块,无音频或视频
转录、加入、广播
我的代码Durable ObjectWebSocket ↔ JSON
用户音频、视频、聊天 ↔RealtimeKit 会议
笔记机器人网格中的图块RealtimeKit 会议
笔记机器人转录、加入、广播 →Durable Object
  • 以名称显示。 你在将 Agent 添加为参与者时传入的 name 就是参与者看到的名称。
  • 在网格中占据一个格子。 即使 Agent 不发送音频或视频,也会显示在视频网格中。如果你使用自定义 Core SDK 网格,可按 participant.presetName 将其过滤掉。
  • 加入后才开始。 Agent 加入前说的话不会被捕获。若要捕获整个会话,请在会议开始前添加 Agent。

要求

  • 一个 RealtimeKit 应用和会议。请参阅快速入门。
  • 一个具有 RealtimeKit 访问权限的 Cloudflare API 令牌。
  • 若要接收实时转录,请在需要转录的参与者预设中启用实时转录。否则 Agent 不会收到 transcript.received 事件。

1. 配置 Agent 预设

与其他参与者一样,Agent 使用预设加入会议。你可以使用现有预设,但专用的 Agent 预设能将 Agent 设置与人类参与者的设置分开。请在 RealtimeKit 控制面板 ↗中创建预设,或使用创建预设 API。

若要对其他参与者隐藏 Agent,请使用更新预设 API设置 hidden_participant:

Required API token permissions

At least one of the following token permissions is required:
  • Realtime Admin
  • Realtime
Update a presetbash
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。

2. 为 Agent 创建会议和参与者令牌

如果尚无会议,请使用创建会议 API创建会议:

Required API token permissions

At least one of the following token permissions is required:
  • Realtime Admin
  • Realtime
Create a meetingbash
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 Admin
  • Realtime
Add a participantbash
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 天。

3. 连接到 Agent 的 WebSocket URL

使用参与者令牌和 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。

4. 设置连接参数

参数 值
subscriptions 可选。可以是 transcript、participant、broadcast 中的任意项,以逗号分隔。
connection_id 可选。恢复先前的连接。请参阅重新连接。

subscriptions 决定 Agent 会收到哪些事件。始终会发送会话事件。

类别 事件 需要
transcript transcript.received 发言者的预设中已启用实时转录。
participant participant.join, participant.leave 无
broadcast broadcast.received 你的应用发送广播。

请只订阅你会用到的事件。事件越少,重连期间需要排队的事件就越少。有关载荷和传递规则,请参阅事件。

5. 在 Durable Object 中运行 Agent

此示例将步骤 1 到 4 组合起来。Worker 会将 Agent 添加到会议中,Durable Object 则持有 Agent 的 WebSocket,并记录最终转录内容和参与者加入事件。

Durable Object 适合运行 Agent:每个会议对应一个实例,支持长时间运行的出站 WebSocket,并可存储用于恢复连接的 connection_id。

  1. 配置 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_TOKEN
  2. 添加和移除 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>;
  3. 在 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();
     }
    }
  4. 部署并启动 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 Admin
  • Realtime
Kick all participantsbash
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。连接会保持打开状态。

重新连接

Agent Durable Object
Agent Participant
会议
connection.get
connection.id
WebSocket 以非 1000 的代码断开
Agent 保持加入 5 秒并将事件排队
使用 ?connection_id= 进行升级
按顺序发送排队的事件
实时事件

存储 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,例如踢出参与者。

这篇文档对您有帮助吗?