文档中心

实时音视频

开发指南

接入联网问答 Agent

您可以接入火山引擎的联网问答 Agent，让 AI 具备实时检索互联网信息的能力（如查询最新资讯、获取天气信息等）。当用户询问具有强时效性的问题（如今日天气、实时金价、最新新闻）时，AI 会自动通过联网问答 Agent 来获取信息。支持根据用户的语音提问搜索实时资讯（文搜），也可结合视频画面或上传的图片联网识别（图搜）。

更多信息，请参见联网问答 Agent 服务。

计费说明

联网问答 Agent 为付费资源，会根据您的实际使用量独立计费。详细计费规则和价格，请参见联网问答 Agent 计费说明。

实现方式

前提条件

火山方舟模型或第三方大模型，且需具备 Function Calling 能力。

若需实现图搜，模型还需具备并开启视觉理解能力。

若使用的是第三方 LLM，您的 LLM 服务返回给 RTC 系统的 JSON 响应中，必须包含标准的 tool_calls 字段，且 function.name 必须精确匹配配置的 FunctionName。

第三方 LLM 交互流程及代码示例

构造 Tools 定义（发送给模型）。

在您的服务端向第三方模型发起对话请求时，需要在 tools 参数中定义联网工具。

工具名称（name）：必须与 StartVoiceChat 接口中 WebSearchAgentConfig.FunctionName 的值保持一致（默认为 webSearch）。

参数定义（parameters）：通常设为空对象即可，联网 Agent 不需要复杂参数。

代码示例：

// 您的服务端向第三方模型发起的请求体
{
"model": "gpt-4",
"messages": [
{"role": "system", "content": "你是一个智能助手，当用户询问实时信息时，请调用 webSearch 工具。"},
{"role": "user", "content": "今天北京天气怎么样？"}
],
// 关键：必须显式定义 tools，否则模型不会触发
"tools": [
{
"type": "function",
"function": {
"name": "webSearch", // 必须与 WebSearchAgentConfig.FunctionName 一致
"description": "用于搜索互联网上的实时信息，如天气、新闻、汇率等。",
"parameters": {
"type": "object",
"properties": {},
"required": []
}
}
}
],
"tool_choice": "auto"
}

回传 Tool Calls（返回给智能体服务）

当第三方模型判断需要联网时，它会返回包含 tool_calls 的响应。您需要将该响应透传或格式化后返回给火山引擎智能体服务。

{
"id": "chatcmpl-unique-id",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null, // 触发工具调用时，content 通常为空
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "webSearch", // 系统检测到此名称，将拦截并触发联网 Agent
"arguments": "{}"
}
}
]
},
"finish_reason": "tool_calls"
}
]
}

步骤 1：创建联网问答 Agent

登录联网问答 Agent 控制台。

左侧导航栏选择联网问答Agent，按需创建一个联网问答 Agent。在创建过程中，务必完成以下关键配置：

文搜 > 联网意图：配置为强制联网，以跳过 LLM 的联网意图判断。

文搜/图搜 > 系统提示词：按需约束 Agent 回复长度，避免因回复冗长影响对话的流畅性。例如：“用最简洁的语言回答，控制在 150 字以内”。

联网问答 Agent 版本区别及其他配置说明，请参见联网问答Agent操作指南。

创建后，正式开通该 Agent，并记录下 Agent ID。

创建一个 API Key，并记录下 API Key 值。具体操作，请参见智能体API认证方式。

步骤 2：启用联网搜索（文搜/图搜）

在调用 StartVoiceChat 接口时，根据您的业务场景（文搜或图搜）配置对应的参数。

详细参数说明参见接口文档 StartVoiceChat（2025-06-01）。

核心参数	说明
WebSearchAgentConfig	启用并配置联网问答 Agent。其子参数 ParamsString 配置说明，可参见 ParamsString 配置说明。
LLMConfig.SystemMessages	添加提示词，引导模型准确触发联网问答 Agent。
LLMConfig.VisionConfig	如果需使用图搜（DisableImageSearch 为 false），需将 VisionConfig.Enable 设置 true，开启视觉理解能力。

纯文本搜索

多模态联网图搜

通过语音或文字提问获取资讯。

如何提供用于搜索的图片

配置联网图搜后（需开启视觉理解），系统会自动提取当前会话缓存的图片进行搜索。可以通过以下方式向会话中添加图片：

视频截图（自动抽帧）：开启视觉理解后，系统会根据配置的 SnapshotConfig 自动对视频画面进行截图。联网搜索时，系统会优先采用这些实时截图。详细配置，参见视频和图片理解。

外部图片（手动发送）：在对话过程中，通过客户端或服务端发送图片。具体操作，参见图片理解（发送外部图片问答）。

注意

系统提取优先级为：视频截图 > 外部图片，总数不超过 10 张。

附录

ParamsString 配置说明

ParamsString 是一个经过压缩和转义的 JSON 字符串，用于向联网问答 Agent 服务传递配置。它本质上是“联网问答 Agent 服务”的 API 请求体 ChatCompletionRequest 的透传。构建方法如下：

参考智能体会话 API 文档，在请求参数 ChatCompletionRequest中选取所需参数，构建 JSON 字符串。

bot_id：必选。值为在步骤 1：创建联网问答 Agent 获取的 Agent ID。

stream 必选，且必须设置为 true。

其他参数（如 messages、knowledge等）：按需选择并配置。

构建示例如下：

最简配置（仅包含必填项）：

{
"bot_id": "7429...747",
"stream": true
}

高级配置（包含上下文）

{
"bot_id": "7429...747",
"stream": true,
"user_id": "user_123",
"messages": [
{ "role": "user", "content": "想去西安玩几天，有什么推荐的。" },
{ "role": "assistant", "content": "好的，西安是历史名城，有兵马俑、大雁塔等著名景点。您计划什么时候去呢？" }
],
"knowledge": "当前用户正在规划去西安的旅行"
}

将构建的 JSON 对象转换为 JSON 字符串，得到 ParamsString 的值。例如，{\"bot_id\":\"7429...747\",\"stream\":true}。

其他联网方式

除了接入联网问答 Agent 以外，还可以通过 MCP 或 Function Calling 方式实现联网：

通过 MCP 实现：推荐通过 MCP 接入火山联网搜索 API。

通过 Function Calling 实现：适用于接入您自有的搜索服务，实现方式参见函数调用 Function Calling。

联网问答 Agent、MCP 和 Function Calling 三者的区别，请参见如何实现联网？

最近更新时间：2026.09.28 10:19:27

这个页面对您有帮助吗？

有用

无用