API 概览

AgoraClientCopy Anchor Link

AgoraClient 是 SDK 的入口，用于管理区域路由、鉴权和 API 访问。

import { AgoraClient, Area } from 'agora-agents';

构造函数Copy Anchor Link

const client = new AgoraClient(options: AgoraClient.Options);

鉴权模式会根据你提供的参数自动解析。

鉴权模式根据你提供的参数解析如下：

各鉴权模式的详细说明可参考实现 HTTP 安全认证。

属性Copy Anchor Link

任意 AgoraClient 实例都提供以下只读属性。

方法Copy Anchor Link

除基础 API 访问能力外，还提供以下高层方法。

agent(options?)Copy Anchor Link

创建一个绑定到当前客户端的 Agent。这样无需在 Agent 构造函数里再次传入 client。

const agent = client.agent({ turnDetection: { language: 'zh-CN' } });

nextRegion()Copy Anchor Link

将域名池切换到下一个区域前缀。通常在请求失败后调用，以尝试其他区域端点。

client.nextRegion();

selectBestDomain(signal?)Copy Anchor Link

手动触发一次 DNS 解析检测，以选择最优的域名后缀。SDK 默认每 30 秒自动执行一次，你也可以手动调用。

await client.selectBestDomain();

getCurrentURL()Copy Anchor Link

返回当前正在使用的完整 API URL，类型为 string。

const url = client.getCurrentURL();
// Example: 'https://api-cn-east-1.sd-rtn.com/cn/api/conversational-ai-agent'

子客户端Copy Anchor Link

AgoraClient 也暴露了原始 API 客户端，便于访问尚未被 Agent 或 AgentSession 封装的接口。大多数场景下，建议优先使用 Agent 和 AgentSession 这套高层 API。

完整的方法签名和请求参数可参考创建对话式智能体 RESTful API。

AgentCopy Anchor Link

Agent 是一个不可变的配置对象。每个构建方法都会返回一个新的 Agent 实例，原对象不会被修改。建议在应用启动时定义一个 Agent，并在每次用户对话时基于它调用 createSession()。

在构造时通过 new Agent({ client, ... })（或 client.agent(...)）绑定 AgoraClient，createSession() 会复用该客户端，因此创建会话时无需再传入客户端。智能体实例名不在 Agent 构造函数上设置，而是在 createSession({ name }) 时传入。

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 });

构造函数Copy Anchor Link

new Agent<TTSSampleRate extends number = number>(options?: AgentOptions)

所有选项均为可选项。创建后可通过 构建方法 配置各服务商。

instructions、greeting、failureMessage、maxHistory、greetingConfigs 是兼容性字段。新代码应在 LLM 服务商上配置这些值，以匹配核心请求 schema。

构建方法Copy Anchor Link

所有构建方法都会返回一个新的 Agent 实例，原对象不会被修改。

仅支持级联式 ASR + LLM + TTS 流水线以及服务商。

withLlm(vendor)Copy Anchor Link

设置 LLM 服务商。传入任意 LLM 服务商 class（AliyunLLM、BytedanceLLM、DeepSeekLLM、TencentLLM 或 CustomLLM）的实例。

withLlm(vendor: BaseCNLLM): Agent<TTSSampleRate>

withTts(vendor)Copy Anchor Link

设置 TTS 服务商。该方法会捕获并追踪采样率类型，以便进行数字人兼容性校验。

withTts<SR extends number>(vendor: BaseCNTTS<SR>): Agent<SR>

withStt(vendor)Copy Anchor Link

设置 STT 服务商。可传入任意 STT 服务商 class 的实例。

withStt(vendor: BaseCNSTT): Agent<TTSSampleRate>

withAvatar(vendor)Copy Anchor Link

设置数字人服务商。这里的 this 约束会在编译阶段校验该 Agent 的 TTS 采样率是否满足数字人要求。需要使用级联式 ASR + LLM + TTS 流水线。

withAvatar<RequiredSR extends number>(
  this: Agent<RequiredSR>,
  vendor: BaseCNAvatar<RequiredSR>
): Agent<RequiredSR>

withTurnDetection(config)Copy Anchor Link

配置级联流程中的 turn detection。使用 config.start_of_speech 和 config.end_of_speech 配置 SOS/EOS 检测。打断行为请使用 withInterruption()。

withTurnDetection(config: TurnDetectionConfig): Agent<TTSSampleRate>

withInterruption(config)Copy Anchor Link

通过顶层 interruption 对象配置统一打断行为。适用于 start_of_speech 和 keywords 两类打断模式。

withInterruption(config: InterruptionConfig): Agent<TTSSampleRate>

