创建 AI 智能体，用于配置和启动智能体，例如智能语音助手、智能硬件智能体。更多详情，请参考 配置智能体。

• Agent 创建成功后，系统会自动分配唯一的 agentId。
• 发起请求时，agentName 和 llmPromptContent 必填，其他配置可以按需填写。

功能描述

• 支持多种 LLM 供应商配置，包括千问、OpenAI、百度等。
• 提供丰富的 TTS 音色选择和语音参数配置。
• 支持多种 ASR 供应商和语言识别配置。
• 支持语音打断、开场白、声纹识别等高级功能。
• 支持自定义工具和 MCP Server 配置。
• 支持 RAG 知识库检索和情绪识别功能。

请求信息

请求 URI

POST https://rtc-agent.yunxinapi.com/v1/agent

请求头参数

请求 Header 的参数说明请参考 请求结构。

请求体参数

参数名称	类型	是否必选	示例	说明
agentName	String	是	"助手小易"	Agent 名称，长度限制 1-100 个字符
llmPromptContent	String	是	"作为网易云信的智能语音助手..."	LLM 提示词内容，长度限制 1-3000 个字符
- llmConfig	Object	否	-	LLM 配置
llmVendor	Integer	否	1	LLM 供应商类型： 1：千问 2：openAI 5：豆包 9：DeepSeek 100：自定义大模型 默认为 1
url	String	否	"https://api.your-llm-provider.com/v1/chat/completions"	自定义大模型的 URL。llmVendor 为 100 时有效
apiKey	String	否	"sk-xxxxxxxxxxxxxxxxxxxx"	自定义大模型的 API 密钥。llmVendor 为 100 时有效
llmModel	String	否	"qwen-plus"	LLM 模型名称，根据供应商提供的模型列表选择，默认为 qwen-plus
temperature	Double	否	1.0	温度参数，控制输出的随机性，范围 0-2，默认为 1.0
topP	Double	否	0.9	核采样阈值，控制输出的多样性，范围 0-1，默认为 0.9
maxTokens	Integer	否	4000	生成的最大 token 数，范围 1-4000，默认为 4000
enableWebSearch	Boolean	否	false	是否启用网页搜索功能，默认为 false
contextSize	Integer	否	3	上下文窗口大小，范围 1-20，表示保留的对话轮数，默认为 3
enableVision	Boolean	否	false	是否启用视觉功能，默认为 false
- tools	Array	否	-	用户自定义工具列表
enable	Boolean	是	true	是否启用此工具
type	String	是	"function"	工具类型，固定为 function
- function	Object	是	-	模型返回中可包含待调用的工具
name	String	是	"get_weather"	调用的函数名称
description	String	是	"获取天气信息"	调用的函数描述，大模型会使用它来判断是否调用这个工具
parameters	Object	否	{"type": "object", "properties": {"city": {"type": "string", "description": "城市名称"}}}	函数请求参数，以 JSON Schema 格式描述
hitMessage	Array	否	["正在为您查询天气"]	命中此工具可返回的提示语句
- ttsConfig	Object	否	-	TTS 音色相关配置
ttsVendor	Integer	否	6	TTS 供应商类型： 3：千问(普通) 4：千问(CosyVoice) 5：MiniMax(废弃) 8：MiniMax 10：豆包 100：网易云信克隆音色（可通过 克隆音色 获取） 默认为 6
voice	String	否	"zh_female_qingxinnvsheng_mars_bigtts"	音色名称，或者是克隆音色的 ID。音色设置范围受 ttsVendor 影响，例如：ttsVendor 如果设置为 100，则音色取值范围为克隆音色的 ID；ttsVendor 如果设置为 3 或者 4（千问），则普通音色取值范围为： siyue：温柔女声 aiya：严厉女声 aimei：甜美女声 zhiqing：台湾地区女性声音 默认为 zh_female_qingxinnvsheng_mars_bigtts
gender	String	否	"Female"	音色性别： Female：女声 Male：男声 默认为 Female
language	String	否	"Chinese"	TTS 语言： Chinese：中文 English：英文 默认为 Chinese
ignoreBracketTextSet	Array	否	[1,2]	过滤内容配置： 1：中文括号 2：英文括号 3：中文方括号 4：英文方括号 5：英文花括号 默认为 [1,2]
speed	Double	否	1.0	TTS 语速，取值范围 0.8-2.0，默认为 1.0 即正常语速
pitch	Integer	否	0	TTS 语调，取值范围 -12-12，默认为 0 即正常语调
volume	Double	否	1.0	TTS 音量，取值范围 0.5-2.0，默认为 1.0 即正常音量
enableLatex	Boolean	否	false	是否启用 Latex 公式播报，默认为 false
- asrConfig	Object	否	-	ASR 配置
asrVendor	Integer	是	6	ASR 供应商： 6：阿里(实时音) 7：讯飞(短语音) 8：阿里(短语音) 9：火山引擎(实时音) 默认为 6
srcLan	String	否	"AUTO"	源语言设置，默认为 AUTO 表示自动识别语言。语言的支持范围跟随您选择的 asrVendor，请参考 ASR 供应商官方文档（腾讯 | 阿里 | 火山）。
maxSentenceSilence	Integer	否	200	断句静音时长，单位为毫秒(ms)，用于控制语音识别的断句时机，默认值为 200
enableSaveAudio	Boolean	否	false	是否保存语音文件，默认为 false 表示不保存
enableSemanticVad	Boolean	否	true	是否启用语义 VAD（语音活动检测），默认为 true
vocabularyId	String	否	"vocab_12345"	热词库 ID，可提高 ASR 识别准确率（仅 asrVendor 为阿里和火山引擎支持）
- agentConfigProperties	Object	否	-	智能体其他属性配置（如 Pipeline 设置）
useMemory	Boolean	否	true	是否启用记忆功能，默认为 true
enableMemoryByVoicePrint	Boolean	否	true	是否启用声纹记忆，默认为 true。开启该功能前，需要先开启 useMemory 和 enableSpeakerVerify
reference	Boolean	否	true	是否返回知识库参考信息，默认为 true
- pipeline	Object	否	-	Pipeline 配置对象
interruptMode	Integer	否	2	打断模式： 0：禁用语音打断 1：开始说话时打断 2：结束说话时打断 4：打断词打断 默认为 2
interruptWords	Array	否	["你好小派"]	自定义打断词列表（当 interruptMode 为 4 时该配置生效），最多 3 个，每个长度不超过 15
enableWelcomeMessage	Boolean	否	true	是否启用开场白，默认为 true
welcomeMessage	String	否	"你好呀，今天过得怎么样"	自定义开场白内容，需要 enableWelcomeMessage 为 true
enablePause	Boolean	否	false	是否启用会话暂停功能，默认为 false
- serverAudioProcess	Object	否	-	服务端音频处理配置
enableServerAec	Boolean	否	false	是否启用云端回声消除，默认为 false
serverAnsMode	Integer	否	0	云端 AI 降噪模式： 0：关闭 1：普通 2：增强 默认为 0
enableSpeakerVerify	Boolean	否	false	是否启用声纹识别，默认为 false
speakerVerifyLevel	Integer	否	1	声纹验证等级： 0：宽松 1：标准 2：严格 默认为 1
enableSpeakerLock	Boolean	否	false	是否启用声纹锁定，默认为 false
enableShowSpeakerInAsrResult	Boolean	否	false	字幕是否显示说话人信息，默认为 false
enabledNotifies	Array	是	["agent.started", "agent.stopped"]	开启回调的类型
- mcpServers	Array	否	-	用户自定义 MCP Server 配置
name	String	否	"weather_server"	MCP Server 名称(英文或阿拉伯数字，不能包含其他特殊字符，限制 100 个字符)
mcpServerId	String	是	"mcp_server_12345"	MCP server ID，从 MCP 相关接口获取
- ragConfig	Array	否	-	RAG（检索增强生成）知识库配置
identifier	String	是	"kb_001"	知识库标识符
docList	Array	否	["doc_001", "doc_002"]	指定使用的文档 ID 列表（如果为空或不存在则使用知识库所有文档）
emotionRecognition	Boolean	否	false	是否启用情绪识别，默认为 false
emotionShow	Boolean	否	false	是否启用情绪显示，默认为 false
- emotionConfig	Object	否	-	情绪配置，键为情绪名称，值为情绪配置信息
- additionalProperties	Object	否	-	具体情绪配置
description	String	是	"高兴的情绪状态"	情绪描述
status	String	是	"enabled"	该情绪是否启用

