需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

API 概览

  • Python

更新时间不可用

声网对话式 AI 引擎 Python SDK 的完整 API 参考，包括 Agora、AsyncAgora、Agent、AgentSession 以及各类服务商类。

Agora / AsyncAgora 客户端

Agora（同步）和 AsyncAgora（异步）是 SDK 的入口，用于管理区域路由、鉴权和 API 访问。

Python
from agora_agent import Agora, Area
client = Agora(
    area=Area.CN,
    app_id='your-app-id',
    app_certificate='your-app-certificate',
)

可参考 同步 vs. 异步 选择适合你应用的客户端。

构造函数

Python
Agora(
    area: Area,
    app_id: str = None,
    app_certificate: str = None,
    username: str = None,
    password: str = None,
    auth_token: str = None,
    headers: Dict[str, str] = None,
    timeout: float = 60,
    follow_redirects: bool = True,
    httpx_client: httpx.Client = None,
)

在 app-credentials 模式下传入 app_id + app_certificate，或在 Basic Auth 模式下传入 username + password。

参数类型是否必填默认值说明
areaArea是—API 路由所使用的区域
app_idstr是*—声网 App ID
app_certificatestr是*—声网 App 证书（app-credentials 模式）。请妥善保管，切勿暴露到客户端
usernamestr是*—客户 ID（Basic Auth 模式）
passwordstr是*—客户密钥（Basic Auth 模式）
auth_tokenstr否—预先构造好的 agora token=<value> 字符串
headersDict[str, str]否None每次请求都会附带的额外 Header
timeoutfloat否60请求超时时间，单位为秒
follow_redirectsbool否True是否跟随 HTTP 重定向
httpx_clienthttpx.Client否None自定义 httpx 客户端实例
表格内容超出当前宽度，可横向滚动查看更多列。

* app_id + app_certificate 与 username + password 二选一提供。

鉴权模式会根据你传入的参数自动解析：

传入的参数解析后的模式
app_id + app_certificate"app-credentials"
auth_token"token"
username + password"basic"
表格内容超出当前宽度，可横向滚动查看更多列。

AsyncAgora 的构造签名与之相同，只是 httpx_client 接收 httpx.AsyncClient 而不是 httpx.Client。

Python
from agora_agent import AsyncAgora, Area
client = AsyncAgora(
    area=Area.CN,
    app_id='your-app-id',
    app_certificate='your-app-certificate',
)

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

属性

pool

访问底层 Pool 对象，以便进行高级域名管理。

Python
pool = client.pool
pool.get_area()  # Area.CN
  • 返回值： Pool

方法

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

next_region()

将域名池切换到下一个区域前缀。通常在请求失败后调用，以尝试其他区域端点。对 Agora 和 AsyncAgora 都是同步方法。

Python
client.next_region()

select_best_domain()

触发基于 DNS 的域名优选，以选出响应最快的域名后缀。结果会缓存 30 秒。

Python
# Sync (Agora)
client.select_best_domain()

# Async (AsyncAgora) — requires await
await client.select_best_domain()

get_current_url()

返回当前正在使用的完整 API URL，类型为 str。对 Agora 和 AsyncAgora 都是同步方法。

Python
url = client.get_current_url()
# Example: 'https://api-cn-east-1.sd-rtn.com/cn/api/conversational-ai-agent'

子客户端

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

属性同步类型异步类型说明
client.agentsAgentsClientAsyncAgentsClient启动、停止、查询列表、更新智能体
表格内容超出当前宽度，可横向滚动查看更多列。

子客户端会在首次访问时懒加载。大多数场景下，建议优先使用 AgentSession API，而不是直接调用 client.agents。

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

Agent

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

在构造时通过 Agent(client=client, ...) 绑定 Agora 客户端，create_session() 和 create_async_session() 会复用该客户端，因此后续创建会话时无需再传入客户端。智能体实例名不在 Agent 构造函数上设置，而是在 create_session(name=...) 时传入。传入 Area.CN 的客户端时，SDK 会自动选用 CNAgent（仅用于 IDE 提示，SDK 不会强制校验服务商与区域是否匹配）。

Python
from agora_agent import Agent, Agora, Area

client = Agora(area=Area.CN, app_id='your-app-id', app_certificate='your-app-certificate')
agent = Agent(client=client)

构造函数

Python
Agent(
    client: Optional[Any] = None,
    instructions: Optional[str] = None,
    turn_detection: Optional[TurnDetectionConfig] = None,
    interruption: Optional[InterruptionConfig] = None,
    sal: Optional[SalConfig] = None,
    advanced_features: Optional[Dict[str, Any]] = None,
    parameters: Optional[SessionParams] = None,
    greeting: Optional[str] = None,
    failure_message: Optional[str] = None,
    max_history: Optional[int] = None,
    geofence: Optional[GeofenceConfig] = None,
    labels: Optional[Dict[str, str]] = None,
    rtc: Optional[RtcConfig] = None,
    filler_words: Optional[FillerWordsConfig] = None,
)

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