withInstructions(text)Copy Anchor Link

已废弃。请改用 LLM 服务商的 systemMessages。在新的 Agent 实例上覆盖 LLM 系统提示词。

withInstructions(instructions: string): Agent<TTSSampleRate>

withGreeting(text)Copy Anchor Link

已废弃。请改用 LLM 服务商的 greetingMessage。在新的 Agent 实例上覆盖问候语。

withGreeting(greeting: string): Agent<TTSSampleRate>

其他构建方法Copy Anchor Link

以下方法遵循相同模式，都会返回一个包含更新后配置的新 Agent 实例。

createSession(options)Copy Anchor Link

使用构造 Agent 时绑定的客户端创建一个绑定到频道的 AgentSession。该方法不会立即启动智能体，需调用 session.start() 才会加入频道。

如果构造 Agent 时未传入 client，调用 createSession() 会抛出错误。

createSession(
  options: SessionOptions,
): AgentSession

const session = agent.createSession({
  name: 'support-agent',
  channel: 'support-room',
  agentUid: '1',
  remoteUids: ['100'],
});

name 为智能体实例名，会发送给声网 API。请在 createSession() 上设置，而不要设置在 Agent 上；省略时自动生成 agent-{timestamp}。

SessionOptions 字段如下：

各服务商均为 BYOK，需要提供对应服务商的凭据。

属性Copy Anchor Link

任意 Agent 实例都提供以下只读属性。

toProperties(opts)Copy Anchor Link

高级方法，用于将 Agent 配置转换为 Start Agent API 所需的请求结构。AgentSession.start() 内部会调用该方法；除非你需要自行构造请求体，否则通常无需直接调用。

toProperties(opts): StartAgentsRequest.Properties

类型别名Copy Anchor Link

SDK 公开了常用请求与响应类型的别名，包括 LlmConfig、SttConfig、AsrConfig（即 SttConfig）、AvatarConfig、会话/对话相关类型，以及 think 类型（例如 ThinkOnListeningAction）。

FillerWordsConfig 支持静态承接词和动态承接词。使用动态承接词时，必须同时配置非空的静态短语作为回退；generated_config 中的 prompt、上下文限制和回退策略均为可选项，模型服务和凭证由声网托管。具体字段结构详见配置承接词。

动态承接词配置还支持 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) 开启工具调用。

AgentSessionCopy Anchor Link

AgentSession 负责管理运行中智能体的完整生命周期。请通过 agent.createSession() 创建会话，而不要直接调用构造函数。

import { AgentSession } from 'agora-agents';

通过 SessionOptions 的 name 字段设置发送给声网 API 的智能体实例名；省略时自动生成 agent-{timestamp}。

状态机Copy Anchor Link

会话状态会按以下流程推进：

idle ──► starting ──► running ──► stopping ──► stopped
                         │
                         ▼
                       error

在 stopped 或 error 状态下，也可以再次调用 start() 以重启会话。

方法Copy Anchor Link

AgentSession 实例提供以下方法。

start()Copy Anchor Link

启动智能体会话。如果未提供 token，则自动生成 token，随后发送启动请求并返回智能体 ID。

start(): Promise<string>

• 状态流转：idle / stopped / error → starting → running
• 若在 starting、running 或 stopping 状态下调用，则抛出异常
• 若数字人配置无效（例如 TTS 采样率不匹配），则抛出异常
• 各服务商均为 BYOK，会按 Agent 上配置的服务商凭据发送配置

stop()Copy Anchor Link

停止智能体会话，并让智能体退出频道。如果智能体已经停止，例如由于空闲超时自动退出，则该方法会静默返回，而不会因为 404 报错。

stop(): Promise<void>

• 状态流转：running → stopping → stopped
• 仅可在 running 状态下调用，否则抛出异常

say(text, options?)Copy Anchor Link

指示智能体播报指定文本。

say(text: string, options?: SayOptions): Promise<void>

• 仅在 running 状态下有效

interrupt()Copy Anchor Link

打断智能体当前正在播报的内容。

interrupt(): Promise<void>

• 仅在 running 状态下有效

update(config)Copy Anchor Link

在不重启会话的情况下，更新会话中的智能体配置。该方法接收 REST API 格式的部分配置对象。

update(config: AgentConfigUpdate): Promise<void>

• 仅在 running 状态下有效

getHistory()Copy Anchor Link

获取当前会话的对话历史。该方法要求已有有效的智能体 ID，也就是 start() 必须已成功调用。

getHistory(): Promise<ConversationHistory>

getTurns(options?)Copy Anchor Link

