豆包智能体

API 配置

保存后下方「Try It」面板会自动携带此 API Key 发送真实请求。

Base: api.xrtoken.net

XRToken 提供豆包联网问答 Agent 透传接口，支持非流式和 SSE 流式响应。

端点

POST /v1/agent/chat/completions

兼容别名：POST /v1/agent/chat/completion、POST /v1/agents/chat/completions。

请求

{
  "bot_id": "你的智能体ID",
  "agent_variant": "lite",
  "stream": false,
  "messages": [
    { "role": "user", "content": "今天北京天气怎么样？" }
  ],
  "user_id": "user-123"
}

bot_id 和 messages 必填。bot_id 必须是已开通的 Agent。agent_variant 可选，取 lite 或 pro；不传时使用该 Agent 的默认档位。model 可选，支持 thinking、auto_thinking 和 reasoning_search。

请求参数

参数	类型	必填	说明
`bot_id`	string	是	Agent 标识
`messages`	array	是	对话消息，支持 `system`、`user`、`assistant`
`stream`	boolean	否	是否使用 SSE 流式响应，默认 `false`
`agent_variant`	string	否	`lite` 或 `pro`，不传使用默认档位
`user_id`	string	否	业务侧终端用户标识，用于保持同一用户的会话、记忆和个性化上下文；不是 XRToken 登录账号标识
`device_id`	string	否	设备标识
`location_info`	object	否	当前位置。出行/天气建议传 `longitude`、`latitude`（小数点后六位）、`province`、`city`、`district`、`town`（街道）。体验页定位图标会按浏览器定位反查这些字段
`navigation_info`	object	否	导航信息；周边路线等场景可传
`knowledge`	string	否	本轮请求需要注入的背景知识
`memory`	string	否	用户画像或个性化记忆
`model`	string	否	`thinking`、`auto_thinking` 或 `reasoning_search`
`extension_options`	object	否	高级能力开关，见下表

user_id 建议使用业务系统中稳定且不可变的用户编号。它不会替代 API Key 鉴权，也不会用于 XRToken 账户计费。

消息内容

文本消息：

{ "role": "user", "content": "你好" }

图文消息：

{
  "role": "user",
  "content": [
    { "type": "text", "text": "请描述这张图片" },
    { "type": "image_url", "image_url": { "url": "https://example.com/a.jpg" } }
  ]
}

文件消息：

{
  "role": "user",
  "content": [
    { "type": "text", "text": "请总结这个文件" },
    { "type": "file_url", "file_url": { "url": "https://example.com/a.pdf" } }
  ]
}

`extension_options`

参数	类型	说明
`filter_emoji`	boolean	为 `true` 时过滤模型输出中的 emoji
`enable_processing_state`	boolean	为 `true` 时输出 Agent 执行的关键过程；仅流式响应生效
`disable_source_type_douyin_video`	boolean	为 `true` 时关闭控制台已配置的抖音视频内容源
`disable_follow_up`	boolean	为 `true` 时关闭控制台已开启的追问功能
`disable_citation`	boolean	为 `true` 时关闭引用角标
`disable_image_text_mix`	boolean	为 `true` 时关闭图文混排
`disable_baike_highlight`	boolean	为 `true` 时关闭百科划线词
`disable_text_to_image`	boolean	为 `true` 时关闭搜图能力
`enable_search_lite`	boolean	为 `true` 时开启极速搜索模式；耗时较短，但效果可能下降
`browsing_mode`	number	联网模式：`1` 自动联网，`2` 强制联网，`3` 关闭联网。文搜使用 `2` 时至少使用一个搜索源
`card_position`	string	卡片返回位置：`first_frame`（默认，首帧）或 `meta_frame`（元数据帧）
`enable_followup_in_response`	boolean	为 `true` 时开启回答结尾的强化追问
`disable_ecom_link`	boolean	为 `true` 时禁用电商意图，电商链接不参与总结和出卡
`disable_video_text_mix`	boolean	为 `true` 时关闭视频文本混排
`learn_mode`	string	拍题答疑增值包；开通后传 `auto_learning`，由系统按意图判断是否走解题链路。体验页不提供此开关
`reasoning_effort`	string	思维链长度：`high`、`medium` 或 `low`；自动深度思考模式下不生效
`sites`	string[]	限定搜索站点，最多 20 个；填写完整域名
`block_hosts`	string[]	屏蔽搜索站点，最多 20 个；填写完整域名，优先级高于 `sites`
`time_range`	string	搜索时间范围，例如 `1d`、`1w`
`search_auth_info_level`	number	搜索站点权威度：`0` 不限制，`1` 仅非常权威站点

示例（强制联网并限定站点）：

{
  "extension_options": {
    "browsing_mode": 2,
    "sites": ["gov.cn", "news.qq.com"],
    "block_hosts": ["example.com"],
    "disable_citation": false,
    "card_position": "meta_frame"
  }
}

未在网关文档中列出的请求字段也会按原样透传；字段是否可用由 Agent 配置和上游能力决定。

响应

非流式响应返回 Agent 原始 JSON，常见字段包括：

choices
references
search_results
follow_ups
cards
thinking_references
usage

流式响应使用 text/event-stream，每帧格式为 data:{...}，以 data:[DONE] 结束。深度思考模式可能在 choices[].message.reasoning_content 或流式 delta 中返回思考内容。

配套接口

会话以外的官方配套接口同样走 tr- 密钥，不暴露火山 AK/SK。开场白、开场问题、热点问题和埋点通常无 token 用量，网关不冻结余额。

体验页 /agent 会调用这些接口。Bot 必须是 Pro，并在火山控制台打开工具包、知识库、抖音、混排、划线、追问、角标、出卡；没有当次「首次开通」API，未开则开关拨了也出不来。

列出可用 Bot

GET /v1/agent/bots

返回当前密钥可用的已启用 Agent（网关本地列表，不是火山官方接口）。

开场白与开场问题

POST /v1/agent/config

{ "bot_id": "你的智能体ID" }

透传火山 GetBotMeta（Version=2026-01-01，ServiceName=ask_echo）。返回控制台配置的 开场白（OpeningRemark）和 开场问题（OpeningQuestions）。体验页把开场白显示为智能体第一条问候，开场问题作为问候下方的可选提问。

热点开场问题

POST /v1/agent/opening-questions

{
  "bot_id": "你的智能体ID",
  "user_id": "user-123",
  "count": 5
}

bot_id 必填。count 取值 1–10，非法时按 3 处理。透传火山 GetOpeningQuestion，返回根据全网热点生成的开场问题，不是控制台里的开场白。

埋点

POST /v1/agent/events

{
  "bot_id": "你的智能体ID",
  "request_id": "上游会话 id",
  "user_id": "user-123",
  "event_list": [
    { "event_name": "agent_like", "event_time": 1710000000 }
  ]
}

bot_id 仅用于网关 ACL，转发前会去掉。request_id 与 event_list 必填，最多 20 条。事件名包括 agent_like、agent_copy、agent_follow_up、agent_reference、agent_opening_question_click 等。透传火山 AgentEventLog。

本期不提供作业批改、热点资讯，也不自研用量对账或 180 天审计接口；会话 usage 见 ChatCompletion 响应。

端点

请求