参数类型默认值说明
clientOptional[Any]None绑定的 Agora 客户端，供 create_session() 和 create_async_session() 复用
instructionsOptional[str]NoneLLM 系统提示词
turn_detectionOptional[TurnDetectionConfig]None语音活动检测配置
interruptionOptional[InterruptionConfig]None统一打断控制配置
salOptional[SalConfig]None选择性注意力锁定配置
advanced_featuresOptional[Dict[str, Any]]None高级特性，例如 {'enable_rtm': True}
parametersOptional[SessionParams]None额外的会话参数
greetingOptional[str]None智能体入会后自动播报的问候语
failure_messageOptional[str]NoneLLM 调用失败时播报的消息
max_historyOptional[int]None保留在 LLM 上下文中的最大对话轮次数
geofenceOptional[GeofenceConfig]None区域访问限制
labelsOptional[Dict[str, str]]None会在通知回调中返回的自定义键值标签
rtcOptional[RtcConfig]NoneRTC 媒体加密配置
filler_wordsOptional[FillerWordsConfig]None等待 LLM 响应期间播放的承接词配置
表格内容超出当前宽度，可横向滚动查看更多列。

构建方法

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

with_llm(vendor)

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

Python
with_llm(vendor: BaseLLM) -> Agent

with_tts(vendor)

设置 TTS 服务商。该方法会记录服务商的 sample_rate，用于进行数字人校验。

Python
with_tts(vendor: BaseTTS) -> Agent

with_stt(vendor)

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

Python
with_stt(vendor: BaseSTT) -> Agent

with_avatar(vendor)

设置数字人服务商。如果 TTS 采样率与数字人要求的采样率不一致，会抛出 ValueError。

Python
with_avatar(vendor: BaseAvatar) -> Agent

异常： ValueError — 当 TTS 采样率与数字人的 required_sample_rate 不匹配时抛出。

with_turn_detection(config)

配置级联流程中的 SOS/EOS 语音活动检测。使用 config.start_of_speech 和 config.end_of_speech 配置 SOS/EOS 检测；打断行为请使用 with_interruption()。

Python
with_turn_detection(config: TurnDetectionConfig) -> Agent

with_interruption(config)

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

Python
with_interruption(config: InterruptionConfig) -> Agent

with_instructions(instructions)

在新的 Agent 实例上覆盖 LLM 系统提示词。

Python
with_instructions(instructions: str) -> Agent

with_greeting(greeting)

在新的 Agent 实例上覆盖问候语。

Python
with_greeting(greeting: str) -> Agent

其他构建方法

以下方法遵循相同模式，每次调用都会返回一个带有更新后配置的新 Agent 实例。

方法参数类型说明
with_sal(config)SalConfig设置选择性注意力锁定配置
with_advanced_features(features)Dict[str, Any]设置高级特性
with_tools(enabled)bool启用或禁用 MCP 和自定义工具调用
with_parameters(parameters)SessionParams设置会话参数。parameters.audio_scenario 可设为 default、chorus 或 aiserver；未设置时，SDK 会自动补成 chorus
with_failure_message(message)str设置 LLM 失败时播报的消息
with_max_history(n)int设置最大对话历史长度
with_geofence(geofence)GeofenceConfig设置区域访问限制配置
with_labels(labels)Dict[str, str]设置自定义标签
with_rtc(rtc)RtcConfig设置 RTC 配置
with_filler_words(filler_words)FillerWordsConfig设置承接词配置
表格内容超出当前宽度，可横向滚动查看更多列。

create_session()

使用已绑定到 Agent(client=...) 的客户端创建一个 AgentSession。该方法不会启动智能体，需调用 session.start() 让其入会。智能体实例名通过 name 参数在此传入，会在会话启动时发送给 Start Agent API。

Python
create_session(
    channel: str,
    agent_uid: str,
    remote_uids: List[str],
    name: Optional[str] = None,
    token: Optional[str] = None,
    idle_timeout: Optional[int] = None,
    enable_string_uid: Optional[bool] = None,
    expires_in: Optional[int] = None,
) -> AgentSession

create_session() 字段说明：

参数类型是否必填说明
channelstr是需要加入的频道名
agent_uidstr是智能体的 RTC UID
remote_uidsList[str]是智能体要监听并响应的远端用户 UID 列表
nameOptional[str]否发送给 Start Agent API 的智能体实例名。省略时 SDK 自动生成 agent-{timestamp}
tokenOptional[str]否预先构造好的 RTC+RTM token。不传则基于应用凭据自动生成
expires_inOptional[int]否token 有效期，单位为秒。仅在自动生成 token 时生效。有效范围为 1–86400。可使用 expires_in_hours() 提升可读性
idle_timeoutOptional[int]否未检测到音频时，智能体自动退出前的秒数
enable_string_uidOptional[bool]否使用字符串 UID 而不是数值 UID
表格内容超出当前宽度，可横向滚动查看更多列。

