GetThreadData - - 阿里雲

取得指定會話的對話資料，按對話發生的先後順序分頁返回每一輪產生的訊息。

介面說明

對話資料以對話輪次為單位組織在 data 中：每個元素對應一輪對話，包含該輪產生的 messages，以及發起該輪對話的請求 ID 與鏈路追蹤 ID。訊息結構與 CreateChat 串流回傳的訊息一致：可透過 callId 與 parentCallId 還原 Agent 的執行層級，透過 contents 取得文字內容，透過 events 取得任務狀態變化，透過 tools 與 agents 瞭解執行過程。對話較長時需按 nextToken 逐頁讀取。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

當前API暫無授權資訊透出。

請求文法

GET /dataagents/{name}/threads/{threadId}/data HTTP/1.1

路徑參數

名稱	類型	必填	描述	樣本值
name	string	否	DataAgent 的名稱，透過請求路徑傳入，用於指定會話所屬的 DataAgent。	order-analysis-agent
threadId	string	否	要查詢的對話 ID，透過請求路徑傳入，由 CreateThread 回傳。	thread-tiirv9-irwdoal8t4rm

請求參數

名稱	類型	必填	描述	樣本值
nextToken	string	否	翻頁遊標。傳入上一次回應返回的 nextToken 可取得下一頁；首次查詢無需傳入。	e81493d42a7d212810e0ac****
maxResults	integer	否	單頁返回的對話輪數，最大為 100。	20

首次查詢只需在路徑中傳入 name 與 threadId；讀取下一頁時，將上一次回應中的 nextToken 原樣作為查詢參數傳入即可。maxResults 不傳時使用預設單頁筆數。

返回參數

名稱	類型	描述	樣本值
	object	回應主體。返回該會話的對話資料與分頁資訊。
data	array<object>	本次返回的會話資料，按對話發生的先後順序分頁返回。
	array<object>	一輪對話的資料。
messages	array<object>	本輪對話產生的訊息列表，包含使用者輸入、Agent 回覆、工具呼叫與狀態事件。
	array<object>	一則訊息。
agents	array<object>	本則訊息中發起的子 Agent 呼叫列表，僅 role 為 assistant 時可能出現。
	object	一次子 Agent 呼叫的資訊。
	any	子 Agent 呼叫明細，常見欄位為 name（子 Agent 名稱）、arguments（本次呼叫的入參）、status（執行狀態：start、progress、success、fail）。	search_data
artifacts	array<object>	本則訊息產出的產出物（檔案）列表，僅 role 為 assistant 時可能出現。
	object	一個產出物。
	any	產物明細，常見欄位為 name（產物名稱）、path（產物路徑）等。可透過 ListArtifacts、GetArtifact 等介面取得已產出的檔案。	report.md
callId	string	本次執行的呼叫識別碼。以該值為 parentCallId 的訊息即為它的下級訊息，可用於還原 Agent 的執行層級。	call_0fdabe9ba7c645a7a6cbf34f
contents	array<object>	本則訊息的內容列表。
	object	一段內容。
	any	內容明細。常見欄位為 type 與 value：type 為 text 時 value 是回覆文字片段；type 為 spin_text 時 value 是 Agent 的思考與執行過程提示；type 為 thread_title_updated 時 value 是更新後的對話標題；type 為 error 時 value 是包含 code 與 message 的錯誤資訊。串流輸出時還帶有 append（是否為增量片段）與 lastChunk（是否為最後一段）標記。	text
detail	string	本則訊息的補充說明，例如目前正在執行的動作描述。	正在分析查詢條件
events	array<object>	本則訊息攜帶的事件清單，用於表達對話狀態的變化。常見 type：thinking（思考中）、interactive（需要您補充輸入或確認）、task_finished（本次任務結束，payload 中帶有 success 與統計資訊）、stream_done（本次串流輸出結束）、error（執行出錯）、thread_title_updated（對話標題更新）。
	object	一個事件。
	any	事件明細，常見欄位為 type（事件類型）與 payload（事件資料，結構隨事件類型不同而不同）。	task_finished
