【實戰】Day 20：AI Agent 系統規格書：訂單決策與預測智能體的架構設計

我們已經在 Day 18 處理了資料庫，並在 Day 19 開發了專屬的 API。接下來就可以直接寫 Prompt 讓 AI 開始運作了嗎？

開發 AI Agent 最忌諱的就是直接開始堆疊 Prompt，這會導致系統在後期變得無法維護與擴充。在真正動手寫 Agent 程式碼之前，我們必須像傳統軟體工程一樣，先寫出一份清晰的系統規格書 (System Requirement Specification, SRS)。

本篇文章，我們將為鞋墊廠定義這套「訂單決策 Agent」的架構藍圖。

• 1. 系統目標與應用場景 (System Objectives)
  • 核心測試情境 (Use Case)
• 2. 雙模式決策機制 (Agent Decision Modes)
  • 模式 A：直接決策模式 (Single-Agent Direct Action)
  • 模式 B：多人討論決策模式 (Multi-Agent Debate)
• 3. 技術選型與架構藍圖 (Tech Stack & Architecture)
  • 系統架構圖 (五層式設計)
• 4. 五層式企業級架構 (Layered Architecture)
• 實用建議：三個起步行動
  • 步驟 1：定義「不要做什麼」
  • 步驟 2：寫下清晰的角色 Persona
  • 步驟 3：設計退場機制 (Human-in-the-loop)
• 我的反思

1. 系統目標與應用場景 (System Objectives)

這個 AI Agent 系統不是用來聊天的，而是用來輔助高階主管進行商業決策。系統的核心目標有兩個：

1. 歷史訂單分析與決策：根據過去兩年的資料，評估利潤與出貨健康度。
2. 未來訂單預測：結合季節性因素與歷史波動，給出產能預估。

核心測試情境 (Use Case)

業務主管的提問：「請給我下一季 NIKE 訂單的評估建議。」

面對這個問題，系統必須能夠自動調用 API 查閱 NIKE 過去的訂單量、鞋墊種類分佈（PU發泡 vs EVA成型），並綜合產能狀況給出包含「預計訂單量」與「接單建議」的完整報告。

2. 雙模式決策機制 (Agent Decision Modes)

為了解決不同複雜度的問題，我們的系統將設計為「雙模式路由架構」。當用戶提出問題時，系統的 Gateway 會自動判斷應該啟用哪一種模式：

模式 A：直接決策模式 (Single-Agent Direct Action)

• 適用場景：簡單、明確的單一數據查詢或趨勢整理。
• 運作方式：由一個強大的「數據分析 Agent」獨挑大樑。它接收問題後，直接呼叫 FastAPI，拿到 JSON 數據後立刻進行運算並輸出結果。
• 優點：反應速度極快，消耗 Token 少。

模式 B：多人討論決策模式 (Multi-Agent Debate)

• 適用場景：遇到充滿不確定性、需要跨部門權衡的複雜決策（例如：是否要接一張急單？下一季的整體產能規劃？）。
• 運作方式：系統會喚醒一個虛擬團隊，包含：
  1. 業務 Agent（專注於客戶關係與營收最大化）
  2. 生管 Agent（專注於工廠產能與交期是否會 Delay）
  3. 財務 Agent（專注於毛利率與成本控制）
• 決策過程：業務提出接單，生管可能因為產能吃緊而反對，財務則依照過往該品牌（如 Adidas）的單價來評估利潤是否值得加班。三方在虛擬會議室中反覆辯論，最後由「總經理 Agent」總結出一份綜合建議書。

3. 技術選型與架構藍圖 (Tech Stack & Architecture)

為了實現上述的雙模式決策，我們將採用以下技術棧：