create_session() 要求构造 Agent 时已传入 client=...。若未绑定客户端，会抛出 ValueError。

Python
session = agent.create_session(
    channel='support-room',
    agent_uid='1',
    remote_uids=['100'],
    name='support-agent',
)

create_async_session() 与 create_session() 等价，但返回 AsyncAgentSession，供 AsyncAgora 使用。同样在 name=... 传入智能体实例名，省略时生成 agent-{timestamp}。

to_properties()

将智能体配置转换为供 Agora API 使用的 StartAgentsRequestProperties 对象。AgentSession.start() 内部会调用该方法。

Python
to_properties(
    channel: str,
    agent_uid: str,
    remote_uids: List[str],
    idle_timeout: Optional[int] = None,
    enable_string_uid: Optional[bool] = None,
    token: Optional[str] = None,
    app_id: Optional[str] = None,
    app_certificate: Optional[str] = None,
    expires_in: Optional[int] = None,
) -> StartAgentsRequestProperties

异常： ValueError — 当既未提供 token，也未提供 app_id+app_certificate，或在级联模式下缺少必需服务商（LLM、TTS）时抛出。

属性

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

属性类型说明
instructionsOptional[str]LLM 系统提示词
greetingOptional[str]问候语
failure_messageOptional[str]LLM 失败时播报的消息
max_historyOptional[int]最大对话历史长度
llmOptional[Dict[str, Any]]LLM 配置字典（来自 to_config()）
ttsOptional[Dict[str, Any]]TTS 配置字典
sttOptional[Dict[str, Any]]STT 配置字典
avatarOptional[Dict[str, Any]]数字人配置字典
turn_detectionOptional[TurnDetectionConfig]轮次检测配置
interruptionOptional[InterruptionConfig]统一打断控制配置
salOptional[SalConfig]SAL 配置
advanced_featuresOptional[Dict[str, Any]]高级特性
parametersOptional[SessionParams]会话参数
geofenceOptional[GeofenceConfig]区域访问限制配置
labelsOptional[Dict[str, str]]自定义标签
rtcOptional[RtcConfig]RTC 配置
filler_wordsOptional[FillerWordsConfig]承接词配置
configDict[str, Any]完整配置快照
表格内容超出当前宽度，可横向滚动查看更多列。

类型别名

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

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

动态承接词配置还支持 context_message_limit（取值范围 1 到 6，省略时由服务按 1 处理）和 history_character_limit（取值范围 0 到 10000，省略时由服务按 1000 处理）。前者包含当前用户消息，显式设置为 2 到 6 时启用近期历史；后者只统计历史消息文本的 Unicode code points。

Think 值常量包括：ThinkOnListeningActionInject、ThinkOnListeningActionInterrupt、ThinkOnListeningActionAppend、ThinkOnListeningActionIgnore、ThinkOnThinkingActionInterrupt、ThinkOnThinkingActionAppend、ThinkOnThinkingActionIgnore、ThinkOnSpeakingActionInterrupt、ThinkOnSpeakingActionAppend、ThinkOnSpeakingActionIgnore。append 不打断当前交互，分别等待当前用户回合、LLM 推理或 TTS 播报完成后，再将该指令作为独立的 user 消息追加到上下文并发起新一轮对话。

公开类型别名还包括 FillerWordsContentGeneratedConfig 以及自定义工具相关的 LlmToolConfig、LlmToolFunctionConfig、LlmToolFunctionParametersConfig、LlmToolExecutionConfig 和 LlmToolServerConfig。

AgentSession / AsyncAgentSession

AgentSession（同步）和 AsyncAgentSession（异步）负责管理运行中智能体的完整生命周期。通常通过 agent.create_session() 获取会话；也可在高级场景下直接构造。

Python
from agora_agent import AgentSession
from agora_agent import AsyncAgentSession
# or from top-level:
from agora_agent import AgentSession, AsyncAgentSession

构造函数

通常通过 Agent.create_session() 创建会话。高级场景下也可以直接构造：

Python
AgentSession(
    client: Any,
    agent: Agent,
    app_id: str,
    name: str,
    channel: str,
    agent_uid: str,
    remote_uids: List[str],
    app_certificate: Optional[str] = None,
    token: Optional[str] = None,
    idle_timeout: Optional[int] = None,
    enable_string_uid: Optional[bool] = None,
)

AsyncAgentSession 的构造签名与之相同。

参数类型是否必填说明
clientAgora 或 AsyncAgora是已完成鉴权的客户端
agentAgent是智能体配置
app_idstr是声网 App ID
namestr是发送给 Start Agent API 的智能体实例名
channelstr是频道名
agent_uidstr是智能体的 UID
remote_uidsList[str]是远端参与者 UID 列表
app_certificateOptional[str]否App 证书（用于自动生成 token）
tokenOptional[str]否预先构造好的 RTC token
idle_timeoutOptional[int]否空闲超时时间，单位为秒
enable_string_uidOptional[bool]否是否启用字符串 UID
表格内容超出当前宽度，可横向滚动查看更多列。