请求体示例

JSON{
    "agentName": "测试智能体",
    "llmPromptContent": "作为网易云信的智能语音助手，我遵循以下原则：我的名字叫小易，我的回答语气可爱乖巧，和真正的人类对话一样，内容清晰全面，但不超过 50 个词, 不回复表情和表情符号，不回复重复的句子。",
    "ttsConfig": {
        "ttsVendor": 6,
        "voice": "zh_female_qingxinnvsheng_mars_bigtts",
        "gender": "Female",
        "language": "Chinese",
        "ignoreBracketTextSet": [1, 2],
        "speed": 1.0,
        "pitch": 0,
        "volume": 1.0,
        "enableLatex": false
    },
    "asrConfig": {
        "asrVendor": 6,
        "srcLan": "AUTO",
        "maxSentenceSilence": 200,
        "enableSaveAudio": false,
        "enableSemanticVad": true
    },
    "llmConfig": {
        "llmVendor": 1,
        "llmModel": "qwen-plus",
        "temperature": 1.0,
        "topP": 0.9,
        "maxTokens": 4000,
        "enableWebSearch": false,
        "contextSize": 3,
        "enableVision": false,
        "tools": [
            {
                "enable": true,
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "获取指定城市的天气信息",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "description": "城市名称"
                            }
                        },
                        "required": ["city"]
                    }
                },
                "hitMessage": ["正在为您查询天气信息"]
            }
        ]
    },
    "agentConfigProperties": {
        "useMemory": true,
        "enableMemoryByVoicePrint": true,
        "reference": true,
        "pipeline": {
            "interruptMode": 2,
            "enableWelcomeMessage": true,
            "welcomeMessage": "你好呀，今天过得怎么样",
            "enablePause": false,
            "serverAudioProcess": {
                "enableServerAec": false,
                "serverAnsMode": 0,
                "enableSpeakerVerify": false,
                "speakerVerifyLevel": 1,
                "enableSpeakerLock": false,
                "enableShowSpeakerInAsrResult": false
            },
            "enabledNotifies": ["agent.started", "agent.stopped"]
        },
        "ragConfig": [
            {
                "identifier": "kb_001",
                "docList": ["doc_001", "doc_002"]
            }
        ],
        "emotionRecognition": false,
        "emotionShow": false
    }
}

响应信息

响应参数

参数名称	类型	说明	是否必返回
code	Integer	响应状态码，200 表示成功	是
msg	String	响应消息，成功时返回 "success"	否
requestId	String	请求 ID，用于问题定位和日志跟踪	是
- data	Object	响应数据对象	是
agentId	String	Agent 唯一标识符，用于后续调用和管理	是

响应体示例

JSON{
  "code": 200,
  "requestId": "aifdec7995a14a498ab652265204925460",
  "data": {
    "agentId": "d71bde7e8f5b4c00a9dbdae674ef20fe"
  }
}

错误码

本文仅列举部分业务接口错误码，完整列表请参考 错误码。

错误码	说明	处理建议
400	参数格式错误或缺少必填参数	检查请求参数格式和必填字段
402	参数值不符合规范要求	检查参数值是否在允许范围内