parentCallId	string	父呼叫的識別碼，用於還原執行層級。取值為空字串時表示本次會話的根節點。	thread-tiirv9-irwdoal8t4rm
role	string	訊息的產生方。取值：assistant（Agent 的回覆或動作）、tool（工具執行結果）、user（使用者輸入）、system（系統訊息）。	assistant
seq	integer	訊息序號，在同一次會話中遞增，可用於同級訊息排序。建議同時參考 timestamp，不要強依賴該值。	1
timestamp	string	訊息產生時間，Unix 時間戳記，字串形式。	1765289000
tools	array<object>	本則訊息中 Agent 發起的工具呼叫列表，僅 role 為 assistant 時可能出現。
	object	一次工具呼叫。
	any	工具呼叫明細，常見欄位為 name（工具名稱）、arguments（入參）、status（執行階段狀態：start、success、fail）、state（執行結果：success、fail）、contents（工具輸出內容）。	get_current_time
type	string	訊息類型。常規回覆訊息可以沒有該欄位；當整則訊息用於表達狀態時會出現，例如 done 表示會話結束、error 表示錯誤訊息。	done
version	string	訊息結構版本號，目前為 v0.1.0。	v0.1.0
requestId	string	產生本輪對話的請求 ID，可用於關聯發起該輪對話的 CreateChat 呼叫。	5B0A6B60BB6EE39764D458B5
traceId	string	本輪對話的鏈路追蹤 ID，用於在問題排查時定位本次呼叫。	88b50db22437400fa9c16c5399722310
maxResults	integer	本次請求實際生效的單頁筆數。	20
nextToken	string	下一頁的遊標。未返回時表示已到最後一頁；翻頁時將其作為請求中的 nextToken 傳入。	e81493d42a7d212810e0ac****
requestId	string	本次請求的 ID，用於問題排查時定位本次呼叫。	5B0A6B60BB6EE39764D458B5
threadId	string	本次查詢的會話 ID，與請求路徑中傳入的 threadId 一致。	thread-tiirv9-irwdoal8t4rm

一輪對話資料的結構範例：

{
  "requestId": "1B2E6A9D-8C4F-4E2A-9E7D-3F5A6B7C8D9E",
  "threadId": "thread-tiirv9-irwdoal8t4rm",
  "maxResults": 20,
  "nextToken": "e81493d42a7d212810e0ac****",
  "data": [
    {
      "requestId": "2C3F7B0E-9D5A-4F3B-8E1C-4A6B7C8D9E0F",
      "traceId": "88b50db22437400fa9c16c5399722310",
      "messages": [
        {
          "role": "assistant",
          "callId": "thread-tiirv9-irwdoal8t4rm",
          "parentCallId": "",
          "seq": 4,
          "timestamp": "1765289004",
          "version": "v0.1.0",
          "contents": [
            { "type": "text", "value": "最近 1 小時請求量最高的 URL 為 ……", "append": true, "lastChunk": true }
          ]
        }
      ]
    }
  ]
}

樣本

正常返回樣本

JSON格式

{
  "data": [
    {
      "messages": [
        {
          "agents": [
            {
              "key": "search_data"
            }
          ],
          "artifacts": [
            {
              "key": "report.md"
            }
          ],
          "callId": "call_0fdabe9ba7c645a7a6cbf34f",
          "contents": [
            {
              "key": "text"
            }
          ],
          "detail": "正在分析查询条件",
          "events": [
            {
              "key": "task_finished"
            }
          ],
          "parentCallId": "thread-tiirv9-irwdoal8t4rm",
          "role": "assistant",
          "seq": 1,
          "timestamp": "1765289000",
          "tools": [
            {
              "key": "get_current_time"
            }
          ],
          "type": "done",
          "version": "v0.1.0"
        }
      ],
      "requestId": "5B0A6B60BB6EE39764D458B5",
      "traceId": "88b50db22437400fa9c16c5399722310"
    }
  ],
  "maxResults": 20,
  "nextToken": "e81493d42a7d212810e0ac****",
  "requestId": "5B0A6B60BB6EE39764D458B5",
  "threadId": "thread-tiirv9-irwdoal8t4rm"
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。