方法

以下方法同时适用于 AgentSession 和 AsyncAgentSession。其中涉及 API 调用的方法，在 AsyncAgentSession 上需要使用 await。

start()

启动智能体会话。如果未提供 RTC token，则自动生成；会校验数字人与 TTS 配置；随后调用 Agora API。

同步 (AgentSession)异步 (AsyncAgentSession)
签名start() -> strasync start() -> str
返回值智能体 ID智能体 ID
异常不处于 idle、stopped 或 error 状态时抛出 RuntimeError同左
异常数字人与 TTS 的采样率不匹配时抛出 ValueError同左
表格内容超出当前宽度，可横向滚动查看更多列。
Python
# Sync
agent_id = session.start()

# Async
agent_id = await session.start()

stop()

停止智能体会话，并将智能体从频道中移除。如果智能体实际上已停止（API 返回 404），会直接切换到 stopped 状态，不会抛错。

同步异步
签名stop() -> Noneasync stop() -> None
异常不处于 running 状态时抛出 RuntimeError同左
表格内容超出当前宽度，可横向滚动查看更多列。
Python
# Sync
session.stop()

# Async
await session.stop()

say(text, priority=None, interruptable=None)

让智能体播报指定文本。

同步异步
签名say(text: str, priority: Optional[str] = None, interruptable: Optional[bool] = None) -> None同左，使用 async
异常不处于 running 状态时抛出 RuntimeError同左
表格内容超出当前宽度，可横向滚动查看更多列。
参数类型是否必填说明
textstr是要播报的文本
prioritystr否INTERRUPT、APPEND 或 IGNORE
interruptablebool否该消息是否允许被打断
表格内容超出当前宽度，可横向滚动查看更多列。
Python
# Sync
session.say('One moment while I look that up.', priority='INTERRUPT', interruptable=False)

# Async
await session.say('One moment while I look that up.', priority='INTERRUPT', interruptable=False)

interrupt()

在智能体说话或思考时进行打断。

同步异步
签名interrupt() -> Noneasync interrupt() -> None
异常不处于 running 状态时抛出 RuntimeError同左
表格内容超出当前宽度，可横向滚动查看更多列。
Python
# Sync
session.interrupt()

# Async
await session.interrupt()

update(properties)

在不中断会话的情况下动态更新智能体配置。接收 REST API 格式的部分 properties 对象。

同步异步
签名update(properties: Any) -> Noneasync update(properties: Any) -> None
异常不处于 running 状态时抛出 RuntimeError同左
表格内容超出当前宽度，可横向滚动查看更多列。
Python
from agora_agent.agents.types import UpdateAgentsRequestProperties

# Sync
session.update(properties)

# Async
await session.update(properties)

think(text, ...)

向运行中的智能体注入一条自定义文本指令。

在 API v2.7 中，如果省略 on_listening_action，服务端默认使用 interrupt。如需保留 v2.7 之前的行为，请显式传入 on_listening_action='inject'。

on_listening_action、on_thinking_action 和 on_speaking_action 均支持 append。该值不会打断当前交互，分别等待当前用户回合、LLM 推理或 TTS 播报完成后处理该指令。

Python
session.think(
    'Summarize the last answer',
    on_listening_action='append',
    on_thinking_action='append',
    on_speaking_action='append',
)

get_history()

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

同步异步
签名get_history() -> Anyasync get_history() -> Any
异常未设置智能体 ID 时抛出 RuntimeError同左
表格内容超出当前宽度，可横向滚动查看更多列。
Python
# Sync
history = session.get_history()

# Async
history = await session.get_history()

get_turns(page_index=None, page_size=None)

获取已完成或运行中会话的分页轮次分析数据。在 v2.7 中，API 默认返回第 1 页，每页最多 50 个 turn。响应包含 agent_id、name、channel、total_turn_count、pagination 和 turns。

Python
page = session.get_turns(page_index=1, page_size=50)

get_all_turns(page_size=None)

拉取所有 turn 分页，并返回一个合并后 turns 列表的 GetTurnsAgentsResponse。

Python
all_turns = session.get_all_turns(page_size=50)

get_info()

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

同步异步
签名get_info() -> Anyasync get_info() -> Any
异常未设置智能体 ID 时抛出 RuntimeError同左
表格内容超出当前宽度，可横向滚动查看更多列。
Python
# Sync
info = session.get_info()

# Async
info = await session.get_info()

on(event, handler)

注册事件处理函数。对 AgentSession 和 AsyncAgentSession 都是同步方法。为避免错过 started 事件，建议在调用 start() 前注册处理函数。

Python
session.on('started', lambda data: print(f'Started: {data}'))
参数类型说明
eventstr事件类型：started、stopped 或 error
handlerCallable[..., None]回调函数
表格内容超出当前宽度，可横向滚动查看更多列。

