> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md).

# 连接 API

为你的 Convai 角色建立一个实时聊天机器人会话，使用户能够通过音频或视频连接并保持对话上下文。

此 **Connect API** 用于在终端用户与 Convai 角色之间建立实时交互会话。重复使用返回的 `character_session_id` 可在不同连接之间延续对话上下文。

{% hint style="warning" %}
本页中的 Actions 协议 v2 字段描述的是可选择启用的候选功能。此处列出这些字段并不代表其已在生产环境中可用，也不代表已有已发布的 SDK 版本。请先验证目标环境返回的所选功能，再决定是否依赖这些功能。
{% endhint %}

## 连接到角色

<mark style="color:绿色;">`POST`</mark> `https://live.convai.com/connect`

### 请求头

<table><thead><tr><th width="199">名称</th><th width="108.9998779296875">类型</th><th>说明</th></tr></thead><tbody><tr><td>X-API-Key<mark style="color:红色;">*</mark></td><td>字符串</td><td>你的 Convai API 密钥。</td></tr><tr><td>Content-Type</td><td>字符串</td><td>必须设为 <code>application/json</code>.</td></tr></tbody></table>

***

### 请求正文

单角色会话只需要 `character_id`；其他字段均有服务器端默认值。多角色房间需发送 `characters` 以及非空的 `end_user_id` ，而不是 `character_id`.

**会话身份**

| 名称                     | 类型   | 说明                                                                                                                                     |
| ---------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `character_id`         | 字符串  | 要连接的角色的唯一 ID。单角色会话必填；发送 `characters`.                                                                                                  |
| `connection_type`      | 字符串  | 连接模式。 `"audio"` （默认值）、 `"video"`或 `"text"`.                                                                                            |
| `character_session_id` | 字符串  | 用于延续对话的现有会话 ID。若省略，则会生成一个新的 ID。                                                                                                        |
| `end_user_id`          | 字符串  | 你为终端用户设置的唯一标识符。用于标记会话并启用长期记忆。发送 `characters`时，以及使用 `mode: "join"` 和房间定位符（`room_session_id` 或 `shared_session_key`）加入现有房间而非连接到角色时，均为必填。 |
| `end_user_metadata`    | JSON | 与终端用户关联的任意元数据。响应中会原样返回。                                                                                                                |

**多角色房间**

多角色房间仅对已启用此功能的账户开放，且仍受账户的角色数和参与者数限制。

| 名称           | 类型   | 说明                                                                                                                                                                                                                                                                                                                               |
| ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `characters` | JSON | 按顺序排列的 `{ "character_id", "character_session_id" }` 条目，每个角色实例对应一个；第一个条目是初始实例。 `character_id` 为必填项，且必须是未加引号的 UUID； `character_session_id` 为可选项，用于延续该实例之前的对话。请发送 `character_id` 或 `characters`，不能同时发送。参见 [使用多角色会话](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md). |
| `group_chat` | 布尔值  | 启用房间群聊，让多个实例对同一条消息作答。默认值为 `false`。创建时固定；加入房间时会继承此设置。参见 [构建群聊](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/build-a-group-chat.md).                                                                                                                                                          |
| `room_brief` | 字符串  | 最多 4000 个字符，作为上下文提供给房间中的每个角色，包括之后添加的角色。创建时固定。仅在 `group_chat: true`.                                                                                                                                                                                                                                                              |

**角色行为与上下文**

