> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 對話

> 接續、分支、列出、分享與刪除 Agent 對話

對話狀態存在伺服器端。你每次只送出一則新的使用者訊息，並用
`metadata.conversation_id` 指定是哪一段對話；Agent 會還原完整的先前脈絡 —
包含它寫過的檔案與學到的內容 — 你不需要重播任何歷史紀錄。

<Note>
  範例使用 DataGen Cloud（`https://api.datagen.dev`）。自架安裝請換成自己的主機，
  例如 `http://10.0.0.42:3001` — 詳見
  [Base URL](/api-reference/agent-api/zh/overview#base-url)。
</Note>

***

## 接續對話

<Steps>
  <Step title="開始一段對話">
    呼叫 `/v1/messages` 時不帶 `conversation_id`。從回應的 **`X-Conversation-Id`**
    header 取得 id — 或是一開始就自訂 id，這樣就可以省略這個步驟。
  </Step>

  <Step title="下一回合帶上該 id">
    ```bash theme={null}
    curl -N -X POST "https://api.datagen.dev/api/agents/data-agent/v1/messages" \
      -H "X-Api-Key: $DATAGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "claude-haiku-4-5",
        "stream": true,
        "metadata": {"conversation_id": "support-ticket-4821"},
        "messages": [{"role": "user", "content": "現在幫我草擬回覆給客戶。"}]
      }'
    ```
  </Step>
</Steps>

<Tip>
  **可以自帶 id。** 尚不存在的 id 會以你送出的字串原樣建立 — 不必是 UUID。直接用你
  的工單編號、Slack 討論串或使用者 id，就不需要另外維護一張對照表。
</Tip>

<Warning>
  **不要在串流結束的瞬間立刻送出下一回合。** 串流關閉的時間，會早於伺服器完成
  「這段對話目前對應哪個工作階段」的紀錄數秒。在這個空窗期送出的訊息，會在尚未有
  工作階段紀錄的情況下接續對話，於是 Agent 會完全不記得剛才那一回合 —
  不會報錯，只是失憶。

  人工打字的節奏不會遇到這個問題，但自動化程式每次都會。在接續一段你剛執行過的
  對話之前，請輪詢 `GET /conversations/{id}` 直到 `claude_session_id` 不為 null：

  ```bash theme={null}
  until curl -s "$BASE/api/agents/$AGENT/conversations/$ID" -H "X-Api-Key: $KEY" \
        | jq -e '.conversation.claude_session_id' >/dev/null; do sleep 0.25; done
  ```

  請設定等待上限，逾時後照常繼續 — 沒有產生任何輸出的回合，本來就不會有工作階段 id。
</Warning>

### id 的解析規則

| `conversation_id`      | 結果                                |
| ---------------------- | --------------------------------- |
| 未提供                    | 建立新對話；id 由 `X-Conversation-Id` 回傳 |
| 不存在的 id                | 以該 id 原樣建立                        |
| 你自己的、屬於這個 Agent        | 接續                                |
| 屬於其他 Agent 或 workspace | `404 Conversation not found`      |
| 別人的、未分享                | `404` — 不會洩漏其存在                   |
| 別人的、已分享至 workspace     | `403` — 可讀不可寫。請改用分支。              |

### 持久性

對話紀錄會持久保存，因此數天或數週後仍可接續。Agent 的沙箱在每一回合後會保持
一段時間的熱狀態，之後才回收；超過之後再接續，第一回合會比較慢，但不會遺失任何脈絡。

<Note>
  如果某個接續中的回合完全沒有產生輸出，接續指標會被清除，下一回合會以全新的工作階段
  開始，而不是永遠靜默地回傳空白。遇到「沒有回應」的對話時，重試是正確的做法。
</Note>

***

## 分支（fork）

在不影響原對話的情況下，分支出去探索另一種可能。

```bash theme={null}
curl -X POST \
  "https://api.datagen.dev/api/agents/data-agent/conversations/{parent-id}/fork" \
  -H "X-Api-Key: $DATAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"at_turn": 2}'
```

```json theme={null}
{
  "conversation_id": "ff3feac1-7da5-48ac-91ca-0064ec9eaa96",
  "parent_conversation_id": "8bb802a6-a001-48d2-8b70-d9c01536c6bc",
  "forked_at_turn": 2,
  "claude_session_id": "6210add3-d666-4474-a6f8-45ee74d536a4"
}
```

| 內容欄位                   | 預設值   | 說明                           |
| ---------------------- | ----- | ---------------------------- |
| `at_turn`              | 全部回合  | 複製到第幾回合為止。超出範圍會自動夾在對話長度內。    |
| `conversation_id`      | 自動產生  | 用你自己的 id 建立子對話。已存在則回傳 `409`。 |
| `model` / `automation` | 沿用父對話 | 記錄在子對話上，供其後續回合使用。            |

子對話由你擁有，預設為私有。它的第一回合會延續父對話的脈絡，之後便走自己的分支 —
父對話不受影響。

***

## 管理對話

以下路由都在 `/api/agents/{agent}/conversations` 之下，使用相同的驗證方式。你可以看到
自己的對話、分享給 workspace 的對話，以及頻道所擁有的對話（Slack、Email）。

| 方法       | 路徑                             | 用途                                                          |
| -------- | ------------------------------ | ----------------------------------------------------------- |
| `GET`    | `/conversations`               | 列出，依最近活動排序                                                  |
| `GET`    | `/conversations/{id}`          | 單一對話的中繼資料                                                   |
| `GET`    | `/conversations/{id}/messages` | 完整對話紀錄                                                      |
| `POST`   | `/conversations/{id}`          | 切換分享狀態 — 內容**必須**是 `{"shared": true}` 或 `{"shared": false}` |
| `POST`   | `/conversations/{id}/fork`     | 分支（見上）                                                      |
| `DELETE` | `/conversations/{id}`          | 刪除，回傳 `204 No Content`                                      |

列表查詢參數：`channel`（`INTERACTIVE`、`NOTEBOOK`、`SLACK`、`EMAIL`）、
`channel_id`、`notebook_path`、`automation=<名稱>`、`since=<iso8601>`，以及
`limit`（1–200，預設 50）。

```json theme={null}
{
  "conversations": [
    {
      "id": "support-ticket-4821",
      "title": "整理昨天失敗的執行紀錄",
      "channel": "INTERACTIVE",
      "shared": false,
      "is_owner": true,
      "claude_session_id": "5a3e26ed-…",
      "parent_conversation_id": null,
      "forked_at_turn_index": null,
      "created_at": "2026-07-31T16:09:28.503Z",
      "updated_at": "2026-07-31T16:09:44.930Z",
      "turn_count": 1
    }
  ]
}
```

`title` 在對話建立時由第一個提示產生，之後不會再更新，因此它永遠代表最初的問題。

### 對話紀錄

`GET /conversations/{id}/messages` 會回傳對話中繼資料、Anthropic 格式的 `messages[]`
陣列，以及供進階用途使用的原始 `events[]` 事件串流。

```json theme={null}
{
  "conversation": { "…": "…" },
  "messages": [
    {
      "role": "user",
      "content": [{"type": "text", "text": "整理昨天失敗的執行紀錄"}],
      "author_user_id": "14d6cade-…",
      "author_name": "alex@example.com"
    },
    { "role": "assistant", "content": [{"type": "text", "text": "有三次執行失敗…"}] }
  ],
  "events": []
}
```

較長的對話會由 Agent 執行環境自動壓縮（compaction）。壓縮會以標記
`is_compact_summary: true` 的 `user` 訊息呈現 — 請把它渲染成「脈絡已壓縮」的提示，
而不是一則使用者訊息。`GET /conversations/{id}/last-compaction` 會回傳
`{compacted, summary}`，讓用戶端能分辨「空回合」與「壓縮步驟」。

### 分享與擁有權

對話在分享之前僅限建立者可見。分享會給予 workspace 成員**讀取**權限，永遠不包含寫入：
成員可以開啟並分支一段分享的對話，但送出訊息會得到 `403`。只有擁有者能切換分享狀態或
刪除對話，管理員也無法越權。