off(event, handler)

移除之前注册的事件处理函数。对 AgentSession 和 AsyncAgentSession 都是同步方法。

Python
session.off('started', my_handler)

属性

以下只读属性同时适用于 AgentSession 和 AsyncAgentSession 实例。

属性类型说明
idOptional[str]智能体 ID，在 start() 成功后填充
statusstr当前会话状态：'idle'、'starting'、'running'、'stopping'、'stopped'、'error'
agentAgent创建该会话时所使用的智能体配置
app_idstr当前会话使用的声网 App ID
rawAgentsClient 或 AsyncAgentsClient直接访问原始 agents 客户端，适用于高级操作
表格内容超出当前宽度，可横向滚动查看更多列。

状态转换

当前状态可执行的操作
idlestart()
starting（等待 API 返回）
runningstop()、say()、interrupt()、update()、get_history()、get_info()
stopping（等待 API 返回）
stoppedstart()（重启）
errorstart()（重试）
表格内容超出当前宽度，可横向滚动查看更多列。

服务商

CN 服务商从 agora_agent.cn 导入；可在 CN 场景使用的 common/custom 服务商从 agora_agent 顶层导入。

Python
from agora_agent import CustomLLM, GenericTTS
from agora_agent.cn import (
    AliyunLLM, BytedanceLLM, DeepSeekLLM, TencentLLM,
    MiniMaxTTS, TencentTTS, BytedanceTTS, MicrosoftTTS,
    CosyVoiceTTS, BytedanceDuplexTTS, StepFunTTS,
    FengmingSTT, TencentSTT, MicrosoftSTT,
    SenseTimeAvatar, SpatiusAvatar,
)

采用 STT → LLM → TTS 的级联流程。除 FengmingSTT 外，本文档中的 CN vendors 均为 BYOK，需要显式提供对应服务商的凭据。

LLM 服务商

与 with_llm() 配合使用。CN 服务商 helper 均复用 OpenAI 兼容协议（style=openai），内部设置各自的服务商标识。CN 场景下这些 helper 均为 BYOK，要求传入 base_url、model 和 api_key。

信息

greeting_configs 可接收 dict 或 LlmGreetingConfigs。在 v2.7 中，greeting_configs.interruptable=False 表示问候语不可被打断；True 则遵循全局 interruption 设置。

类服务商服务提供方
AliyunLLMaliyun阿里云百炼
BytedanceLLMbytedance火山引擎（字节跳动）
DeepSeekLLMdeepseekDeepSeek
TencentLLMtencent腾讯混元
CustomLLMcustom任意兼容 OpenAI Chat Completions 协议的 LLM
表格内容超出当前宽度，可横向滚动查看更多列。

以上四个 CN 服务商 helper 共用相同的构造参数：

Python
from agora_agent.cn import AliyunLLM

llm = AliyunLLM(
    base_url='https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
    model='qwen-plus',
    api_key='your-api-key',
)
参数类型是否必填默认值说明
base_urlstr是—OpenAI 兼容的 chat completions endpoint
modelstr是—模型名称
api_keystr是—服务商 API 密钥
system_messagesList[Dict]否None额外的系统消息列表
greeting_messagestr否None智能体问候语
failure_messagestr否NoneLLM 调用失败时播报的消息
max_historyint否None保留在 LLM 上下文中的最大对话轮次数
paramsDict[str, Any]否None附加模型参数
headersDict[str, str]否None转发给 LLM 服务商的自定义 HTTP 请求头
template_variablesDict[str, str]否None创建智能体时确定的固定模板变量；序列化到 llm.template_variables，可供自定义工具通过 {{template_variables.<name>}} 引用
toolsList[Dict[str, Any]]否None同步自定义工具定义；需要同时启用 with_tools(True)
表格内容超出当前宽度，可横向滚动查看更多列。

LLM 服务商的 template_variables 选项用于声明创建智能体时确定的固定字符串值。自定义工具可以在 server.url、server.headers 或 server.body 中通过 {{template_variables.<name>}} 引用这些值；{{args.<name>}} 和 {{tool_call_id}} 分别由模型和引擎运行时提供，不需要配置 template_variables。

LLM 服务商的 tools 选项用于声明同步自定义工具。每个工具包含函数定义和服务端请求配置；调用 .with_tools()（或传入 True）后，SDK 才会启用 tools 和 mcp_servers 中的工具调用。

CustomLLM

用于接入任意兼容 OpenAI Chat Completions 协议的自定义 LLM 服务。

Python
from agora_agent import CustomLLM

