# API 概览 (/zh-CN/api-reference/conversational-ai/agent-typescript) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## AgoraClient [#agoraclient] `AgoraClient` 是 SDK 的入口,用于管理区域路由、鉴权和 API 访问。 ```typescript import { AgoraClient, Area } from 'agora-agents'; ``` ### 构造函数 [#constructor] ```typescript const client = new AgoraClient(options: AgoraClient.Options); ``` 鉴权模式会根据你提供的参数自动解析。 | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `area` | [`Area`](#area) | 是 | API 路由所使用的区域。固定为 `Area.CN` | | `appId` | `string` | 是 | 声网 App ID | | `appCertificate` | `string` | 是 | 声网 App 证书。请妥善保管,切勿暴露在客户端 | | `customerId` | `string` | 否 | 用于 Basic Auth 的客户 ID | | `customerSecret` | `string` | 否 | 用于 Basic Auth 的客户密钥 | | `authToken` | `string` | 否 | 预先构造好的 `agora token=` 字符串 | | `timeoutInSeconds` | `number` | 否 | 请求超时时间,单位为秒 | | `maxRetries` | `number` | 否 | 最大重试次数 | | `logging` | `LogConfig \| Logger` | 否 | SDK 日志配置 | | `fetch` | `typeof fetch` | 否 | 在不支持默认运行时的环境中传入自定义 `fetch` 实现 | 鉴权模式根据你提供的参数解析如下: | 传入的配置项 | Resolved [`authMode`](#agoraauthmode) | |---|---| | `customerId` + `customerSecret` | `"basic"` | | `authToken` | `"token"` | | 均未提供 | `"app-credentials"` | 各鉴权模式的详细说明可参考[实现 HTTP 安全认证](/zh-CN/ai/build/http-basic-auth)。 ### 属性 [#properties] 任意 `AgoraClient` 实例都提供以下只读属性。 | 属性 | 类型 | 说明 | |---|---|---| | `appId` | `string` | 声网 App ID | | `appCertificate` | `string` | 声网 App 证书 | | `authMode` | [`AgoraAuthMode`](#agoraauthmode) | 解析后的鉴权模式 | | `pool` | `Pool` | 用于区域路由的底层域名池实例 | ### 方法 [#methods] 除基础 API 访问能力外,还提供以下高层方法。 #### `agent(options?)` [#agentoptions] 创建一个绑定到当前客户端的 [`Agent`](#agent)。这样无需在 `Agent` 构造函数里再次传入 `client`。 ```typescript const agent = client.agent({ turnDetection: { language: 'zh-CN' } }); ``` #### `nextRegion()` [#nextregion] 将域名池切换到下一个区域前缀。通常在请求失败后调用,以尝试其他区域端点。 ```typescript client.nextRegion(); ``` #### `selectBestDomain(signal?)` [#selectbestdomainsignal] 手动触发一次 DNS 解析检测,以选择最优的域名后缀。SDK 默认每 30 秒自动执行一次,你也可以手动调用。 ```typescript await client.selectBestDomain(); ``` | 参数 | 类型 | 说明 | |---|---|---| | `signal` | `AbortSignal` | 可选的中止信号,用于取消此次 DNS 检测 | #### `getCurrentURL()` [#getcurrenturl] 返回当前正在使用的完整 API URL,类型为 `string`。 ```typescript const url = client.getCurrentURL(); // Example: 'https://api-cn-east-1.sd-rtn.com/cn/api/conversational-ai-agent' ``` ### 子客户端 [#sub-clients] `AgoraClient` 也暴露了原始 API 客户端,便于访问尚未被 `Agent` 或 `AgentSession` 封装的接口。大多数场景下,建议优先使用 [Agent](#agent) 和 [AgentSession](#agentsession) 这套高层 API。 | 属性 | 说明 | |---|---| | `client.agents` | 启动、停止、更新、播报、打断、获取历史记录、查询智能体列表 | 完整的方法签名和请求参数可参考[创建对话式智能体 RESTful API](/zh-CN/api-reference/api-ref/conversational-ai/join)。 ## Agent [#agent] `Agent` 是一个不可变的配置对象。每个构建方法都会返回一个新的 `Agent` 实例,原对象不会被修改。建议在应用启动时定义一个 `Agent`,并在每次用户对话时基于它调用 `createSession()`。 在构造时通过 `new Agent({ client, ... })`(或 [`client.agent(...)`](#agentoptions))绑定 `AgoraClient`,[`createSession()`](#createsessionoptions) 会复用该客户端,因此创建会话时无需再传入客户端。智能体实例名不在 `Agent` 构造函数上设置,而是在 `createSession({ name })` 时传入。 ```typescript import { AgoraClient, Agent, Area } from 'agora-agents'; const client = new AgoraClient({ area: Area.CN, appId: 'your-app-id', appCertificate: 'your-app-certificate' }); const agent = new Agent({ client }); ``` ### 构造函数 [#constructor-1] ```typescript new Agent(options?: AgentOptions) ``` 所有选项均为可选项。创建后可通过 [构建方法](#builder-methods) 配置各服务商。 | 配置项 | 类型 | 默认值 | 说明 | |---|---|---|---| | `client` | `AgoraClient` | `undefined` | 绑定的客户端,绑定后即可调用 `createSession(options)` 而无需再传入客户端 | | `pipelineId` | `string` | `undefined` | 作为基础配置使用的已发布 AI Studio 工作流 ID | | `instructions` | `string` | `undefined` | 已废弃。请改用 LLM 服务商的 `systemMessages` | | `greeting` | `string` | `undefined` | 已废弃。请改用 LLM 服务商的 `greetingMessage` | | `failureMessage` | `string` | `undefined` | 已废弃。请改用 LLM 服务商的 `failureMessage` | | `maxHistory` | `number` | `undefined` | 已废弃。请改用 LLM 服务商的 `maxHistory` | | `turnDetection` | `TurnDetectionConfig` | `undefined` | 语音活动检测设置 | | `interruption` | `InterruptionConfig` | `undefined` | 统一的打断控制设置 | | `sal` | `SalConfig` | `undefined` | 选择性注意力锁定配置 | | `avatar` | `AvatarConfig` | `undefined` | 数字人配置(推荐使用 `withAvatar()` 以获得类型安全) | | `advancedFeatures` | `AdvancedFeatures` | `undefined` | 启用 AI-VAD 等高级特性 | | `parameters` | `SessionParams` | `undefined` | 会话参数,包括静默与结束语配置 | | `geofence` | `GeofenceConfig` | `undefined` | 区域访问限制 | | `labels` | `Labels` | `undefined` | 在通知回调中返回的自定义键值标签 | | `rtc` | `RtcConfig` | `undefined` | RTC 媒体加密配置 | | `fillerWords` | `FillerWordsConfig` | `undefined` | 在等待 LLM 响应期间播放的承接词配置 | | `greetingConfigs` | `LlmGreetingConfigs` | `undefined` | 已废弃。请改在 LLM 服务商上配置 | `instructions`、`greeting`、`failureMessage`、`maxHistory`、`greetingConfigs` 是兼容性字段。新代码应在 LLM 服务商上配置这些值,以匹配核心请求 schema。 :::info[信息] `AgentOptions` 支持泛型参数(`AgentOptions<TArea>`)。SDK 会根据客户端的区域配置提示可用的服务商,但不会强制校验服务商与区域是否匹配。 ::: ### 构建方法 [#builder-methods] 所有构建方法都会返回一个**新的** `Agent` 实例,原对象不会被修改。 仅支持级联式 ASR + LLM + TTS 流水线以及服务商。 #### `withLlm(vendor)` [#withllmvendor] 设置 LLM 服务商。传入任意 [LLM 服务商 class](#llm-vendors)([`AliyunLLM`](#llm-vendors)、[`BytedanceLLM`](#llm-vendors)、[`DeepSeekLLM`](#llm-vendors)、[`TencentLLM`](#llm-vendors) 或 [`CustomLLM`](#llm-vendors))的实例。 ```typescript withLlm(vendor: BaseCNLLM): Agent ``` #### `withTts(vendor)` [#withttsvendor] 设置 TTS 服务商。该方法会捕获并追踪采样率类型,以便进行[数字人](#avatar-vendors)兼容性校验。 ```typescript withTts(vendor: BaseCNTTS): Agent ``` #### `withStt(vendor)` [#withsttvendor] 设置 STT 服务商。可传入任意 [STT 服务商 class](#stt-vendors) 的实例。 ```typescript withStt(vendor: BaseCNSTT): Agent ``` #### `withAvatar(vendor)` [#withavatarvendor] 设置数字人服务商。这里的 `this` 约束会在编译阶段校验该 `Agent` 的 TTS 采样率是否满足数字人要求。需要使用级联式 ASR + LLM + TTS 流水线。 ```typescript withAvatar( this: Agent, vendor: BaseCNAvatar ): Agent ``` #### `withTurnDetection(config)` [#withturndetectionconfig] 配置级联流程中的 turn detection。使用 `config.start_of_speech` 和 `config.end_of_speech` 配置 SOS/EOS 检测。打断行为请使用 `withInterruption()`。 ```typescript withTurnDetection(config: TurnDetectionConfig): Agent ``` #### `withInterruption(config)` [#withinterruptionconfig] 通过顶层 `interruption` 对象配置统一打断行为。适用于 `start_of_speech` 和 `keywords` 两类打断模式。 ```typescript withInterruption(config: InterruptionConfig): Agent ``` #### `withInstructions(text)` [#withinstructionstext] 已废弃。请改用 LLM 服务商的 `systemMessages`。在新的 `Agent` 实例上覆盖 LLM 系统提示词。 ```typescript withInstructions(instructions: string): Agent ``` #### `withGreeting(text)` [#withgreetingtext] 已废弃。请改用 LLM 服务商的 `greetingMessage`。在新的 `Agent` 实例上覆盖问候语。 ```typescript withGreeting(greeting: string): Agent ``` #### 其他构建方法 [#other-builder-methods] 以下方法遵循相同模式,都会返回一个包含更新后配置的新 `Agent` 实例。 | 方法 | 参数类型 | 说明 | |---|---|---| | `withSal(config)` | `SalConfig` | 设置选择性注意力锁定配置 | | `withAdvancedFeatures(features)` | `AdvancedFeatures` | 设置高级特性 | | `withTools(enabled)` | `boolean` | 启用或关闭 MCP 和自定义工具调用 | | `withParameters(parameters)` | `SessionParams` | 设置会话参数 | | `withAudioScenario(audioScenario)` | `ParametersAudioScenario` | 设置 `parameters.audio_scenario`。可选值为 `default`、`chorus` 和 `aiserver`。未设置时,SDK 会自动补成 `chorus`。为便于发现可选值,建议使用导出的 `AudioScenario` 常量,例如 `agent.withAudioScenario(AudioScenario.Aiserver)` | | `withFailureMessage(message)` | `string` | 设置 LLM 失败时播报的消息 | | `withMaxHistory(n)` | `number` | 设置级联 LLM 流水线的最大对话历史长度 | | `withGeofence(geofence)` | `GeofenceConfig` | 设置 geofence 配置 | | `withLabels(labels)` | `Labels` | 设置自定义标签 | | `withRtc(rtc)` | `RtcConfig` | 设置 RTC 配置 | | `withFillerWords(fillerWords)` | `FillerWordsConfig` | 设置承接词配置 | ### `createSession(options)` [#createsessionoptions] 使用构造 `Agent` 时绑定的客户端创建一个绑定到频道的 [`AgentSession`](#agentsession)。该方法不会立即启动智能体,需调用 [`session.start()`](#start) 才会加入频道。 如果构造 `Agent` 时未传入 `client`,调用 `createSession()` 会抛出错误。 ```typescript createSession( options: SessionOptions, ): AgentSession ``` ```typescript const session = agent.createSession({ name: 'support-agent', channel: 'support-room', agentUid: '1', remoteUids: ['100'], }); ``` `name` 为智能体实例名,会发送给声网 API。请在 `createSession()` 上设置,而不要设置在 `Agent` 上;省略时自动生成 `agent-{timestamp}`。 `SessionOptions` 字段如下: | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `name` | `string` | 否 | 发送给声网 API 的智能体实例名。省略时自动生成 `agent-{timestamp}` | | `channel` | `string` | 是 | 要加入的频道名 | | `agentUid` | `string` | 是 | 智能体的 RTC UID | | `remoteUids` | `string[]` | 是 | 智能体需要监听并响应的远端用户 UID 列表 | | `token` | `string` | 否 | 预先构造好的 RTC+RTM token。留空时会根据应用凭据自动生成 | | `expiresIn` | `number` | 否 | token 有效期,单位为秒。仅在自动生成 token 时生效。有效范围为 1–86400。建议使用 [`ExpiresIn`](#expiresin) 辅助方法增强可读性 | | `idleTimeout` | `number` | 否 | 当检测不到音频时,智能体自动退出前的秒数。`0` 表示禁用超时 | | `enableStringUid` | `boolean` | 否 | 使用字符串 UID,而非数字 UID | | `pipelineId` | `string` | 否 | 作为基础配置使用的已发布 AI Studio 工作流 ID | | `debug` | `boolean` | 否 | 在控制台输出 API 请求日志 | | `warn` | `(message: string) => void` | 否 | 自定义告警日志函数;如需静默告警可传入空操作函数 | 各服务商均为 BYOK,需要提供对应服务商的凭据。 ### 属性 [#properties-1] 任意 `Agent` 实例都提供以下只读属性。 | 属性 | 类型 | 说明 | |---|---|---| | `pipelineId` | `string \| undefined` | 作为基础配置使用的已发布 AI Studio 工作流 ID | | `instructions` | `string \| undefined` | LLM 系统提示词(兼容性字段) | | `greeting` | `string \| undefined` | 问候语(兼容性字段) | | `failureMessage` | `string \| undefined` | LLM 失败时播报的消息(兼容性字段) | | `maxHistory` | `number \| undefined` | 最大对话历史长度(兼容性字段) | | `llm` | `LlmConfig \| undefined` | LLM 配置 | | `tts` | `TtsConfig \| undefined` | TTS 配置 | | `stt` | `SttConfig \| undefined` | STT 配置 | | `avatar` | `AvatarConfig \| undefined` | 数字人配置 | | `turnDetection` | `TurnDetectionConfig \| undefined` | 轮次检测配置 | | `interruption` | `InterruptionConfig \| undefined` | 打断配置 | | `sal` | `SalConfig \| undefined` | SAL 配置 | | `advancedFeatures` | `AdvancedFeatures \| undefined` | 高级特性配置 | | `parameters` | `SessionParams \| undefined` | 会话参数 | | `geofence` | `GeofenceConfig \| undefined` | Geofence 配置 | | `labels` | `Labels \| undefined` | 自定义标签 | | `rtc` | `RtcConfig \| undefined` | RTC 配置 | | `fillerWords` | `FillerWordsConfig \| undefined` | 承接词配置 | | `greetingConfigs` | `LlmGreetingConfigs \| undefined` | 问候语播放配置兼容性字段 | | `config` | `AgentOptions` | 完整的只读配置快照 | ### `toProperties(opts)` [#topropertiesopts] 高级方法,用于将 `Agent` 配置转换为 Start Agent API 所需的请求结构。`AgentSession.start()` 内部会调用该方法;除非你需要自行构造请求体,否则通常无需直接调用。 ```typescript toProperties(opts): StartAgentsRequest.Properties ``` ### 类型别名 [#type-aliases] SDK 公开了常用请求与响应类型的别名,包括 `LlmConfig`、`SttConfig`、`AsrConfig`(即 `SttConfig`)、`AvatarConfig`、会话/对话相关类型,以及 think 类型(例如 `ThinkOnListeningAction`)。 `FillerWordsConfig` 支持静态承接词和动态承接词。使用动态承接词时,必须同时配置非空的静态短语作为回退;`generated_config` 中的 `prompt`、上下文限制和回退策略均为可选项,模型服务和凭证由声网托管。具体字段结构详见[配置承接词](/zh-CN/ai/build/shape-the-conversation/filler-words)。 动态承接词配置还支持 `context_message_limit`(取值范围 `1` 到 `6`,省略时由服务按 `1` 处理)和 `history_character_limit`(取值范围 `0` 到 `10000`,省略时由服务按 `1000` 处理)。前者包含当前用户消息,显式设置为 `2` 到 `6` 时启用近期历史;后者只统计历史消息文本的 Unicode 码点。 Think 值常量包括:`ThinkOnListeningActionInject`、`ThinkOnListeningActionInterrupt`、`ThinkOnListeningActionAppend`、`ThinkOnListeningActionIgnore`、`ThinkOnThinkingActionInterrupt`、`ThinkOnThinkingActionAppend`、`ThinkOnThinkingActionIgnore`、`ThinkOnSpeakingActionInterrupt`、`ThinkOnSpeakingActionAppend`、`ThinkOnSpeakingActionIgnore`。`append` 不打断当前交互,分别等待当前用户回合、LLM 推理或 TTS 播报完成后,再将该指令作为独立的 user 消息追加到上下文并发起新一轮对话。 公开类型别名还包括 `FillerWordsContentGeneratedConfig`、`FillerWordsContentMode` 以及自定义工具相关的 `LlmTool`、`LlmToolFunction`、`LlmToolServer` 和 `LlmToolExecution`。`llm.tools` 与 MCP 服务器配置相互独立,但都需要通过 `withTools(true)` 开启工具调用。 ## AgentSession [#agentsession] `AgentSession` 负责管理运行中智能体的完整生命周期。请通过 [`agent.createSession()`](#createsessionoptions) 创建会话,而不要直接调用构造函数。 ```typescript import { AgentSession } from 'agora-agents'; ``` 通过 `SessionOptions` 的 `name` 字段设置发送给声网 API 的智能体实例名;省略时自动生成 `agent-{timestamp}`。 ### 状态机 [#state-machine] 会话状态会按以下流程推进: ```text idle ──► starting ──► running ──► stopping ──► stopped │ ▼ error ``` | 状态变化 | 触发条件 | |---|---| | `idle → starting` | 调用 `start()` | | `starting → running` | API 返回智能体 ID | | `starting → error` | API 请求失败 | | `running → stopping` | 调用 `stop()` | | `stopping → stopped` | API 确认智能体已停止 | | `stopping → error` | 停止请求失败,且智能体并未提前停止 | | `running → error` | 交互过程中发生不可恢复错误 | 在 `stopped` 或 `error` 状态下,也可以再次调用 `start()` 以重启会话。 ### 方法 [#methods-1] `AgentSession` 实例提供以下方法。 #### `start()` [#start] 启动智能体会话。如果未提供 token,则自动生成 token,随后发送启动请求并返回智能体 ID。 ```typescript start(): Promise ``` - 状态流转:`idle` / `stopped` / `error` → `starting` → `running` - 若在 `starting`、`running` 或 `stopping` 状态下调用,则抛出异常 - 若数字人配置无效(例如 TTS 采样率不匹配),则抛出异常 - 各服务商均为 BYOK,会按 `Agent` 上配置的服务商凭据发送配置 #### `stop()` [#stop] 停止智能体会话,并让智能体退出频道。如果智能体已经停止,例如由于空闲超时自动退出,则该方法会静默返回,而不会因为 404 报错。 ```typescript stop(): Promise ``` - 状态流转:`running` → `stopping` → `stopped` - 仅可在 `running` 状态下调用,否则抛出异常 #### `say(text, options?)` [#saytext-options] 指示智能体播报指定文本。 ```typescript say(text: string, options?: SayOptions): Promise ``` | 参数 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `text` | `string` | 是 | 要让智能体播报的文本 | | `options.priority` | [`SpeakPriority`](#speakpriority) | 否 | 消息优先级 | | `options.interruptable` | `boolean` | 否 | 该消息是否允许被用户打断 | - 仅在 `running` 状态下有效 #### `interrupt()` [#interrupt] 打断智能体当前正在播报的内容。 ```typescript interrupt(): Promise ``` - 仅在 `running` 状态下有效 #### `update(config)` [#updateconfig] 在不重启会话的情况下,更新会话中的智能体配置。该方法接收 REST API 格式的部分配置对象。 ```typescript update(config: AgentConfigUpdate): Promise ``` - 仅在 `running` 状态下有效 #### `getHistory()` [#gethistory] 获取当前会话的对话历史。该方法要求已有有效的智能体 ID,也就是 `start()` 必须已成功调用。 ```typescript getHistory(): Promise ``` #### `getTurns(options?)` [#getturnsoptions] 获取当前会话的逐轮分析数据,包括开始/结束事件以及延迟指标。该方法要求已有有效的智能体 ID,且 `start()` 已成功调用。 ```typescript getTurns(options?: GetTurnsOptions): Promise ``` - `options.page_index`:页码,从 `1` 开始 - `options.page_size`:每页返回的轮次数量 #### `getAllTurns(options?)` [#getallturnsoptions] 获取所有轮次分析分页,并合并 `turns` 数组。该方法要求已有有效的智能体 ID,且 `start()` 已成功调用。 ```typescript getAllTurns(options?: Omit): Promise ``` - 要求存在有效的 `agentId` - 对于超长会话,建议使用 `getTurns()` 按页处理,以避免一次性将所有数据加载到内存中 #### `getInfo()` [#getinfo] 从 API 获取当前智能体的元数据。该方法要求已有有效的智能体 ID。 ```typescript getInfo(): Promise ``` #### `on(event, handler)` [#onevent-handler] 订阅会话事件。建议在调用 `start()` 之前注册 handler,以避免错过 `started` 事件。 ```typescript on(event: AgentSessionEvent, handler: AgentSessionEventHandler): void ``` #### `off(event, handler)` [#offevent-handler] 取消订阅此前注册的事件 handler。 ```typescript off(event: AgentSessionEvent, handler: AgentSessionEventHandler): void ``` ### 事件 [#events] 会话会发出以下事件。类型详情可参考 [`AgentSessionEvent`](#agentsessionevent) 和 [`AgentSessionEventHandler`](#agentsessioneventhandler)。 | 事件 | 数据类型 | 说明 | |---|---|---| | `"started"` | `{ agentId: string }` | 智能体成功加入频道 | | `"stopped"` | `{ agentId: string }` | 智能体离开频道 | | `"error"` | `Error` | 发生不可恢复错误 | ### 属性 [#properties-2] 任意 `AgentSession` 实例都提供以下只读属性。 | 属性 | 类型 | 说明 | |---|---|---| | `status` | `string` | 当前会话状态,可能取值为 `"idle"`、`"starting"`、`"running"`、`"stopping"`、`"stopped"`、`"error"` | | `id` | `string \| null` | 智能体 ID,在 `start()` 成功后填充 | | `agent` | `Agent` | 当前会话所基于的智能体配置 | | `appId` | `string` | 当前会话使用的声网 App ID | | `raw` | `AgentsClient` | 直接访问原始 `AgentsClient`,适用于高级调用场景 | #### 使用 `session.raw` [#using-sessionraw] 你可以通过 `session.raw` 调用尚未被高层 API 封装的接口: ```typescript await session.raw.someNewEndpoint({ appid: session.appId, agentId: session.id!, }); ``` 使用 raw 方法时,需要手动传入 `appid` 和 `agentId`。 ### 自带密钥(BYOK) [#byok] 建议优先在 `Agent` builder 上配置服务商。各服务商均为 BYOK,需要显式提供对应服务商的凭据。 - 在 builder 上为各服务商显式提供凭据 ## 服务商 [#vendors] 服务商类均从 `agora-agents` 导入。将这些服务商实例传给 [Agent 构建方法](#builder-methods) 即可。 ```typescript import { AliyunLLM, BytedanceLLM, DeepSeekLLM, TencentLLM, CustomLLM, MiniMaxCNTTS, MiniMaxDuplexTTS, TencentTTS, BytedanceTTS, MicrosoftCNTTS, CosyVoiceTTS, BytedanceDuplexTTS, StepFunTTS, GenericTTS, FengmingSTT, StepFunSTT, TencentSTT, MicrosoftCNSTT, SensetimeAvatar, SpatiusAvatar, } from 'agora-agents'; ``` 采用 STT → LLM → TTS 的级联流程。所有服务商均为 BYOK,需要提供对应服务商的凭据。constructor 在必填字段缺失时会抛出错误。 ### LLM 服务商 [#llm-vendors] 与 [`withLlm()`](#withllmvendor) 配合使用。LLM helper 均基于 OpenAI 兼容协议(`style = "openai"`),共享同一套构造参数,区别仅在于内部写入的 `vendor` 标识。这些 helper 均为 BYOK,`url`、`model` 和 `apiKey` 均为必填。 | 类 | `vendor` 值 | 服务提供方 | |---|---|---| | `AliyunLLM` | `aliyun` | 阿里云百炼(通义千问,如 `qwen-plus`) | | `BytedanceLLM` | `bytedance` | 火山引擎(字节跳动豆包,如 `doubao-seed-1-6`) | | `DeepSeekLLM` | `deepseek` | DeepSeek(如 `deepseek-chat`) | | `TencentLLM` | `tencent` | 腾讯混元(如 `hunyuan-turbos-latest`) | | `CustomLLM` | `custom` | 任意 OpenAI 兼容协议的 LLM | 以上 helper 共用相同的构造参数: ```typescript import { AliyunLLM } from 'agora-agents'; const llm = new AliyunLLM({ url: 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions', model: 'qwen-plus', apiKey: 'your-api-key', }); ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `url` | `string` | 是 | 兼容 OpenAI 聊天补全接口的端点 | | `model` | `string` | 是 | 模型名称 | | `apiKey` | `string` | 是 | 服务商 API 密钥 | | `maxHistory` | `number` | 否 | 缓存的最大对话历史条数 | | `systemMessages` | `Record[]` | 否 | 附加系统消息列表 | | `greetingMessage` | `string` | 否 | 智能体问候语 | | `failureMessage` | `string` | 否 | LLM 调用失败时播报的消息 | | `inputModalities` | `string[]` | 否 | 输入模态。默认值:`["text"]` | | `outputModalities` | `string[]` | 否 | 输出模态 | | `params` | `Record` | 否 | 透传给模型的附加 LLM 参数 | | `headers` | `Record` | 否 | 转发给 LLM 服务商的自定义 HTTP 请求头 | | `greetingConfigs` | `LlmGreetingConfigs` | 否 | 问候语播放配置 | | `templateVariables` | `Record` | 否 | 消息模板变量 | | `tools` | `LlmTool[]` | 否 | 同步自定义工具定义;需要同时启用 `withTools(true)` | `tools` 用于声明供 LLM 选择调用的自定义工具。每个工具包含模型可见的函数定义,以及同步 `GET` 或 `POST` 请求的服务端配置;`withTools(true)` 同时适用于 `tools` 和 MCP 服务器配置。 :::info[信息] 自定义 LLM 路由复用 `CustomLLM`,因此即便是 BYOK 路径,`apiKey`、`model`、`url` 均为必填。 ::: ### 语音合成服务商 [#tts-vendors] 与 [`withTts()`](#withttsvendor) 配合使用。`sampleRate`(或对应字段)决定数字人兼容性,详见 [`withAvatar()`](#withavatarvendor)。所有 TTS 类均支持 `skipPatterns` 和 `additionalParams`。 #### MiniMaxCNTTS [#minimaxcntts] MiniMax TTS 为 BYOK,始终要求 `key` 和 `model`。此外必须提供 `voiceSetting.voice_id` 或非空的 `timberWeights` 之一。 ```typescript new MiniMaxCNTTS(options: MiniMaxCNTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `key` | `string` | 是 | MiniMax API 密钥 | | `model` | `string` | 是 | MiniMax TTS 模型 | | `voiceSetting` | `MiniMaxCNVoiceSetting` | 条件必填 | 音色设置;未提供 `timberWeights` 时必须设置且 `voice_id` 非空 | | `timberWeights` | `MiniMaxCNTimberWeight[]` | 条件必填 | 混合音色权重;未提供 `voiceSetting.voice_id` 时必填,至少一项 | | `audioSetting` | `MiniMaxCNAudioSetting` | 否 | 音频设置(`sample_rate`) | | `pronunciationDict` | `MiniMaxCNPronunciationDict` | 否 | 发音词典(`tone: string[]`) | | `languageBoost` | `string` | 否 | 语言增强策略 | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加 MiniMax TTS 参数 | `MiniMaxCNVoiceSetting` 字段:`voice_id`(必填)、`speed?`、`vol?`、`pitch?`、`emotion?`、`latex_read?`、`english_normalization?`。`MiniMaxCNTimberWeight` 字段:`voice_id`、`weight`。 #### MiniMaxDuplexTTS [#minimaxduplextts] MiniMax 双向流式 TTS,输出 `tts.vendor = "minimax_duplex"`。`key`、`model` 和 `voiceSetting.voice_id` 必填且不能为空,否则构造函数抛出错误。该构造函数要求单音色配置,混合音色参数不能替代 `voiceSetting.voice_id`。 ```typescript new MiniMaxDuplexTTS(options: MiniMaxDuplexTTSOptions) ``` ```typescript import { MiniMaxDuplexTTS, StepFunSTT } from 'agora-agents'; const tts = new MiniMaxDuplexTTS({ key: '', model: 'speech-2.8-turbo', voiceSetting: { voice_id: 'female-shaonv' }, }); const stt = new StepFunSTT({ apiKey: '' }); ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `key` | `string` | 是 | MiniMax API key | | `model` | `string` | 是 | 模型名称,例如 `speech-2.8-turbo` | | `voiceSetting` | `MinimaxDuplexTtsParams.VoiceSetting` | 是 | 音色设置,`voice_id` 必须非空 | | `url` | `string` | 否 | 双向流式 TTS 的 WebSocket 接口地址 | | `audioSetting` | `MinimaxDuplexTtsParams.AudioSetting` | 否 | 音频设置,写入 `params.audio_setting` | | `pronunciationDict` | `MinimaxDuplexTtsParams.PronunciationDict` | 否 | 发音词典,可选字段 `tone?: string[]` | | `voiceModify` | `MinimaxDuplexTtsParams.VoiceModify` | 否 | 音效设置,写入 `params.voice_modify` | | `languageBoost` | `string` | 否 | 语言增强策略,例如 `Chinese` | | `textNormalizationMode` | `string` | 否 | 文本归一化模式,例如 `basic` | | `subtitleEnable` | `boolean` | 否 | 是否启用字幕 | | `subtitleType` | `string` | 否 | 字幕粒度,例如 `word` | | `continuousSound` | `boolean` | 否 | 是否启用连续音频生成 | | `sessionId` | `string` | 否 | MiniMax 供应商会话标识 | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置,写入 `tts.skip_patterns` | | `additionalParams` | `Record` | 否 | 附加供应商参数;已设置的显式字段优先 | #### TencentTTS [#tencenttts] ```typescript new TencentTTS(options: TencentTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `appId` | `string` | 是 | 腾讯云 TTS 应用 ID | | `secretId` | `string` | 是 | 腾讯云 TTS 密钥 ID | | `secretKey` | `string` | 是 | 腾讯云 TTS 密钥 | | `voiceType` | `number` | 是 | 腾讯云 TTS 音色类型 | | `volume` | `number` | 否 | 音量 | | `speed` | `number` | 否 | 语速 | | `emotionCategory` | `string` | 否 | 情感类别 | | `emotionIntensity` | `number` | 否 | 情感强度 | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加腾讯云 TTS 参数 | #### BytedanceTTS [#bytedancetts] ```typescript new BytedanceTTS(options: BytedanceTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `token` | `string` | 是 | 字节跳动 TTS token | | `appId` | `string` | 是 | 字节跳动 TTS 应用 ID | | `cluster` | `string` | 是 | 字节跳动 TTS cluster | | `voiceType` | `string` | 是 | 字节跳动 TTS 音色类型 | | `speedRatio` | `number` | 否 | 语速比例 | | `volumeRatio` | `number` | 否 | 音量比例 | | `pitchRatio` | `number` | 否 | 音调比例 | | `emotion` | `string` | 否 | 情感 | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加字节跳动 TTS 参数 | #### MicrosoftCNTTS [#microsoftcntts] `sampleRate` 可取 `16000`、`24000` 或 `48000`,并参与数字人采样率校验。 ```typescript new MicrosoftCNTTS(options: MicrosoftCNTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `key` | `string` | 是 | Microsoft Azure 订阅密钥 | | `region` | `string` | 是 | Azure 区域 | | `voiceName` | `string` | 是 | 音色名称 | | `sampleRate` | `16000 \| 24000 \| 48000` | 否 | 采样率,单位 Hz | | `speed` | `number` | 否 | 语速倍率 | | `volume` | `number` | 否 | 音量 | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加 Microsoft TTS 参数 | #### GenericTTS [#generictts] 自定义 OpenAI 兼容 HTTP TTS。`url` 必填,且必须是 HTTP 或 HTTPS 绝对地址;缺失 `url`、地址格式错误或使用 `ws:`、`wss:` 等非 HTTP(S) 协议时,constructor 会抛出错误。合法地址会序列化为 `tts.vendor = "generic_http"`。 ```typescript new GenericTTS(options: GenericTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `url` | `string` | 是 | 自定义 TTS 服务的 HTTP(S) endpoint | | `headers` | `Record` | 否 | 转发给 TTS 服务的自定义 HTTP 请求头;未设置时不会写入 `headers` | | `apiKey` | `string` | 否 | TTS 服务鉴权 API 密钥 | | `model` | `string` | 否 | TTS 模型名 | | `voice` | `string` | 否 | 音色名 | | `speed` | `number` | 否 | 语速 | | `sampleRate` | `number` | 否 | 输出音频采样率,单位为 Hz。如果你的 TTS 服务暂不支持多采样率,请确保返回音频的采样率与该配置一致。 | | `responseFormat` | `"pcm"` | 否 | 输出音频格式;当前 ConvoAI 支持 `pcm` | | `instruction` | `string` | 否 | 语音风格、情绪或其他播报指令 | | `additionalParams` | `Record` | 否 | 透传给 TTS 服务的其他参数;同名字段会被显式字段覆盖 | | `skipPatterns` | `number[]` | 否 | 控制 TTS 跳过特定文本模式 | #### CosyVoiceTTS [#cosyvoicetts] ```typescript new CosyVoiceTTS(options: CosyVoiceTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `apiKey` | `string` | 是 | CosyVoice API 密钥 | | `model` | `string` | 是 | CosyVoice 模型 | | `sampleRate` | `number` | 是 | 采样率,单位 Hz | | `voice` | `string` | 是 | CosyVoice 音色 | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加 CosyVoice TTS 参数 | #### BytedanceDuplexTTS [#bytedanceduplextts] 字节跳动全双工 TTS(`vendor = "bytedance_duplex"`)。 ```typescript new BytedanceDuplexTTS(options: BytedanceDuplexTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `appId` | `string` | 是 | 字节跳动 Duplex TTS 应用 ID | | `token` | `string` | 是 | 字节跳动 Duplex TTS token | | `speaker` | `string` | 是 | 字节跳动 Duplex TTS speaker | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加字节跳动 Duplex TTS 参数 | #### StepFunTTS [#stepfuntts] ```typescript new StepFunTTS(options: StepFunTTSOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `apiKey` | `string` | 是 | StepFun TTS API 密钥 | | `model` | `string` | 是 | StepFun TTS 模型 | | `voiceId` | `string` | 是 | StepFun TTS 音色 id | | `skipPatterns` | `number[]` | 否 | 跳过括号内容的规则配置 | | `additionalParams` | `Record` | 否 | 附加 StepFun TTS 参数 | ### 语音识别服务商 [#stt-vendors] 与 [`withStt()`](#withsttvendor) 配合使用。 #### FengmingSTT [#fengmingstt] 声网自研的「风鸣」STT 服务,无需外部凭据,输出 `asr.vendor = "fengming"`。可选传入 `keywords` 热词列表和 `additionalParams`,这些参数会写入 `asr.params`。 ```typescript new FengmingSTT(options?: FengmingSTTOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `keywords` | `string[]` | 否 | 热词列表,用于提升 ASR 识别准确率 | | `additionalParams` | `Record` | 否 | 附加 Fengming 参数,合并进 `asr.params` | #### TencentSTT [#tencentstt] ```typescript new TencentSTT(options: TencentSTTOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `key` | `string` | 是 | 腾讯云 ASR 参数 `secret_id` | | `appId` | `string` | 是 | 腾讯云 App ID | | `secret` | `string` | 是 | 腾讯云 ASR 参数 `secret_key` | | `engineModelType` | `string` | 是 | 引擎模型类型 | | `voiceId` | `string` | 是 | 会话标识 | | `language` | `string` | 否 | 语言代码 | | `additionalParams` | `Record` | 否 | 附加服务商参数,合并进 `params` | #### MicrosoftCNSTT [#microsoftcnstt] ```typescript new MicrosoftCNSTT(options: MicrosoftCNSTTOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `key` | `string` | 是 | Azure 语音服务密钥 | | `region` | `string` | 是 | Azure 区域,例如 `'chinaeast2'` | | `language` | `string` | 是 | 语言代码,例如 `'zh-CN'` | | `phraseList` | `string[]` | 否 | 提升识别准确率的短语列表 | | `additionalParams` | `Record` | 否 | 附加服务商参数,合并进 `params` | #### StepFunSTT [#stepfunstt] 阶跃星辰 ASR,输出 `asr.vendor = "stepfun"`。`apiKey` 必填且不能为空,否则构造函数抛出错误。识别语言由智能体的 turn detection 配置决定。 ```typescript new StepFunSTT(options: StepFunSTTOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `apiKey` | `string` | 是 | 阶跃星辰 API key,写入 `asr.params.api_key` | | `additionalParams` | `Record` | 否 | 附加 ASR 参数;同名字段由 `apiKey` 覆盖 | ### 数字人服务商 [#avatar-vendors] 与 [`withAvatar()`](#withavatarvendor) 配合使用。数字人服务商会声明所需 TTS 采样率;如果返回 `0`,则不强制要求特定的 TTS 采样率。 #### SensetimeAvatar [#sensetimeavatar] 商汤数字人。如果 `agoraUid`、`appId` 或 `appKey` 为空,构造函数会抛出错误。 ```typescript new SensetimeAvatar(options: SensetimeAvatarOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `agoraUid` | `string` | 是 | 数字人视频流使用的 RTC UID | | `appId` | `string` | 是 | 商汤 App ID(输出为 `appId`) | | `appKey` | `string` | 是 | 商汤 App Key | | `sceneList` | `Record[]` | 是 | 商汤场景列表 | | `agoraToken` | `string` | 否 | 数字人鉴权所用的 RTC token | | `enable` | `boolean` | 否 | 是否启用数字人。默认值:`true` | | `additionalParams` | `Record` | 否 | 附加商汤数字人参数,合并进 `params` | #### SpatiusAvatar [#spatiusavatar] Spatius 数字人。如果 `spatiusApiKey`、`spatiusAppId`、`spatiusAvatarId` 或 `agoraUid` 为空,构造函数会抛出错误。 ```typescript new SpatiusAvatar(options: SpatiusAvatarOptions) ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `spatiusApiKey` | `string` | 是 | Spatius API 密钥 | | `spatiusAppId` | `string` | 是 | Spatius 应用 ID | | `spatiusAvatarId` | `string` | 是 | Spatius 数字人 ID | | `agoraUid` | `string` | 是 | Avatar 视频流对应的 UID | | `region` | `string` | 否 | Spatius 服务区域 | | `agoraToken` | `string` | 否 | Avatar 鉴权 RTC token | | `sampleRate` | `16000 \| 24000` | 否 | 写入 Spatius 服务商参数的音频采样率,单位 Hz | | `sessionExpireMinutes` | `number` | 否 | Spatius 会话过期时间,单位分钟 | | `enable` | `boolean` | 否 | 是否启用数字人。默认值:`true` | | `additionalParams` | `Record` | 否 | 附加 Spatius 数字人参数,合并进 `params` | ## Token 工具 [#token-utilities] 用于生成和管理 token 的辅助函数与类。当你需要精确控制 token 有效期,或在会话之外生成 token 时,可使用这些能力。 ```typescript import { generateConvoAIToken, ExpiresIn } from 'agora-agents'; ``` ### `generateConvoAIToken(options)` [#generateconvoaitokenoptions] 生成一个同时具备 RTC 和 RTM 权限的对话式 AI 引擎 token。这与 SDK 在 app-credentials 模式下自动生成的 token 相同。当你需要在会话之外生成 token,或希望将预生成的 token 传给 [`SessionOptions.token`](#createsessionoptions) 时,可使用该方法。 ```typescript generateConvoAIToken(options: GenerateConvoAITokenOptions): string ``` | 配置项 | 类型 | 是否必填 | 说明 | |---|---|---|---| | `appId` | `string` | 是 | 声网 App ID | | `appCertificate` | `string` | 是 | 声网 App 证书 | | `channelName` | `string` | 是 | token 所授权访问的频道 | | `account` | `string` | 是 | token 颁发给哪个 UID,使用字符串形式表示 | | `tokenExpire` | `number` | 否 | token 有效期,单位秒。默认值:`86400`。有效范围:1–86400 | **返回值:** `string` — 生成后的 token。 ```typescript const token = generateConvoAIToken({ appId: 'your-app-id', appCertificate: 'your-app-certificate', channelName: 'support-room-123', account: '1', tokenExpire: ExpiresIn.hours(12), }); ``` ### `ExpiresIn` [#expiresin] 用于指定 token 有效期的辅助类。可与 [`SessionOptions.expiresIn`](#createsessionoptions) 或 [`generateConvoAIToken`](#generateconvoaitokenoptions) 配合使用。所有值都会经过校验,并受限于声网的最大值 86400 秒(24 小时)。 | 值或方法 | 返回值 | 说明 | |---|---|---| | `ExpiresIn.DAY` | `86400` | 24 小时,即声网允许的最大值,也是默认值 | | `ExpiresIn.hours(n)` | `number` | 返回 `n` 小时对应的秒数。若 `n` ≤ 0 则抛出异常;若超过 24 小时则发出警告并截断至上限 | | `ExpiresIn.minutes(n)` | `number` | 返回 `n` 分钟对应的秒数。若 `n` ≤ 0 则抛出异常;若超过 24 小时则发出警告并截断至上限 | ## 类型与枚举 [#types-and-enums] `AgoraClient`、`Agent`、`AgentSession` 及各服务商类会共用以下类型与枚举。 ### `Area` [#area] 用于 API 路由的区域枚举。通过 `AgoraClient` 的 `area` 选项传入。固定使用 `Area.CN`。 ```typescript import { Area } from 'agora-agents'; ``` | 值 | 区域 | |---|---| | `Area.CN` | 中国大陆 | `Area.CN` 的路由信息: | 项目 | 值 | |---|---| | 主区域前缀 | `api-cn-east-1` | | 备用区域前缀 | `api-cn-north-1` | | 主域名后缀 | `sd-rtn.com` | | 备用域名后缀 | `agora.io` | | 请求路径 | `/cn/api/conversational-ai-agent` | ### `AgoraAuthMode` [#agoraauthmode] 表示 `AgoraClient` 实例上的已解析鉴权模式,可通过 `client.authMode` 读取。 ```typescript type AgoraAuthMode = "app-credentials" | "token" | "basic"; ``` | 值 | 说明 | |---|---| | `"app-credentials"` | 提供了 App ID 和 App 证书,SDK 自动生成 token | | `"token"` | 提供了预先构造的 `authToken` | | `"basic"` | 提供了 `customerId` 和 `customerSecret` | ### `AgentSessionEvent` [#agentsessionevent] `session.on()` 和 `session.off()` 可用的所有事件名的联合类型。 ```typescript type AgentSessionEvent = "started" | "stopped" | "error"; ``` ### `AgentSessionEventHandler` [#agentsessioneventhandler] 会话事件回调的泛型 handler 类型。 ```typescript type AgentSessionEventHandler = (data: T) => void; ``` | 事件 | `T` | |---|---| | `"started"` | `{ agentId: string }` | | `"stopped"` | `{ agentId: string }` | | `"error"` | `Error` | ### `SpeakPriority` [#speakpriority] 用于控制智能体在处理 [`say()`](#saytext-options) 调用时,如何与当前活动状态交互。 ```typescript type SpeakPriority = "INTERRUPT" | "APPEND" | "IGNORE"; ``` | 值 | 说明 | |---|---| | `"INTERRUPT"` | 智能体立即停止当前播报并输出该消息 | | `"APPEND"` | 将消息加入队列,待当前播报结束后输出 | | `"IGNORE"` | 如果智能体当前正在播报,则直接丢弃该消息 | ### `AgoraError` [#agoraerror] 当 API 返回 4xx 或 5xx 响应时抛出。可捕获该错误以检查状态码和响应包体。 ```typescript import { AgoraError } from 'agora-agents'; try { const agentId = await session.start(); } catch (err) { if (err instanceof AgoraError) { console.error('Status:', err.statusCode); console.error('Message:', err.message); console.error('Body:', err.body); } } ``` | 属性 | 类型 | 说明 | |---|---|---| | `statusCode` | `number` | API 返回的 HTTP 状态码 | | `message` | `string` | 可读的错误消息 | | `body` | `unknown` | 原始响应包体 |