获取当前会话的逐轮分析数据，包括开始/结束事件以及延迟指标。该方法要求已有有效的智能体 ID，且 start() 已成功调用。

getTurns(options?: GetTurnsOptions): Promise<ConversationTurns>

• options.page_index：页码，从 1 开始
• options.page_size：每页返回的轮次数量

getAllTurns(options?)Copy Anchor Link

获取所有轮次分析分页，并合并 turns 数组。该方法要求已有有效的智能体 ID，且 start() 已成功调用。

getAllTurns(options?: Omit<GetTurnsOptions, "page_index">): Promise<ConversationTurns>

• 要求存在有效的 agentId
• 对于超长会话，建议使用 getTurns() 按页处理，以避免一次性将所有数据加载到内存中

getInfo()Copy Anchor Link

从 API 获取当前智能体的元数据。该方法要求已有有效的智能体 ID。

getInfo(): Promise<SessionInfo>

on(event, handler)Copy Anchor Link

订阅会话事件。建议在调用 start() 之前注册 handler，以避免错过 started 事件。

on<T>(event: AgentSessionEvent, handler: AgentSessionEventHandler<T>): void

off(event, handler)Copy Anchor Link

取消订阅此前注册的事件 handler。

off<T>(event: AgentSessionEvent, handler: AgentSessionEventHandler<T>): void

事件Copy Anchor Link

会话会发出以下事件。类型详情可参考 AgentSessionEvent 和 AgentSessionEventHandler。

属性Copy Anchor Link

任意 AgentSession 实例都提供以下只读属性。

使用 session.rawCopy Anchor Link

你可以通过 session.raw 调用尚未被高层 API 封装的接口：

await session.raw.someNewEndpoint({
  appid: session.appId,
  agentId: session.id!,
});

使用 raw 方法时，需要手动传入 appid 和 agentId。

自带密钥（BYOK）Copy Anchor Link

建议优先在 Agent builder 上配置服务商。各服务商均为 BYOK，需要显式提供对应服务商的凭据。

• 在 builder 上为各服务商显式提供凭据

服务商Copy Anchor Link

服务商类均从 agora-agents 导入。将这些服务商实例传给 Agent 构建方法 即可。

import {
  AliyunLLM, BytedanceLLM, DeepSeekLLM, TencentLLM, CustomLLM,
  MiniMaxCNTTS, TencentTTS, BytedanceTTS, MicrosoftCNTTS,
  CosyVoiceTTS, BytedanceDuplexTTS, StepFunTTS, GenericTTS,
  FengmingSTT, TencentSTT, MicrosoftCNSTT,
  SensetimeAvatar, SpatiusAvatar,
} from 'agora-agents';

采用 STT → LLM → TTS 的级联流程。所有服务商均为 BYOK，需要提供对应服务商的凭据。constructor 在必填字段缺失时会抛出错误。

LLM 服务商Copy Anchor Link

与 withLlm() 配合使用。LLM helper 均基于 OpenAI 兼容协议（style = "openai"），共享同一套构造参数，区别仅在于内部写入的 vendor 标识。CN 场景下这些 helper 均为 BYOK，url、model 和 apiKey 均为必填。

以上 helper 共用相同的构造参数：

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',
});

tools 用于声明供 LLM 选择调用的自定义工具。每个工具包含模型可见的函数定义，以及同步 GET 或 POST 请求的服务端配置；withTools(true) 同时适用于 tools 和 MCP 服务器配置。

语音合成服务商Copy Anchor Link

与 withTts() 配合使用。sampleRate（或对应字段）决定数字人兼容性，详见 withAvatar()。所有 TTS 类均支持 skipPatterns 和 additionalParams。

MiniMaxCNTTSCopy Anchor Link

MiniMax TTS 为 BYOK，始终要求 key 和 model。此外必须提供 voiceSetting.voice_id 或非空的 timberWeights 之一。

new MiniMaxCNTTS(options: MiniMaxCNTTSOptions)

MiniMaxCNVoiceSetting 字段：voice_id（必填）、speed?、vol?、pitch?、emotion?、latex_read?、english_normalization?。MiniMaxCNTimberWeight 字段：voice_id、weight。

TencentTTSCopy Anchor Link

new TencentTTS(options: TencentTTSOptions)

BytedanceTTSCopy Anchor Link

new BytedanceTTS(options: BytedanceTTSOptions)

MicrosoftCNTTSCopy Anchor Link

sampleRate 可取 16000、24000 或 48000，并参与数字人采样率校验。

new MicrosoftCNTTS<SR extends MicrosoftCNSampleRate>(options: MicrosoftCNTTSOptions<SR>)

