對話

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

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

範例使用 DataGen Cloud（https://api.datagen.dev）。自架安裝請換成自己的主機， 例如 http://10.0.0.42:3001 — 詳見 Base URL。

---

接續對話

1. 開始一段對話

   呼叫 /v1/messages 時不帶 conversation_id。從回應的 X-Conversation-Id header 取得 id — 或是一開始就自訂 id，這樣就可以省略這個步驟。

2. 下一回合帶上該 id

   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": "現在幫我草擬回覆給客戶。"}]
     }'
   

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

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

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

id 的解析規則

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

持久性

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

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

---

分支（fork）

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

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}'

{
  "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）。

{
  "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[] 事件串流。

{
  "conversation": { "…": "…" },
  "messages": [
    {
      "role": "user",
      "content": [{"type": "text", "text": "整理昨天失敗的執行紀錄"}],
      "author_user_id": "14d6cade-…",
      "author_name": "[e-mail]"
    },
    { "role": "assistant", "content": [{"type": "text", "text": "有三次執行失敗…"}] }
  ],
  "events": []
}

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

分享與擁有權

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