# 豆包智能体

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

## 端点

`POST /v1/agent/chat/completions`

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

## 请求

```json
{
  "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 账户计费。

### 消息内容

文本消息：

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

图文消息：

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

文件消息：

```json
{
  "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` 仅非常权威站点 |

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

```json
{
  "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`

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

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

### 热点开场问题

`POST /v1/agent/opening-questions`

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

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

### 埋点

`POST /v1/agent/events`

```json
{
  "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 响应。

## 相关

企业涉诉 / 涉税风控是**另一条接口**：`POST /v1/agent/risk/chat/completions`，不是本页的豆包透传。见 [风控智能体](/docs/agent-risk)。