AI 代理人設計

核心哲學

代理人並非魔法——它們是具備輸入、輸出、記憶、工具和決策邏輯的系統。請以與任何生產級軟體相同的嚴謹態度來設計它們。每個代理人都應有明確的目的、定義的邊界，以及明確的失敗模式。

代理人設計原則

1. 行動前先釐清意圖

代理人必須在使用者意圖不明確時，先詢問釐清問題——然後再執行任何不可逆的操作。使用以下模式：

目標是否明確？如果不明確，則提出一個重點問題。
是否已知限制條件？（範圍、輸出格式、資料來源）
成功的模樣是什麼？

2. 規範先於程式碼

在撰寫代理人邏輯之前，先產出一個規格或任務列表檔案：

定義代理人的角色與職責
列出其需要存取的所有工具
定義輸入/輸出合約
找出失敗模式與備援行為
然後再撰寫程式碼

3. 單一職責

每個代理人應專注做好一件事。優先採用一群專業代理人，而非一個通用型代理人。

編排模式

模式	使用時機	描述
順序 (Sequential)	線性管線	代理人按固定順序執行（草稿 → 審查 → 發佈）
監督者 (Supervisor)	複雜多模組任務	主導代理人將任務路由給專業工作者
ReAct	自主解決問題	結合推理（思考）+ 行動（工具使用）
群組聊天 (Group Chat)	協作任務	多人通訊，並有人類監督
DAG	有狀態工作流程	有向無環圖，用於循環、有狀態的編排

框架選擇指南

框架	最佳用途	狀態
LangGraph	複雜的有狀態代理人、循環工作流程、多代理人編排、生產級應用	✅ 活躍 — 2025年5月正式發行
LangChain	簡單的 RAG 管線、線性工作流程、快速原型	✅ 活躍 — 適用於 RAG，不適用於代理人
CrewAI	基於角色的多代理人團隊（「經理」、「研究員」、「作家」）	✅ 活躍
Microsoft Agent Framework	Azure 生態系統中的企業代理人 — 取代 AutoGen + Semantic Kernel	✅ 活躍 — 2025年10月公開預覽，目標2026年第一季正式發行
AutoGen	舊版 — 仍可運作但無新功能	⚠️ 維護模式（自2025年10月起）
自訂 (MCP)	輕量、可攜、可互通的代理人工具，基於開放標準	✅ 活躍

LangChain vs LangGraph — 該使用哪個

LangChain 團隊現已明確建議如下分工：

LangGraph → 用於代理人：有狀態、循環、多代理人、長時間執行的任務
LangChain → 用於 RAG 和線性管線：簡單的文件問答、逐步轉換

LangGraph 建立在 LangChain 之上——你可以兩者一起使用，先從 LangChain 開始，當需要更多控制時再轉向 LangGraph。

RAG 管線設計

標準 RAG 流程

使用者查詢 → 嵌入查詢 → 向量搜尋 → 取回區塊 → 擴充提示 → LLM → 回應

分塊策略（2026 年最佳實務）

使用語意分塊——依據意義來分割，而非字元數
區塊大小：256–512 個 token 以取得精確度；1024 個 token 用於敘述性內容
務必包含元資料：來源、頁面、章節、時間戳記

混合搜尋（建議採用）

結合密集向量（語意）+ 稀疏向量（關鍵字）以獲得最佳召回率：

最終分數 = α × 密集分數 + (1 - α) × 稀疏分數

向量資料庫選擇

資料庫	最佳用途
pgvector	現有的 PostgreSQL 技術堆疊、簡單使用案例
Pinecone	受管、生產規模、最低維運成本
Weaviate	多模態、內建混合搜尋
Milvus	高效能、自架、大規模
Chroma	本機開發、原型製作

代理人記憶體架構