1. 大腦模型 (LLM)：推薦使用 Claude 3.5 Sonnet 或 GPT-4o，因為它們在 Function Calling（呼叫 API）與長文本推理的能力上目前表現最穩定。
2. 單一代理人框架 (Mode A)：採用 Pydantic AI。它的強型別特性，能確保 Agent 從 API 拿到的 JSON 資料被精準解析，不會出現資料錯置。
3. 多智能體框架 (Mode B)：採用 CrewAI 或 AutoGen。它們天生就具備「角色扮演」與「團隊對話」的底層機制，非常適合用來實作跨部門的辯論會議。
4. 記憶體機制 (Memory)：使用短期的對話視窗（Buffer Memory）來維持會議上下文，並搭配向量資料庫來儲存長期的「過去決策紀錄」。

系統架構圖 (五層式設計)

4. 五層式企業級架構 (Layered Architecture)

為了確保 AI 的「決策計算」絕對正確，且系統具備極高的擴充性與安全性，我們將採用企業標準的分層解耦設計：

1. AI Agent Layer (大腦意圖層)：純粹負責理解主管的自然語言問題，並規劃解決步驟。
2. User Context / Memory Layer (主管偏好與記憶層)：未來在 Day 22，我們將專門實作這一層。讓系統能根據登入的主管，自動套用他們喜歡的格式（例如：總經理喜歡看圖表，財務長只看毛利率數據）。
3. Agent Tool Layer (工具封裝層)：在明天的 Day 21，我們將動手實作這層。把生硬的底層 API，包裝成帶有說明書的 Tools 交給 AI。
4. Business API Layer (商業邏輯層)：也就是我們 Day 19 寫的 FastAPI。這是此架構最精華的地方：假設要「分析訂單毛利率」，我們會在這裡寫一個獨立的 Python Method；要「預測訂單」，再寫另一個 Method。AI 不負責算數學，它只負責「呼叫正確的 Method」，從而保證 100% 的準確率。
5. Data Service Layer (數據庫層)：最底層的 PostgreSQL 乾淨中介庫。

實用建議：三個起步行動

在為公司撰寫 AI Agent 系統規格書時，請務必釐清以下三點：

步驟 1：定義「不要做什麼」

在規格書中，比起條列 Agent 能做什麼，更重要的是寫下限制（Guardrails）。例如：「Agent 絕對不能直接修改 PostgreSQL 的訂單數據」、「Agent 不能承諾客戶降價」。這決定了你後續防護網的設計。

步驟 2：寫下清晰的角色 Persona

如果要啟用「多人討論模式」，請在規格書中為每一個 Agent 寫下詳盡的背景設定。生管 Agent 的 Prompt 必須明確指示它「極度厭惡延遲交貨」，財務 Agent 必須「對利潤率低於 15% 的訂單提出警告」。

步驟 3：設計退場機制 (Human-in-the-loop)

AI 決策牽涉到真實營收時，絕對不能讓它「完全自動駕駛」。規格書必須規範明確的退場底線。 實戰案例【紅線數值防護】：當 Agent 接收到一份新訂單評估請求，雖然產能允許，但它透過 API 算出這批鞋墊的預估毛利率只有 8%（低於公司規定的 15% 紅線）。此時 Agent 絕對不能自動拒絕客戶，而是必須暫停流程並發送警告給人類主管：「🚨 低利潤警報：此訂單毛利僅 8%。是否要授權 Agent 啟動『降價談判腳本』，還是由您親自接手處理？」

我的反思

AI Agent 的開發，與傳統的軟體工程其實非常相似。很多人拿到 LangChain 或是 CrewAI 就開始瘋狂地把工具串在一起，最後做出來的系統往往像是一個不受控制的黑盒子，稍微遇到意料之外的提問就會崩潰。

「寫規格書」這個看似老派的動作，其實是在幫 AI 界定它的能力邊界。

有了這份清晰的系統規格與架構藍圖，我們終於可以捲起袖子，在明天的文章中，開始動手撰寫這套「雙模式訂單決策 Agent」的核心程式碼了！