# 發起對話

`POST` `/v1/ai/agents/{agent_id}/conversations`

向指定 Agent 提問。可以開啟一個全新會話，也可以傳入已有會話的 `chat_uid` 在同一會話中追加提問。

Agent 會結合行情、賬戶等能力生成回答。當 Agent 需要你補充信息或確認時，本次運行會**中斷**（`status` 為 `interrupted`），此時需通過 [繼續對話](/zh-HK/docs/ai/chat/continue) 回傳答案後才能繼續。

通過請求頭 `Accept` 選擇響應模式：`text/event-stream` 為 SSE 流式，逐步推送運行過程與回答；其他值為阻塞式，一次性返回聚合後的最終結果。

:::tip 如何獲取 Agent 的 UID
除通過 Workspace 下的 Agent 接口查詢外，也可以直接從 Longbridge 網頁端獲取：打開 Agent 的對話頁，URL 形如 `https://longbridge.com/zh-HK/ai/agents/chatbot/chat`，其中 `chatbot` 即為該 Agent 的 UID。
:::

## Parameters

### Path Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | Yes | 目標 Agent 的 UID，需為已發佈 Agent |

### Request Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | 用戶問題，不能為空 |
| `chat_uid` | string | No | 已有會話標識。傳入則在該會話中繼續提問，不傳則新建會話 |
| `parent_message_id` | string | No | 父消息 ID，取上一輪響應中的 `message_id`。在已有會話中追加提問時傳入，將本輪消息掛在指定消息之後，保證消息流順序。僅在傳入 `chat_uid` 時有效，且父消息必須屬於該會話；新會話不可傳 |

## Request Example

```bash
curl --request POST \
  --url 'https://openapi.longbridge.com/v1/ai/agents/<agent_id>/conversations' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"<query>","chat_uid":"<chat_uid>","parent_message_id":"<parent_message_id>"}'
```

## Response

### Response Properties

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `chat_uid` | string | Yes | 會話標識，追加提問或排查問題時使用 |
| `message_id` | string | Yes | 本輪消息 ID（字符串形式） |
| `status` | string | Yes | 運行終態：`succeeded` / `interrupted` / `failed` / `stopped` |
| `answer` | string | No | 最終回答文本，`status` 為 `succeeded` 時有效 |
| `references` | object[] | No | 回答引用的資料來源，無引用時為 `null` |
| `elapsed_time` | number | No | 運行耗時（秒） |
| `interrupt` | object | No | 僅當 `status` 為 `interrupted` 時出現 |
| `└ node_id` | string | Yes | 觸發中斷的節點 ID |
| `└ tool_call_id` | string | Yes | 本次詢問對應的工具調用 ID，繼續對話時作為答案的 key |
| `└ questions` | object[] | Yes | 需要你回答的問題列表 |
| `└ ∟ question` | string | Yes | 問題文本 |
| `└ ∟ options` | object[] | No | 可選項，為空表示自由作答 |
| `└ ∟∟ description` | string | No | 選項文本 |
| `└ ∟ multi_select` | boolean | No | 是否允許多選 |
| `└ message_id` | int64 | No | 被暫停的消息 ID |
| `└ chat_id` | int64 | No | 所屬會話 ID |
| `error` | object | No | 僅當運行出錯時出現 |
| `└ code` | int32 | No | 錯誤碼 |
| `└ message` | string | No | 錯誤信息 |

### Response JSON Example

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "chat_uid": "ct_9f2c1a5b",
    "message_id": "42",
    "status": "succeeded",
    "answer": "Tesla (TSLA.US) recently...",
    "references": [
      {
        "index": 1,
        "title": "...",
        "url": "..."
      }
    ],
    "elapsed_time": 3.21
  }
}
```