GenericTTSCopy Anchor Link

自定义 OpenAI 兼容 HTTP TTS。url 必填，且必须是 HTTP 或 HTTPS 绝对地址；缺失 url、地址格式错误或使用 ws:、wss: 等非 HTTP(S) 协议时，constructor 会抛出错误。合法地址会序列化为 tts.vendor = "generic_http"。

new GenericTTS(options: GenericTTSOptions)

CosyVoiceTTSCopy Anchor Link

new CosyVoiceTTS(options: CosyVoiceTTSOptions)

BytedanceDuplexTTSCopy Anchor Link

字节跳动全双工 TTS（vendor = "bytedance_duplex"）。

new BytedanceDuplexTTS(options: BytedanceDuplexTTSOptions)

StepFunTTSCopy Anchor Link

new StepFunTTS(options: StepFunTTSOptions)

语音识别服务商Copy Anchor Link

与 withStt() 配合使用。

FengmingSTTCopy Anchor Link

声网自研的「风鸣」STT 服务，无需外部凭据，输出 asr.vendor = "fengming"。可选传入 keywords 热词列表和 additionalParams，这些参数会写入 asr.params。

new FengmingSTT(options?: FengmingSTTOptions)

TencentSTTCopy Anchor Link

new TencentSTT(options: TencentSTTOptions)

MicrosoftCNSTTCopy Anchor Link

new MicrosoftCNSTT(options: MicrosoftCNSTTOptions)

数字人服务商Copy Anchor Link

与 withAvatar() 配合使用。数字人服务商会声明所需 TTS 采样率；如果返回 0，则不强制要求特定的 TTS 采样率。

SensetimeAvatarCopy Anchor Link

商汤数字人。如果 agoraUid、appId 或 appKey 为空，构造函数会抛出错误。

new SensetimeAvatar(options: SensetimeAvatarOptions)

SpatiusAvatarCopy Anchor Link

Spatius 数字人。如果 spatiusApiKey、spatiusAppId、spatiusAvatarId 或 agoraUid 为空，构造函数会抛出错误。

new SpatiusAvatar(options: SpatiusAvatarOptions)

Token 工具Copy Anchor Link

用于生成和管理 token 的辅助函数与类。当你需要精确控制 token 有效期，或在会话之外生成 token 时，可使用这些能力。

import { generateConvoAIToken, ExpiresIn } from 'agora-agents';

generateConvoAIToken(options)Copy Anchor Link

生成一个同时具备 RTC 和 RTM 权限的对话式 AI 引擎 token。这与 SDK 在 app-credentials 模式下自动生成的 token 相同。当你需要在会话之外生成 token，或希望将预生成的 token 传给 SessionOptions.token 时，可使用该方法。

generateConvoAIToken(options: GenerateConvoAITokenOptions): string

返回值： string — 生成后的 token。

const token = generateConvoAIToken({
  appId: 'your-app-id',
  appCertificate: 'your-app-certificate',
  channelName: 'support-room-123',
  account: '1',
  tokenExpire: ExpiresIn.hours(12),
});

ExpiresInCopy Anchor Link

用于指定 token 有效期的辅助类。可与 SessionOptions.expiresIn 或 generateConvoAIToken 配合使用。所有值都会经过校验，并受限于声网的最大值 86400 秒（24 小时）。

类型与枚举Copy Anchor Link

AgoraClient、Agent、AgentSession 及各服务商类会共用以下类型与枚举。

AreaCopy Anchor Link

用于 API 路由的区域枚举。通过 AgoraClient 的 area 选项传入。固定使用 Area.CN。

import { Area } from 'agora-agents';

Area.CN 的路由信息：

AgoraAuthModeCopy Anchor Link

表示 AgoraClient 实例上的已解析鉴权模式，可通过 client.authMode 读取。

type AgoraAuthMode = "app-credentials" | "token" | "basic";

AgentSessionEventCopy Anchor Link

session.on() 和 session.off() 可用的所有事件名的联合类型。

type AgentSessionEvent = "started" | "stopped" | "error";

AgentSessionEventHandlerCopy Anchor Link

会话事件回调的泛型 handler 类型。

type AgentSessionEventHandler<T> = (data: T) => void;

SpeakPriorityCopy Anchor Link

用于控制智能体在处理 say() 调用时，如何与当前活动状态交互。

type SpeakPriority = "INTERRUPT" | "APPEND" | "IGNORE";

AgoraErrorCopy Anchor Link

当 API 返回 4xx 或 5xx 响应时抛出。可捕获该错误以检查状态码和响应包体。

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);
  }
}