wen aidev
Published on

Microsoft Agent Framework 完整指南 03：實戰經驗與開發避坑指南

Table of Contents

這是系列文的最後一篇。我們將脫離架構圖與理論，直接進入 「開發第一線」 的戰壕。

這是基於早期採用者（包括 BMW, Commerzbank 等先行企業）與社群 Issue 回饋的血淚經驗總結。如果你正準備將 Agent 投入生產環境，這篇文章可能會幫你省下數週的除錯時間。

必備神器：DevUI 視覺化除錯

以前開發 Semantic Kernel 時，我們常陷入 Console.WriteLine 地獄。要看清楚 "Agent A 到底傳了什麼給 Agent B"，往往要翻閱幾百行的 JSON Log。

Agent Framework 引入了 DevUI，這是一個革命性的本地開發工具。

# 啟動本地除錯伺服器 (需先安裝相關套件)
devui ./agents --port 8080

DevUI 能做什麼？

  1. 即時拓撲圖 (Live Topology)：它會自動解析你的程式碼，畫出 Agent 之間的連接關係。如果是並行 (Concurrent) 或循序 (Sequential) 流程，圖表一目瞭然。
  2. 攔截與檢閱 (Intercept & Inspect)：你可以點擊流程圖中的任何一條連線，查看：
    • Prompt：Agent 實際發送給 LLM 的完整 Prompt（包含 System Message 與 Context）。
    • Response：LLM 原始回傳的內容。
    • State：當下的變數狀態。
  3. 時光回溯：在 Durable 模式下，你可以拉動時間軸，看 Agent 在 "昨天下午 3 點" 是什麼狀態。

強烈建議：在專案啟動的第一天，就配置好 Team 的 DevUI 環境。它能將除錯效率提升至少 50%。

⚠️ 開發避坑指南 (Gotchas)

這些限制大多是為了保護資源或目前的技術瓶頸，但在開發時很容易撞牆。

🛑 陷阱 1：巢狀工具呼叫 (Nested Tool Call) 深度限制

錯誤訊息：Error: Maximum tool call depth of 5 exceeded

場景：你設計了一個超強 Agent A。

  • Agent A 呼叫 Tool X (例如 "查詢資料庫")。
  • Tool X 內部其實是呼叫另一個 Agent B (例如 "SQL 生成專家")。
  • Agent B 又呼叫 Tool Y...

目前 Azure AI Agents 強制限制 5 層 深度。這是為了防止 Agent 陷入死回圈（Infinite Loop）瞬間燒光你的 Token 額度。

解法：

  1. 扁平化設計：盡量減少 "Tool 包 Agent" 的設計。
  2. 改用 Workflow：將邏輯提升到 Workflow 層級。使用 Events 來觸發下一個步驟，而不是在 Tool 內部隱式呼叫。讓 Workflow 變成「扁平的流水線」而非「深層的遞迴」。

🛑 陷阱 2：Token 爆炸 (Context Explosion)

在 Group Chat (群聊模式) 中，預設的行為是「廣播」。 為了讓每個 Agent 都能接話，系統會將 完整的對話歷史 傳給每一個參與的 Agent。

想像一下：

  1. Agent A 講了一段話 (100 tokens)。
  2. Agent B 回覆 (100 + 200 tokens)。
  3. Agent C 回覆 (100 + 200 + 300 tokens)...

對話輪數一多，Token 消耗是呈 指數級增長 的。

解法：

  1. Memory Summarization：實作一個 Middleware（或使用 SK 的 Summary Plugin），在每一輪對話後自動摘要重要資訊，只保留摘要給下一個 Agent。
  2. 精準路由 (Targeted Routing)：在某些場景下，Agent C 其實不需要知道 Agent A 說了什麼。透過程式邏輯控制 Context 的可見範圍。

🛑 陷阱 3：Python 與 .NET 的 ID 不一致

如果你試圖建立一個「混合語言」系統（Python Agent + .NET Agent 互相溝通），請注意目前的 SDK 版本中，兩者生成的 Thread ID 與 Resource ID 格式可能不完全相容。

建議：在 SDK 完全成熟前，單一子系統 (Sub-system) 最好統一使用同一種語言開發（全 C# 或全 Python）。

遷移策略：我該現在轉移嗎？

如果你的團隊正在使用 Semantic Kernel 或 AutoGen，以下是遷移建議：

  1. 簡單的 Chat / RAG 應用 (基於 SK)： 👉 暫時不用動。如果你的應用只是一問一答，或者只是簡單的 Plugin 呼叫，Semantic Kernel 已經夠穩定且高效。強行遷移到 AF 反而會增加架構複雜度（引入 Orchestrator 等）。

  2. 多代理系統 (基於 AutoGen 0.2)： 👉 強烈建議遷移。AutoGen 0.2 的架構較為發散，且缺乏企業級的狀態管理。AF 提供了更嚴謹的 Durable 機制與 Azure 整合，這對於長期維護至關重要。

  3. 全新專案： 👉 直接使用 Agent Framework。雖然目前仍是預覽版，學習曲線較陡，但它是微軟未來 3-5 年的 AI 架構標準。現在投入學習，未來的技術債最少。

總結

Microsoft Agent Framework 是一個充滿野心的專案。它試圖在 AutoGen 的「靈活性」與 Semantic Kernel 的「工程紀律」之間找到平衡。

它並不完美（深度限制、API 變動），但配合 Azure 的 Managed Identity、Durable Functions 與 Content Safety，它無疑是目前在微軟生態系上構建 複雜、企業級 AI Agent 的最佳基石。

希望這系列文章能幫助你在 AI Agent 的開發之路上少走冤枉路，打造出真正能落地、創造價值的應用！

📚 系列導覽

留言討論