我的知識庫

Orchestration 與 Agent Loop

閱讀時間約 7 分鐘

Agentic 系統的「內部架構」決定了它在多複雜的任務上能走多遠，以及出錯時有多難收拾。這篇拆解 orchestration 的具體模式、LangGraph 的狀態機設計、tool calling 的運作方式，以及非同步長任務、重試冪等性、可觀測性這幾個上 production 必然碰到的問題。

Orchestration 的三種基本模式

順序（Sequential） 任務一個接一個執行：文件抽取 → 分類 → 摘要。最簡單，最好除錯。缺點是整體延遲是各步驟之和，且步驟之間有資料依賴時需要小心傳遞中間結果。

平行／Scatter-Gather 把任務拆開給多個 agent 同時執行，最後匯聚結果。例如把長文件分段後並行讓多個 LLM 摘要，再合併。整體延遲降為最慢那條路徑，但引入了「部分失敗」的處理問題——某一個分支失敗時，其餘結果仍然有效還是要全部重跑？

階層（Hierarchical / Supervisor-Worker） 一個 supervisor agent 決定任務分派，多個 worker agent 各自執行子任務，結果彙報給 supervisor 做後續決策。Microsoft 在 2025 年 10 月發布的 Microsoft Agent Framework 明確採用這個模式，把 AutoGen 的多 agent 對話抽象與 Semantic Kernel 的企業整合能力合併，並在頂層加圖形工作流控制執行路徑。

LangGraph：圖形狀態機

LangGraph 是 LangChain 推出的低層 orchestration 框架，官方文件對它的定位是「為需要 loop、persistence 和 cyclic reasoning 的 stateful multi-agent system 而設計」。

核心概念：

  • 節點（Node）：一個 agent、一個 LLM 調用、或一個工具執行函數
  • 邊（Edge）：節點間的轉移，可以是固定的也可以是條件式的（根據 LLM 輸出動態選擇下一個節點）
  • State：一個所有節點共享、可讀可寫的 typed dict；每個節點可以修改 state，下一個節點讀到的是更新後的值
  • Checkpointing：LangGraph 支援把 state 持久化到資料庫（SQLite、PostgreSQL），讓長任務可以中斷後從斷點恢復

這個設計的工程優勢是：複雜的執行路徑在圖結構中可視化和審計。缺點是引入了顯著的框架學習成本，以及 graph 本身的複雜度可能比直接寫業務邏輯更難維護。

是否一定要用 LangGraph 或任何框架？這是主張不是定論：對於簡單的 2-3 步流程，直接用 LLM API＋手寫狀態管理通常更清晰；框架的價值在步驟多、有複雜分支、需要 checkpointing 的場景才明顯。

Tool Calling 的機制

以 Anthropic Claude 的 tool use 為例（官方文件）：

  1. 工程師在 API request 的 tools 欄位提供工具定義（name、description、input_schema as JSON Schema）
  2. 模型在回應中輸出 tool_use content block，包含 tool_name 和符合 schema 的 input 物件
  3. 宿主程式（你的 server）執行實際函數，把結果包成 tool_result content block 傳回
  4. 模型繼續推理，可以再次調用工具，或輸出最終文字回應

幾個工程現實：

  • 工具描述品質是準確度的關鍵：模型依賴 description 決定何時調用工具、傳什麼參數。描述模糊或有歧義會直接提高錯誤調用率。
  • Parallel tool use：Claude 3.5＋ 支援在一次回應中輸出多個 tool_use blocks，讓宿主程式並行執行；這需要宿主端明確處理並行回傳的 tool_result。
  • 工具調用不是免費的：每個 tool description 佔 token 預算；工具多時系統提示可能佔用大量上下文空間。

非同步長任務與佇列

Agent loop 可能運行數分鐘甚至更長，HTTP request 不能等那麼久。生產系統的標準模式是：

  1. API endpoint 接收任務請求，立刻回傳 job_id（202 Accepted）
  2. 把任務推入佇列（BullMQ、Celery、Cloudflare Queues 等）
  3. Worker 從佇列取任務，執行 agent loop，更新 job 狀態到資料庫
  4. Client 輪詢 /jobs/{id} 或透過 WebSocket／SSE 接收進度事件

佇列帶來的額外工程問題：工作者崩潰後的任務恢復、dead-letter queue 的處理、並發數限制（避免同時打太多 LLM API calls 超出 rate limit）。

重試與冪等性

LLM API 呼叫會失敗（503、rate limit、timeout），agent loop 本身也可能需要重試。冪等性是核心要求：同一個任務重跑兩次，結果必須一致，且不能產生重複副作用（例如發兩封 email）。

工程做法：

  • 每個有副作用的工具調用帶一個 idempotency_key（通常是 job_id + step_index 的 hash）
  • 工具在執行前查詢是否已有相同 key 的記錄；有則直接返回之前的結果
  • LLM 推理本身不是冪等的（非決定性），但業務操作必須是冪等的

可觀測性（Observability）

沒有可觀測性的 agent 系統在 production 裡幾乎無法除錯。主要的工具：

  • LangSmith（LangChain 官方）：自動記錄每個 LLM 呼叫的 input/output/latency/token count，以及整個 chain 的 trace tree
  • Traceloop / OpenLLMetry：基於 OpenTelemetry 標準的 LLM observability，可以把 traces 送到現有的 OTEL backend（Jaeger、Datadog 等），文件
  • Braintrust：除了 traces 還支援 evals 和 production monitoring

必須記錄的最低資訊：每次 LLM 呼叫的 prompt（含 system prompt）、completion、token count、latency、model 版本、任何工具調用的 input/output。沒有這些，出了問題根本不知道 LLM 推理出了什麼。

延伸

關係圖譜

反向連結