DeepSeek Harness Agent 生命週期詳解

DeepSeek Harness Agent 生命週期是一套事件驅動迴圈：使用者的 Follow-up 先進入 Inbox，Driver 啟動 Turn，agent/pre-step 決定下一步是否成立，系統組裝 Prompt、接收模型串流回覆，Tool Call 又可能帶來新的 Step。直到模型不再要求工具，或流程進入 Error、Abort、Cancel 等終止路徑，這個 Turn 才算結束。

本文依據 DeepSeek Harness 官方 Agent 生命週期文件 改寫，目標是協助開發者排查 Agent 停住、重複請求或工具未執行等問題，不是逐行翻譯 Sequence Diagram。

先分清楚 Turn 與 Step

Turn 是由使用者或系統輸入觸發的完整回應週期；Step 則是一次模型請求及其相關工作。一個 Turn 可能包含多個 Step，因為模型可以先要求工具，再根據 Tool Result 繼續呼叫模型。

這也說明了為何只送出一則訊息，卻看到數次 LLM Request。分析用量、Provider Error 與 Tool Loop 時要看 Step；分析對話層級的輸入和完成狀態時，則應觀察 Turn。

從 Agent Inbox 到 Turn Start

使用者 Follow-up 先排入 Agent Inbox。Driver 被喚醒後，將 agent/status 更新為 running，並送出 turn/start，接著領取下一個 Step 和一則排隊 Prompt。

Queue 把「訊息已抵達」與「Agent 已開始執行」分開。訊息可以先等待，介面也能以即時狀態顯示 Agent 所處階段，而不必改寫已持久化的對話。

agent/pre-step 決策點

模型請求開始前，Runtime 會以 Waterfall 方式派送 agent/pre-step。Handler 可以拒絕 Step，也能加入訊息。Step 通過後，系統送出 step/start、寫入相關 User Message，並組裝 Prompt。

這是 Policy 和 Orchestration 的重要 Seam。Handler 可以影響本次模型輸入，但必須區分「改變持久歷史」和「只調整目前 Request」。Session Event 與即時 agent/* Event 的界線，可參考 DeepSeek Harness 架構解析。

模型請求與串流回覆

Prompt 組裝完成後，Harness 向選定的 LLM Provider 發出請求。Assistant Chunk 可以先以串流形式抵達，之後才形成完整的 Assistant Message。

介面可以立即呈現 Chunk，而 Session 只需記錄 Replay 所需的持久訊息。如果 UI 不更新但 Provider 仍在回應，應檢查 Stream 處理與 Client Boundary；若 Request 根本沒有成功，則先檢查金鑰、Endpoint 與 Request Error 路徑。模型設定可參考 模型供應商設定教學。

Tool Call 如何排程

完整 Assistant Response 可能包含 Tool Call。Runtime 會依 Execution Mode 分類，並按需要使用 Barrier 或 Rolling Pool。每次工具呼叫還會經過 Pre Execute、Execute 與 Post Execute 階段。

Execution Mode 決定 Concurrency 和順序。唯讀查詢可能適合重疊執行，修改狀態的命令則可能需要 Barrier。工具作者要正確宣告行為，使用者仍應檢查操作目標與授權範圍。

Tool Result 會加入目前 Context。若 Agent 需要解讀結果或繼續決策，同一 Turn 會進入下一個 Step。可在 工具目錄 查看 Shell、檔案、終端機與 Subagent 等分類。

Retry、Abort 與 Cancel

模型請求失敗時，agent/request-error 可以回傳 Retry Action。Retry Policy 應區分暫時網路問題，以及無效金鑰、錯誤參數或可重現的 Tool Error。後三類問題不斷重試只會增加延遲與費用。

Abort 與 Cancel 是終止控制路徑，應停止等待中的工作、釋放資源，並讓 Agent 回到可理解的狀態。工具必須真正觀察傳入的 Signal，才算支援 Cooperative Cancellation；只有接收參數卻不檢查，無法中止長時間工作。

Session Event 與即時狀態

生命週期使用兩條互補通道：

• session/event 保存 Replay、History 與 Audit 需要的事實；
• agent/* 負責即時控制和 Runtime State。

User Message、Assistant Message 與需要保存的 Tool Result 可以進入 Append-only Session History；running 狀態、串流進度和攔截決策通常屬於即時狀態。混用可能造成 Replay 重複，或重新啟動後少了關鍵事實。

Agent 卡住時的排查順序

1. 確認 Follow-up 是否進入 Inbox；
2. 找出 running 狀態與 turn/start；
3. 檢查 agent/pre-step 是否拒絕或修改 Step；
4. 確認 Prompt 已組裝並送往 Provider；
5. 分清串流 Chunk 與最終 Assistant Message；
6. 檢查工具 Execution Mode、Barrier 與完成事件；
7. 確認錯誤處理選擇 Retry、Abort 還是 Cancel。

依這個順序，可以把「Agent 沒反應」縮小到具體 Boundary。若問題發生在跨處理程序呼叫，請繼續查看 API Gateway 指南。

官方原文

本文依據 DeepSeek Harness 官方 Agent 生命週期文件（中文） 獨立整理，查核日期為 2026-08-20。目前事件順序以官方 Sequence Diagram 為準。