llm = CustomLLM(
    base_url='https://your-llm.example.com/v1/chat/completions',
    model='your-model',
    api_key='your-api-key',
)
参数类型是否必填默认值说明
base_urlstr是—自定义 LLM 服务的 OpenAI 兼容 chat completions endpoint
modelstr是—模型名称
api_keystr是—自定义 LLM 服务鉴权 API 密钥
system_messagesList[Dict]否None额外的系统消息列表
greeting_messagestr否None智能体问候语
failure_messagestr否NoneLLM 调用失败时播报的消息
max_historyint否None保留在 LLM 上下文中的最大对话轮次数
paramsDict[str, Any]否None附加模型参数
headersDict[str, str]否None转发给 LLM 服务的自定义 HTTP 请求头
template_variablesDict[str, str]否None创建智能体时确定的固定模板变量；序列化到 llm.template_variables，可供自定义工具通过 {{template_variables.<name>}} 引用
toolsList[Dict[str, Any]]否None同步自定义工具定义；需要同时启用 with_tools(True)
表格内容超出当前宽度，可横向滚动查看更多列。

语音合成服务商

与 with_tts() 配合使用。sample_rate 选项决定数字人兼容性，详见 with_avatar()。

所有 TTS 类均支持 skip_patterns 和 additional_params。

MiniMaxTTS

MiniMax TTS 为 BYOK，始终需要传入 key 和 model。voice_id 与 timber_weights 必须二选一。

Python
from agora_agent.cn import MiniMaxTTS
参数类型是否必填默认值说明
keystr是—MiniMax API 密钥
modelstr是—MiniMax TTS 模型
voice_idstr条件必填None音色样式标识。voice_id 与 timber_weights 必须二选一
timber_weightsList[Dict[str, Any]]条件必填None音色混合配置。voice_id 与 timber_weights 必须二选一
speedfloat否None语速
volfloat否None音量增益
pitchfloat否None音调调整
emotionstr否None情感风格
latex_readbool否None是否朗读 LaTeX 表达式
english_normalizationbool否None是否对英文文本做归一化
sample_rateint否None输出采样率，单位 Hz
pronunciation_dictDict[str, Any]否None发音替换词典
language_booststr否None语言增强策略
additional_paramsDict[str, Any]否None附加 MiniMax TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

TencentTTS

Python
from agora_agent.cn import TencentTTS
参数类型是否必填默认值说明
app_idstr是—腾讯云 TTS 应用 ID
secret_idstr是—腾讯云 TTS 密钥 ID
secret_keystr是—腾讯云 TTS 密钥
voice_typeint是—腾讯云 TTS 音色类型
volumeint否None音量
speedint否None语速
emotion_categorystr否None情感类别
emotion_intensityint否None情感强度
additional_paramsDict[str, Any]否None附加腾讯云 TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

BytedanceTTS

Python
from agora_agent.cn import BytedanceTTS
参数类型是否必填默认值说明
tokenstr是—字节跳动 TTS token
app_idstr是—字节跳动 TTS 应用 ID
clusterstr是—字节跳动 TTS cluster
voice_typestr是—字节跳动 TTS 音色类型
speed_ratiofloat否None语速比例
volume_ratiofloat否None音量比例
pitch_ratiofloat否None音调比例
emotionstr否None情感
additional_paramsDict[str, Any]否None附加字节跳动 TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

MicrosoftTTS

Python
from agora_agent.cn import MicrosoftTTS
参数类型是否必填默认值说明
keystr是—Microsoft Azure 订阅密钥
regionstr是—Azure 区域
voice_namestr是—音色名称
sample_rateint否None采样率，单位 Hz
speedfloat否None语速倍率
volumefloat否None音量
additional_paramsDict[str, Any]否None附加 Microsoft TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

GenericTTS

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

Python
from agora_agent import GenericTTS
参数类型是否必填默认值说明
urlstr是—自定义 TTS 服务的 HTTP(S) endpoint
headersDict[str, str]否None转发给 TTS 服务的自定义 HTTP 请求头；未设置时不会写入 headers
api_keystr否NoneTTS 服务鉴权 API 密钥
modelstr否NoneTTS 模型名
voicestr否None音色名
speedfloat否None语速
sample_rateint否None输出音频采样率，单位为 Hz。如果你的 TTS 服务暂不支持多采样率，请确保返回音频的采样率与该配置一致
response_formatstr否None输出音频格式；当前 ConvoAI 支持 pcm
instructionstr否None语音风格、情绪或其他播报指令
additional_paramsDict[str, Any]否None透传给 TTS 服务的其他参数；同名字段会被显式参数覆盖
skip_patternsList[int]否None控制 TTS 跳过特定文本模式。
表格内容超出当前宽度，可横向滚动查看更多列。

CosyVoiceTTS

Python
from agora_agent.cn import CosyVoiceTTS
参数类型是否必填默认值说明
api_keystr是—CosyVoice API 密钥
modelstr是—CosyVoice 模型
sample_rateint否None采样率，单位 Hz
voicestr是—CosyVoice 音色
additional_paramsDict[str, Any]否None附加 CosyVoice TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

BytedanceDuplexTTS

Python
from agora_agent.cn import BytedanceDuplexTTS
参数类型是否必填默认值说明
app_idstr是—字节跳动 Duplex TTS 应用 ID
tokenstr是—字节跳动 Duplex TTS token
speakerstr是—字节跳动 Duplex TTS speaker
additional_paramsDict[str, Any]否None附加字节跳动 Duplex TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

