開源 AI Agent 框架實作比較與追蹤

這篇教你選開源 AI Agent 框架、接上 Langfuse 追蹤，並完成第一個可驗證的代理流程。

如果你正在為 Python 或 TypeScript 專案挑選 agent framework，這篇可以直接帶你縮小選項，並在第一天就把觀測資料接好。照做完，你會得到一個能跑的最小代理流程、一條可在 Langfuse 檢視的 trace，以及一份適合你技術棧的框架判斷。

本文以 Langfuse 的框架比較內容為基礎，重點放在實作路線而不是空泛排名。你會先選出控制風格，再把 SDK、工具呼叫、追蹤、護欄與基準測試串成一條可驗收的工作流。

開始之前

• Node 20+，若你要用 TypeScript 框架，例如 Mastra、Vercel AI SDK 或 Strands Agents。
• Python 3.10+，若你要用 LangGraph、Claude Agent SDK、Google ADK、Pydantic AI、CrewAI 或 Strands Agents。
• 一個 Langfuse 帳號與專案，用來收 trace、span、prompt 和 evaluation。
• 至少一組模型 API key，例如 OpenAI、Anthropic、Google Gemini 或 AWS Bedrock。
• 本機已安裝 Git，方便你 clone 範例 app 或自己的 agent service。
• 具備 tool calling、async code 與環境變數的基本操作能力。

Step 1: 選定控制風格

目的：先決定你要自己掌握多少 orchestration。LangGraph 與 Google ADK 適合明確流程；OpenAI Agents SDK 與 Claude Agent SDK 適合管理式 loop；Pydantic AI 適合重視型別驗證的 Python 團隊；Mastra 與 Vercel AI SDK 則偏向 TypeScript-first 產品。

判斷規則很簡單：如果你需要分支、重試與人工核准發生在固定節點，就先選 graph-based 框架。若你想用最少組裝完成可用 loop，就先選 loop-first SDK。若你最在意輸入輸出驗證與開發體驗，就先從 Pydantic AI 開始。

驗收：你應該能用一句話說出選擇，例如「我需要明確狀態控制，所以選 LangGraph。」

Step 2: 安裝 SDK 與追蹤客戶端

目的：建立一個能送出 trace 的本機專案。先安裝你選定的框架，再加入 Langfuse client 或該框架文件建議的 OpenTelemetry 整合。

npm install @langfuse/client @vercel/ai-sdk

如果你是 Python 專案，就改裝對應的框架套件與 Langfuse Python SDK。接著在執行 app 之前，先設定 Langfuse public key、secret key 與 host 等環境變數。

驗收：你應該看到套件安裝完成沒有錯誤，而且 .env 已包含框架需要的金鑰。

Step 3: 建立單工具代理迴圈

目的：先證明框架能呼叫工具並回傳有用答案，再加多代理或工作流複雜度。第一版只保留一個 model、一段 prompt、一個 tool 與一條輸出路徑。

例如接上一個天氣查詢、檔案讀取或資料庫查詢工具。若框架支援 handoff、subagent 或 workflow，先不要用，先確認基本 loop 真的能跑通。

驗收：你應該看到代理回應中包含工具結果，而不是只有模型猜測。

Step 4: 把執行寫進 Langfuse

目的：把代理執行記錄下來，方便檢查 prompt、tool call、延遲與失敗原因。依照框架整合文件加入 tracing hooks 或 middleware，然後送出一次測試請求。

打開 Langfuse 專案後，確認 trace 內有 root run，並且 model call 與 tool call 都各自形成 child span。若框架支援結構化 metadata，請把框架名稱、模型名稱與環境一起附上，方便日後篩選。

驗收：你應該在 Langfuse 看到一條新 trace，而且至少有一個 model span 與一個 tool span。

Step 5: 加上護欄與流程控制

目的：在流量進來前，先把代理變得更安全、更可預測。加入框架原生的控制，例如輸入驗證、輸出 schema、權限 allowlist、retry、checkpoint 或 human-in-the-loop interrupt。

控制方式要跟框架特性對齊。Pydantic AI 用 typed input 與 output。CrewAI 用角色定義，再包進 Flows。LangGraph 或 Google ADK 用明確分支與重試路徑。Claude Agent SDK 或 OpenAI Agents SDK 則用 hooks、guardrails 或 handoffs 來限制行為。

驗收：你應該能丟出一個無效輸入，並看到代理拒絕或改道，而不是靜默失敗。

Step 6: 對照基準 trace

目的：用觀測資料判斷第一版是否足夠。對同一個 prompt 跑幾次，對照 trace，找出不穩定的 tool 使用、重試過多，或 context 無謂膨脹。

接著記錄 latency、cost 與 success rate 的基準值，方便後續版本比較。Langfuse 最有價值的地方，是把 traces 當成開發資產，而不只是上線後的儀表板。

驗收：你應該拿到一組可重複的 baseline trace，並列出下一輪要改善的項目。

常見錯誤

• 因為品牌熟悉度選框架，而不是依控制需求選。修法：先對照 workflow control、type safety 或 managed loop，再決定框架。
• 單代理 loop 還沒跑通就先做多代理協作。修法：先把一個 tool、一段 prompt、一條 trace 做穩，再加 handoff 或 subagent。
• 等到 production 才接觀測。修法：在第一個 prototype 就串 Langfuse，提早看見 prompt、tool 與 retry 問題。

接下來可以看什麼

當第一個 agent 已經可追蹤且穩定，下一步就進入框架專屬強化：加入 eval、建立 prompt versioning、替 tool call 製作 regression test，並比較重試、記憶成長與人工核准流程下的表現。