類型	描述	實作方式
情境內 (In-context)	當前對話視窗	聊天歷史陣列
外部短期 (External short-term)	工作階段範圍的記憶體	Redis / 記憶體內儲存
外部長期 (External long-term)	跨工作階段持久化	向量資料庫 + 元資料
情節式 (Episodic)	摘要化的過去互動	摘要化鏈 → 向量儲存

情境衰減警告： 過長的上下文視窗會隨著時間降低代理人品質。每 N 輪執行一次摘要步驟，以維持相關性。

工具使用與函式呼叫

工具定義模式

每個工具都需要：

name: descriptive_tool_name
description: 何時使用此工具及其功能（明確說明）
parameters:
  - name: param_name
    type: string
    description: 此參數預期的內容
    required: true

工具使用最佳實務

工具應盡可能具備冪等性
在傳遞至下一步之前，務必驗證工具輸出
為外部工具呼叫實作逾時與重試機制
記錄所有工具呼叫以供除錯

代理人通訊模式

意圖釐清協定

當代理人收到模糊的請求時：

找出模糊點——具體來說是什麼不清楚？
提出一個問題——最重要的那一個，而不是全部
提出預設值——「除非您告訴我其他方式，否則我將假設 X」
在不可逆操作前確認——在刪除、發佈或發送之前務必詢問

進度回報

對於長時間執行的任務，代理人應回報：

[步驟 1/4] 正在擷取文件... ✓
[步驟 2/4] 正在分塊與嵌入... ✓
[步驟 3/4] 正在查詢向量儲存...

錯誤通訊

✗ 工具失敗：[工具名稱]
原因：[具體錯誤]
備援：[我改採的替代方案]

MCP（模型上下文協定）

MCP 是將代理人連接到外部工具與資料來源的開放標準。在建立可攜、可互通的代理人工具時使用它。

MCP 伺服器結構

my-mcp-server/
├── server.py （或 index.ts）
├── tools/
│   └── my_tool.py
└── README.md

何時使用 MCP 與直接整合

當工具需要在多個代理人/平台間重複使用時，使用 MCP
對於專案特定、一次性工具實作，使用直接整合

請參閱 mcp-builder 技能以取得詳細的 MCP 伺服器實作指引。

安全性與安全

切勿允許代理人在沒有沙箱的情況下執行任意程式碼
對所有 LLM API 呼叫實作速率限制
在傳遞至工具之前，驗證並清理所有輸入
記錄所有代理人決策以供稽核
實作護欄以防止失控的 token 成本或遞迴迴圈
使用系統提示注入防護——使用明確的分隔符號將使用者輸入與系統指令分開

韌性代理人設計（自我修復）

代理人在生產環境中會失敗。從一開始就設計恢復機制。

驗證與重試迴圈（LoopAgent 模式）

產生輸出 → 驗證輸出 → 若無效：回饋 + 重新產生
最大迭代次數：3  ← 斷路器，防止無限迴圈

規劃–驗證–執行–觀察–重新規劃

規劃：     產生計劃，在行動前檢查可行性
執行：     採取行動
觀察：     是否成功？檢查輸出、執行測試
重新規劃： 若觀察結果顯示失敗 → 調整並重試
停止：     若達到最大重試次數 → 清楚回報失敗，請求協助

代理人備援層級

主要方法失敗 → 嘗試替代方法
替代方法失敗 → 向開發者請求釐清
未取得釐清   → 安全預設動作或優雅停止

呈現前輸出驗證

在呈現產生的程式碼之前，先執行測試/lint
驗證輸出格式是否符合需求
使用獨立的驗證步驟（不同的模型或提示）來檢查產生器的輸出
切勿將未經驗證的輸出呈現為已完成

代理人的斷路器

設定硬性限制以防止失控行為：

每項任務的最大工具呼叫迭代次數（例如 10 次）
每個工作階段的最大 token 花費
每個失敗步驟的最大重試次數（例如 3 次）
每個工具呼叫的逾時時間

請參閱 self-healing-mindset 技能以取得完整的韌性哲學與程式碼範例。

在你喜歡的 AI 中提問

說明文件