StepFunTTS

Python
from agora_agent.cn import StepFunTTS
参数类型是否必填默认值说明
api_keystr是—StepFun TTS API 密钥
modelstr是—StepFun TTS 模型
voice_idstr是—StepFun TTS 音色 id
additional_paramsDict[str, Any]否None附加 StepFun TTS 参数
skip_patternsList[int]否None跳过括号内容的规则配置
表格内容超出当前宽度，可横向滚动查看更多列。

语音识别服务商

与 with_stt() 配合使用。

FengmingSTT

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

Python
from agora_agent.cn import FengmingSTT
参数类型是否必填默认值说明
keywordsList[str]否None热词列表，用于提升 ASR 识别准确率
表格内容超出当前宽度，可横向滚动查看更多列。

TencentSTT

Python
from agora_agent.cn import TencentSTT
参数类型是否必填默认值说明
keystr是—腾讯云 ASR 参数 secret_id
app_idstr是—腾讯云 ASR 应用 ID
secretstr是—腾讯云 ASR 参数 secret_key
engine_model_typestr是—腾讯云 ASR 引擎模型类型
voice_idstr是—腾讯云 ASR voice id
additional_paramsDict[str, Any]否None附加腾讯云 ASR 参数
表格内容超出当前宽度，可横向滚动查看更多列。

MicrosoftSTT

Python
from agora_agent.cn import MicrosoftSTT
参数类型是否必填默认值说明
keystr是—Microsoft Azure 订阅密钥
regionstr是—Azure 区域，例如 chinaeast2
languagestr是—语言代码，例如 zh-CN
phrase_listList[str]否None热词提示
additional_paramsDict[str, Any]否None附加 Microsoft ASR 参数
表格内容超出当前宽度，可横向滚动查看更多列。

数字人服务商

与 with_avatar() 配合使用。

SenseTimeAvatar

数字人服务商。其 required_sample_rate 为 0，即不强制要求特定的 TTS 采样率。

Python
from agora_agent.cn import SenseTimeAvatar
参数类型是否必填默认值说明
agora_tokenstr否None数字人发布者使用的 RTC token；未传入时由 AgentSession 生成
agora_uidstr是—数字人 RTC 发布者 uid
appIdstr否None商汤应用 ID
app_keystr是—商汤 app key
sceneListList[Dict[str, Any]]否None商汤场景列表
enablebool否None是否启用数字人
additional_paramsDict[str, Any]否None附加商汤数字人参数
表格内容超出当前宽度，可横向滚动查看更多列。

SenseTimeAvatar 直接接收数字人发布者的 agora_token 和 agora_uid，因此与级联流程中的 TTS 采样率无关。

SpatiusAvatar

数字人服务商。required_sample_rate 返回 sample_rate 字段值；未设置时返回 0，即不强制要求特定的 TTS 采样率。

Python
from agora_agent.cn import SpatiusAvatar
参数类型是否必填默认值说明
spatius_api_keystr是—Spatius API 密钥
spatius_app_idstr是—Spatius 应用 ID
spatius_avatar_idstr是—Spatius 数字人 ID
agora_uidstr是—数字人服务使用的 Agora UID
agora_tokenstr否None数字人发布者使用的 RTC token；未传入时由 AgentSession 生成
regionstr否NoneSpatius 服务区域，例如 cn-beijing
sample_rateint否None音频采样率，单位 Hz
session_expire_minutesint否NoneSpatius 会话有效时长，单位分钟
enablebool否None是否启用数字人
additional_paramsDict[str, Any]否None附加 Spatius 数字人参数
表格内容超出当前宽度，可横向滚动查看更多列。

Token 工具

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

Python
from agora_agent.agentkit.token import generate_convo_ai_token, generate_rtc_token
from agora_agent.agentkit import expires_in_hours, expires_in_minutes

generate_convo_ai_token()

生成一个同时具备 RTC 和 RTM 权限的 Conversational AI token。这与 SDK 在 app-credentials 模式下自动生成的 token 相同。当你需要把预生成 token 传给 create_session() 时，可以使用该方法。

Python
generate_convo_ai_token(
    app_id: str,
    app_certificate: str,
    channel_name: str,
    account: str,
    token_expire: int = 86400,
    privilege_expire: int = 0,
) -> str
参数类型是否必填默认值说明
app_idstr是—声网 App ID
app_certificatestr是—声网 App 证书
channel_namestr是—token 授权访问的频道
accountstr是—token 颁发给哪个 UID，使用字符串形式表示
token_expireint否86400token 有效期，单位为秒。有效范围：1–86400
privilege_expireint否0权限过期时间，单位为秒。0 表示与 token_expire 保持一致
表格内容超出当前宽度，可横向滚动查看更多列。

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