| 名称                        | 类型                                  | 说明                                                                                                                                                           |
| ------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action_config`           | [JSON](#action_config)              | 会话的语义动作能力以及可选的、由客户端执行的工具声明。参见 [响应约定与解析](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md). |
| `capabilities`            | [JSON](#agentic-actions-v2-preview) | 显式指定协议选项。省略此字段可保留旧版 v1 响应格式。                                                                                                                                 |
| `dynamic_info`            | [JSON](#dynamic-info)               | 用于影响对话流程的实时上下文数据。                                                                                                                                            |
| `scene_description`       | [JSON](#scene_description)          | 当前场景或环境的描述。仅作为描述性上下文—— **不会授予动作能力**.                                                                                                                         |
| `narrative_template_keys` | JSON                                | 替换角色提示模板中内容的键值对。                                                                                                                                             |
| `emotion_config`          | JSON                                | 情绪检测和表达的配置。                                                                                                                                                  |
| `thinking_mode`           | 布尔值                                 | 启用模型在回复前进行扩展推理。默认值为 `false`.                                                                                                                                 |
| `respond_modes`           | JSON                                | 按模态控制何时必须由角色作出回复。                                                                                                                                            |

**模型与提供商**

| 名称                      | 类型  | 说明                                                                         |
| ----------------------- | --- | -------------------------------------------------------------------------- |
| `llm_provider`          | 字符串 | `"dynamic"` （默认值）、 `"gemini-live"`, `"gemini-live-beta"`或 `"gemini-baml"`. |
| `stt_provider`          | 字符串 | 覆盖此会话的语音转文本提供方。                                                            |
| `disable_live_fallback` | 布尔值 | 阻止回退到非实时模型。默认值为 `true`.                                                    |

**音频、语音与轮次交互**

| 名称                      | 类型                    | 说明                                                                                                                                                                       |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `audio_config`          | [JSON](#audio_config) | 音频输出行为。仅适用于 LiveKit 传输（默认）。                                                                                                                                              |
| `default_tts_enabled`   | 布尔值                   | 机器人音频是否默认启用。默认值为 `true`。之后可通过 [`tts-toggle`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#tts-toggle). |
| `default_stt_enabled`   | 布尔值                   | 麦克风输入是否默认启用。默认值为 `true`。之后可通过 [`stt-toggle`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#stt-toggle). |
| `vad_params`            | JSON                  | 语音活动检测调优参数： `confidence`, `start_secs`, `stop_secs`, `min_volume`.                                                                                                       |
| `turn_detection_config` | JSON                  | 轮次检测策略覆盖项。                                                                                                                                                               |

**虚拟形象与视觉**

| 名称                    | 类型   | 说明                                                                                                                                                                                                                                                                                                                                 |
| --------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blendshape_provider` | 字符串  | `"not_provided"` （默认值）、 `"ovr"`或 `"neurosync"`。决定您接收哪种面部动画消息。                                                                                                                                                                                                                                                                      |
| `blendshape_config`   | JSON | 提供方专属的混合形状配置。                                                                                                                                                                                                                                                                                                                      |
| `vision_input_config` | JSON | 视觉输入配置，包括采样窗口。启用视觉环形缓冲区，该缓冲区由 [`vision-status`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#vision-status) 和 [`vision-trigger`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#vision-trigger). |
| `video_track_name`    | 字符串  | 传入视频轨道的名称。默认值为 `"camera"`.                                                                                                                                                                                                                                                                                                         |

**多参与者会话**

| 名称                     | 类型  | 说明                                                                  |
| ---------------------- | --- | ------------------------------------------------------------------- |
| `max_num_participants` | 整数  | 房间内 **人类** 参与者的最大数量。默认值为 `1`。角色实例不计入此处；名册大小由 `characters` 并由账户设置上限。 |
| `shared_session_key`   | 字符串 | 用于确定性地将参与者分配到同一房间的分组键。长度为 1–128 个字符，包含字母数字字符以及 `-` 和 `_`.           |
| `mode`                 | 字符串 | `"create"` （默认值）或 `"join"`.                                         |
| `room_name`            | 字符串 | 要创建或加入的明确房间名称。                                                      |

**诊断**

| 名称                    | 类型   | 说明                                               |
| --------------------- | ---- | ------------------------------------------------ |
| `debug`               | 布尔值  | 启用 RTVI 指标、 `turn-trace`和 `server-log` 数据通道上的消息。 |
| `debug_row_cap`       | 整数   | 覆盖每个会话的诊断行数上限。仅当 `debug` 为 `true`.               |
| `invocation_metadata` | JSON | 调用方提供的归因和分析元数据。                                  |

{% tabs %}
{% tab title="action\_config" %}

```json
{
  "actions": ["Move To", "Pick Up", "Drop", "Follow"],
  "objects": [
    { "name": "cube",  "description": "A red cube on the table" },
    { "name": "lever", "description": "A metal lever on the wall" }
  ],
  "characters": [
    { "name": "Player", "bio": "The current user" },
    { "name": "Guard",  "bio": "A nearby guard" }
  ],
  "current_attention_object": "cube"
}
```

**字段**

**`actions`** —角色可能发出的语义动作名称。接受字符串数组或 `{ "value": "..." }` 对象数组。Convai 会先验证语义动作名称，再通过 [`action-response`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#action-response).

**`objects`** — `{ name, description }` 条目，用于为语义动作目标提供依据并进行验证。

**`characters`** — `{ name, bio }` 条目，用于为语义动作目标提供依据并进行验证。

**`current_attention_object`** —用户当前正在注视或提及的对象名称。用于确定“ *这个*, *那个*”等代词所指的对象，以及 *"它"*。必须与以下 `objects[].name` 值之一匹配。接受字符串或完整对象。

`actions`, `objects`和 `characters` 用于约束旧版语义动作投影。仅在 `scene_description` 中提及的对象不会成为语义动作目标。由客户端执行的 v2 工具使用其自身的 JSON Schema 参数，并且执行前仍需经过客户端授权。

整个契约可在会话中途通过 [`context-update`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#context-update).
{% endtab %}

{% tab title="动态信息" %}

```json
{
    "text": "string"
}
```

{% endtab %}

{% tab title="场景描述" %}

```json
[
  {
    "name": "string",
    "description": "string"
  }
]
```

{% endtab %}

{% tab title="音频配置" %}

```json
{
  "output": {
    "audio_routing": "audio_only", // 默认值："audio_only" | "data_only" | "both"
    "max_chunk_duration_ms": 100, // 默认值：100，范围：10-1000ms
    "add_wav_header": false // 默认值：false
  }
}
```

**字段**

**`audio_routing`** - 控制音频传输方式：

* `"audio_only"` （默认）- 标准 WebRTC 音轨（推荐）
* `"data_only"` - 接收 `audio-data` 消息，通过数据通道进行自定义处理
* `"both"` - 通过音轨和数据通道接收

**`max_chunk_duration_ms`** - 音频分块大小（10-1000ms，默认值：100ms）

* 值越低 = 延迟越低、开销越大
* 值越高 = 更适用于不稳定的网络
* 向上取整到最接近的 10ms： `95ms → 100ms`, `45ms → 50ms`

**`add_wav_header`** - 在数据通道分块中包含 WAV 文件头（默认值：false）

* 仅在使用 `data_only` 或 `both` 路由时适用
  {% endtab %}
  {% endtabs %}

***

## Agentic Actions v2 预览版

协议选择彼此独立。仅请求客户端实际实现的行为：

```json
{
  "character_id": "CHARACTER_ID",
  "capabilities": {
    "action_protocol_version": 2,
    "model_output_version": 2,
    "bot_llm_text_mode": "legacy"
  },
  "action_config": {
    "actions": ["Wave"],
    "objects": [],
    "characters": [],
    "tools": [
      {
        "name": "open_training_record",
        "description": "操作员确认记录 ID 后，打开训练记录。",
        "inputSchema": {
          "type": "object",
          "properties": {
            "record_id": { "type": "string" }
          },
          "required": ["record_id"]
        }
      }
    ]
  }
}
```

| 字段                                     | 取值                   | 行为                                                                                                                                                                    |
| -------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `capabilities.action_protocol_version` | `1` 或 `2`            | 版本 `2` 启用关联的客户端工具调用和 [`action-result`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result). |
| `capabilities.model_output_version`    | `1` 或 `2`            | 版本 `2` 启用规范的 [`model-output`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#model-output) 消息。        |
| `capabilities.bot_llm_text_mode`       | `"legacy"` 或 `"raw"` | `"legacy"` 保留经过筛选的聊天投影。 `"raw"` 通过 `bot-llm-text`流式传输提供方可见的文本；未经应用审核，切勿执行或朗读此流。                                                                                       |
| `action_config.tools`                  | 工具声明数组               | 声明可由客户端（而非 Convai）在验证每次调用后执行的工具。需要 action protocol v2。                                                                                                                |

每个工具声明都必须包含 `name`, `description`以及以对象为根的 `inputSchema`。根架构接受 `type`, `properties`和 `required`；属性架构中可以使用受支持的验证关键字。工具名称必须唯一，必须以字母或下划线开头，并且只能包含字母、数字、下划线或连字符。

候选实现强制执行以下限制：

| 限制       | 值           |
| -------- | ----------- |
| 每个连接的工具数 | `32`        |
| 工具名称     | `64` 个字符    |
| 工具描述     | `1,024` 个字符 |
| 序列化输入架构  | `16 KiB`    |
| 输入架构嵌套深度 | `8`         |

任何 v2 操作选择、v2 模型输出选择或原始 `bot-llm-text` 选择都需要 `mode: "create"`、单个 `character_id`、没有 `shared_session_key`，并且 `max_num_participants: 1`。不支持加入式、名册式、共享会话及多参与者拓扑。

角色的显式 **启用智能体操作** 设置仍具有决定性。当该设置关闭时，Convai 不会向模型添加 Actions 合约、语义操作工具或客户端工具架构。如果未设置该项，则拥有一个或多个已保存旧版角色操作的角色，会在模型输出 v1 和 v2 中继承启用状态；没有已保存旧版操作的角色，其模型输出 v2 默认为关闭。读取此继承状态不会持久化新设置。即使 Actions 关闭，仍可生成纯文本模型输出 v2。

客户端工具还要求已解析的模型支持提供方原生函数调用。仅进行能力协商并不会授权使用工具，也不保证所选模型能够调用该工具。

工具声明的作用范围是连接级别的。 [`context-update`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#context-update) 可以替换语义操作列表，但不能替换 `action_config.tools`；要更改工具集，请重新连接。

当请求包含 `capabilities`时，响应会返回所选字段：

```json
{
  "capabilities": {
    "action_protocol_version": 2,
    "model_output_version": 2,
    "bot_llm_text_mode": "legacy"
  }
}
```

如果请求未包含 `capabilities`，响应中也不会包含该字段。此时会话使用操作协议 v1、模型输出 v1 和旧版 `bot-llm-text` 行为。

***

### 响应

{% tabs %}
{% tab title="200：成功。已创建与你的角色对应的 WebRTC 房间。" %}

```json
{
  "session_id": "<你的实时会话临时会话 ID>",
  "request_trace_id": "<此 /connect 请求的服务器端跟踪 ID>",
  "character_session_id": "<你的会话 ID。对于新会话，将返回新生成的值；否则返回旧值>",
  "room_url": "<客户端需要加入的房间 URL>",
  "room_name": "<要加入的房间名称>",
  "token": "<客户端加入房间所需的令牌>",
  "end_user_id": "<会话中用户的 end_user_id；如果请求中未发送，则为 null>",
  "end_user_metadata": "<与最终用户关联的元数据；如果请求中未发送，则为 null>",
  "room_session_id": null,
  "active_membership_id": null,
  "route_epoch": null,
  "roster_epoch": null,
  "partial_dispatch": false,
  "characters": null
}
```

最后六个键会出现在每个响应中，且仅在 roster room 中填充。

| 字段                     | 类型              | 说明                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id`           | 字符串             | 此实时会话的临时令牌。                                                                                                                                                                                                                                                                                                                                          |
| `request_trace_id`     | 字符串             | 服务器端跟踪 ID。提交支持请求时请附上此 ID——它可将您的会话与服务器日志、遥测数据和会话记录关联起来。                                                                                                                                                                                                                                                                                               |
| `character_session_id` | 字符串             | 对话会话 ID。稍后再次调用 `/connect` 即可继续同一对话。                                                                                                                                                                                                                                                                                                                  |
| `room_url`             | 字符串             | 客户端加入的 room 的 URL。                                                                                                                                                                                                                                                                                                                                   |
| `room_name`            | 字符串             | Room 名称。仅适用于 LiveKit 传输。                                                                                                                                                                                                                                                                                                                             |
| `token`                | 字符串             | 用于加入 room 的身份验证令牌。                                                                                                                                                                                                                                                                                                                                   |
| `end_user_id`          | String \| null  | 从请求中回显。                                                                                                                                                                                                                                                                                                                                              |
| `end_user_metadata`    | Object \| null  | 从请求中回显。                                                                                                                                                                                                                                                                                                                                              |
| `capabilities`         | Object          | 仅当请求明确包含 `capabilities`时才会出现。包含服务器选定的协议字段。                                                                                                                                                                                                                                                                                                           |
| `room_session_id`      | String \| null  | 用于标识 room；随每条 room 命令发送。任何 roster room 都会填充此字段，包括 `mode: "join"` 响应； `null` 单角色会话则为此值。                                                                                                                                                                                                                                                               |
| `active_membership_id` | String \| null  | 当前接收用户轮次的角色实例。创建时，这是第一个 `characters` 条目；加入时，则是当时处于活动状态的实例，因为 [切换活动角色](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md#switch-the-active-character) 会改变此值。任何 roster room 都会填充此字段； `null` 单角色会话则为此值。                                                                                     |
| `route_epoch`          | Integer \| null | 在首条 room 命令中将其作为 `expected_route_epoch` 发送。任何 roster room 都会填充此字段，包括 `mode: "join"` 响应； `null` 单角色会话则为此值。                                                                                                                                                                                                                                            |
| `roster_epoch`         | Integer \| null | 将其作为 `expected_roster_epoch` 在第一条 `character-roster-update`。对于任何角色阵容房间都会填充，包括 `mode: "join"` 响应； `null` 单角色会话则为此值。                                                                                                                                                                                                                                   |
| `partial_dispatch`     | 布尔值             | `true` 如果有任何角色实例启动失败。始终 `false` 单角色会话则为此值。                                                                                                                                                                                                                                                                                                           |
| `characters`           | 数组 \| null      | 每个角色实例对应一个条目： `membership_id`, `session_id`, `is_initial`, `provisioning_status`, `failure_code`, `display_name`, `description`以及中列出的标识符 [使用多角色会话](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md#map-each-character-instance)。对于任何角色阵容房间都会填充，包括 `mode: "join"` 响应； `null` 单角色会话则为此值。 |
| {% endtab %}           |                 |                                                                                                                                                                                                                                                                                                                                                      |

{% tab title="404：未找到。为请求生成响应失败" %}

```json
{
    "detail": "未找到角色，或该角色不属于此用户"
}
```

{% endtab %}

{% tab title="422：请求格式错误时" %}

```json
{
    "detail": [
        {
            "type": "<type_of_issue_with_the_request_body>",
            "loc": [],
            "msg": "<message>",
            "input": "<input value>",
            "ctx": {
                "error": "more details about the error"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

***

## 重要说明

{% hint style="warning" %}
Convai 严格遵循 **OpenAI 内容政策** 关于 API 的使用规定。\
用户不得生成或传播有毒、有害或不当内容。\
屡次违规将导致您的 API 密钥被 **列入黑名单**.
{% endhint %}

重复使用相同的 `character_session_id` 以在交互之间保持上下文。新的 `character_session_id` 会在没有先前对话上下文的情况下启动会话。

***

## 请求示例

{% tabs %}
{% tab title="Python" %}

```python
import requests

url = "https://live.convai.com/connect"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<your api key>"  # 替换为你的实际 Convai API 密钥
}

data = {
    "character_id": "<your character id>",
    "connection_type": "audio",  # 或 "video"
    "character_session_id": "string"  # 可选
## 如需指定场景描述
##    "scene_description": [
##        {
##            "name": "string",
##            "description": "string"
##        }
##    ],
##如需指定动态信息
##    "dynamic_info": {
##        "text": "string"
##    },
}

response = requests.post(url, headers=headers, json=data)

print("Status Code:", response.status_code)
print("Response:", response.text)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location 'https://live.convai.com/connect' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <your api key>' \
--data '{
    "character_id": "<your character id>",
    "connection_type": "audio", // 或 "video"（用于视频功能）
    "character_session_id": "string" // 可选
    "dynamic_info": { // 可选
        "text": "string"
    },
    "scene_description": [
        {
            "name": "string",
            "description": "string"
        }
    ], // 可选
}'
```

{% endtab %}
{% endtabs %}

***

## 连接后

使用以下内容加入房间： `room_url` 和 `token`。此后，整个会话都通过 WebRTC 数据通道上的消息以及音轨来驱动。

* [轮次生命周期与消息顺序](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md) — 机器人轮次如何传递，以及可以依赖的消息顺序
* [响应约定与解析](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md) — 旧版文本、规范输出、操作和原始文本之间的区别
* [客户端到服务器的消息](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md) — 更新上下文、切换音频、发送文本
* [服务器到客户端的消息](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md) — 你接收的所有内容的完整字段参考


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