Python
from agora_agent.agentkit.token import generate_convo_ai_token
from agora_agent.agentkit import expires_in_hours

token = generate_convo_ai_token(
    app_id='your-app-id',
    app_certificate='your-app-certificate',
    channel_name='support-room-123',
    account='1',
    token_expire=expires_in_hours(12),
)

generate_rtc_token()

生成一个仅用于频道入会的 RTC token。大多数对话式 AI 场景建议优先使用 generate_convo_ai_token()。

Python
generate_rtc_token(
    app_id: str,
    app_certificate: str,
    channel: str,
    uid: int,
    role: int = 1,
    expiry_seconds: int = 86400,
) -> str
参数类型是否必填默认值说明
app_idstr是—声网 App ID
app_certificatestr是—声网 App 证书
channelstr是—频道名
uidint是—用户 ID。使用 0 表示任意用户
roleint否1RTC 角色：1 表示发布者，2 表示订阅者
expiry_secondsint否86400token 有效期，单位为秒。有效范围：1–86400
表格内容超出当前宽度，可横向滚动查看更多列。

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

expires_in_hours() / expires_in_minutes()

用于指定 token 生命周期的辅助函数。可与 create_session() 或 token 生成函数配合使用。函数会校验输入值，并在超过声网上限 86400 秒（24 小时）时自动截断。

Python
expires_in_hours(hours: int) -> int
expires_in_minutes(minutes: int) -> int
函数返回值行为
expires_in_hours(n)int — seconds当 n ≤ 0 时抛出 ValueError。如果结果超过 24 小时，会给出警告并截断到 86400
expires_in_minutes(n)int — seconds当 n ≤ 0 时抛出 ValueError。如果结果超过 24 小时，会给出警告并截断到 86400
表格内容超出当前宽度，可横向滚动查看更多列。
Python
from agora_agent.agentkit import expires_in_hours, expires_in_minutes

session = agent.create_session(
    channel='support-room-123',
    agent_uid='1',
    remote_uids=['100'],
    name='support-agent',
    expires_in=expires_in_hours(12),
)

类型与枚举

Agora、AsyncAgora、Agent、AgentSession 以及各服务商类会共用以下类型和枚举。

Area

用于 API 路由的区域枚举。通过 area 参数传给 Agora 或 AsyncAgora。固定使用 Area.CN。

Python
from agora_agent import Area
值区域
Area.CN中国大陆
表格内容超出当前宽度，可横向滚动查看更多列。

Area.CN 的路由信息：

项目值
主区域前缀api-cn-east-1
备用区域前缀api-cn-north-1
主域名后缀sd-rtn.com
备用域名后缀agora.io
请求路径/cn/api/conversational-ai-agent
表格内容超出当前宽度，可横向滚动查看更多列。

AgentSessionEvent

session.on() 和 session.off() 可用的事件名。

Python
'started' | 'stopped' | 'error'
值数据说明
'started'dict with agent_id: str智能体已成功加入频道
'stopped'dict with agent_id: str智能体已离开频道
'error'Exception发生不可恢复错误
表格内容超出当前宽度，可横向滚动查看更多列。

SpeakPriority

控制智能体在处理 say() 调用时，相对于当前行为应如何处理消息。通过字符串传给 session.say()。

值说明
'INTERRUPT'智能体立即停止当前播报并发送该消息
'APPEND'将消息加入队列，待当前播报结束后发送
'IGNORE'如果智能体当前正在说话，则丢弃该消息
表格内容超出当前宽度，可横向滚动查看更多列。

ApiError

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

Python
from agora_agent.core.api_error import ApiError

try:
    agent_id = session.start()
except ApiError as e:
    print(e.status_code)
    print(e.body)
属性类型说明
status_codeintAPI 返回的 HTTP 状态码
bodyAnyAPI 原始响应体
表格内容超出当前宽度，可横向滚动查看更多列。

同步与异步

Python SDK 提供两套并行的客户端和会话体系: 同步与异步。应根据你应用的运行时模型进行选择。

同步异步
客户端AgoraAsyncAgora
会话AgentSessionAsyncAgentSession
HTTP 客户端httpx.Clienthttpx.AsyncClient
表格内容超出当前宽度，可横向滚动查看更多列。

在以下场景使用 Agora（同步）：

  • 你在编写脚本、CLI 工具或批处理任务
  • 你的 Web 框架是同步模型，例如 Flask，或未使用异步 view 的 Django
  • 你希望代码保持尽可能简单

在以下场景使用 AsyncAgora（异步）：

  • 你的应用基于 asyncio，例如 FastAPI、Starlette 或 aiohttp
  • 你需要高效管理多个并发的智能体会话
  • 你希望使用非阻塞 I/O

Agent builder 类对同步和异步两种模式通用，因为它本身不发起 HTTP 调用，因此不存在异步版本。将 AsyncAgora 客户端传给 agent.create_session() 时，返回值会是 AsyncAgentSession。

这个页面有帮助吗？

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利