Mastra：用 TypeScript 把 AI Agent 從原型帶進可維護的應用程式

我一直覺得，AI Agent 最難的部分不是讓模型「回答一次」，而是把它放進一個真正會被使用的產品：它要知道何時該呼叫工具、何時該交給固定流程、如何保留上下文、如何被觀察與評估，還要能和既有的前端、後端及部署方式共存。Mastra 想處理的，正是這段從 demo 到產品的工程落差。

Mastra 是一個以 TypeScript 為核心的 AI 應用程式與 Agent framework。官方 README 將它定位為支援 React、Next.js、Node，以及獨立伺服器部署的框架；它把 model routing、agents、workflows、human in the loop、context management、MCP servers、evals 與 observability 放在同一套開發體驗裡。這個定位很適合 AI Chain 讀者：重點不是再介紹一個聊天機器人，而是拆解一個團隊如何把 Agent 做成可組合、可測試、可持續維護的軟體元件。

先講結論：Mastra 的價值在於把邊界畫清楚

如果你的需求是一次性呼叫模型、把回答顯示在頁面上，Mastra 可能不是必要選擇；直接使用模型供應商 SDK 反而更快。但只要需求開始出現以下任一條件，框架化的價值就會上升：Agent 需要使用多個工具，任務有明確的多步驟流程，使用者必須在關鍵節點核准，團隊需要追蹤每次執行，或產品同時支援不同模型供應商。

我對 Mastra 的主要判斷是：它不是只把 LLM API 包一層，而是提供一個讓「不確定的推理」與「確定的程式流程」共存的結構。Agent 適合處理步驟未知的開放式任務；workflow 則把執行順序、分支與平行處理寫成可檢查的圖。這種分工比「所有事情都丟給一個超級 Agent」更容易除錯，也比較容易向產品與資安團隊說明。

Mastra 到底提供哪些組件？

1. Model routing：先降低供應商耦合

官方文件使用 provider/model 的字串格式描述模型，例如 openai/某個模型名稱。這種介面把模型選擇集中在一個可讀的設定值，而不是把特定供應商的 provider object 散落在每個 Agent 裡。當團隊需要比較不同模型，或因為成本、延遲、資料治理而更換供應商時，這個抽象層能減少改動面。

不過，這不代表模型切換沒有代價。不同模型在工具呼叫、結構化輸出、上下文長度與推理風格上仍可能有差異。model routing 解決的是連接方式與設定管理，不會自動替你完成模型評估。因此我會把它視為「降低切換成本的入口」，而不是「模型品質的保證」。

2. Agents：把開放式任務交給推理迴圈

Mastra 官方對 Agent 的定義很清楚：Agent 使用 LLM 與 tools 解決開放式任務，依目標決定要呼叫哪些工具、迭代幾次，以及何時停止。你提供的是目標、限制與工具邊界，而不是把每一個步驟寫死。

最小的 Agent 可以只有 id、name、instructions 和 model。如果要提供工具，官方文件建議用 createTool 建立帶有 id、描述、Zod schema 與 execute 的工具，再把工具傳入 Agent。這裡有一個值得注意的工程原則：工具不是一段隨手塞進去的函式，而是具有輸入契約與執行邊界的介面。對想把 Agent 接到企業資料或外部 API 的團隊來說，這是安全性與可測試性的起點。

下面是官方文件概念的精簡版本，示範一個只負責回答天氣問題的 Agent：

import { Agent } from '@mastra/core/agent'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: 'You are a helpful weather assistant.',
  model: 'provider/model-name',
})

這段程式碼真正重要的不是名稱，而是責任分離：Agent 描述要完成的任務，model 指定推理引擎，工具則在另一個明確的模組中定義。正式專案應再補上錯誤處理、權限、輸入驗證、逾時與觀測資料，不能把這個最小範例直接當成生產設定。

3. Workflows：把可預測流程寫回程式碼

當任務的步驟其實是確定的，例如先查詢訂單、再檢查庫存、最後產生通知，使用 workflow 比使用一個自由決策的 Agent 更合適。Mastra 的 workflow engine 以圖形化的多步驟流程為核心，官方 README 提到可以用 .then()、.branch() 與 .parallel() 表達順序、分支和平行執行。

這個差異可以用一句話概括：Agent 決定「下一步該做什麼」，workflow 規定「哪些步驟可以做、依什麼順序做」。兩者不是競爭關係，而是可以互相組合。你可以讓 workflow 在固定節點呼叫 Agent，也可以讓 Agent 使用一個已經被權限與 schema 約束好的 workflow。

我認為這是 Mastra 最值得寫進架構圖的部分。很多 Agent demo 看起來很靈活，但一進入產品就會遇到不可重現、難以回溯與無法估算成本的問題。把確定的流程移回程式碼，讓模型只負責真的需要推理的決策，通常會得到更穩定的系統。

4. Human in the loop：讓暫停成為正式狀態

真實工作流常常不能完全自動化。例如退款、發送對外訊息、修改權限或提交交易，都可能需要使用者或主管核准。Mastra 支援暫停 Agent 或 workflow，等待輸入或批准後再恢復；官方 README 也說明它會透過 storage 保存執行狀態，因此流程可以暫停一段時間後再繼續。

這和在 prompt 裡寫「遇到重要事情請先詢問」是兩回事。Prompt 只是行為建議；可保存的 suspend and resume 狀態才是系統能力。前者可能因模型誤判而被跳過，後者可以在應用程式層建立真正的審核介面、權限規則與逾時處理。

5. Context、memory 與 RAG：不要把所有資料塞進 prompt

Agent 要做出一致決策，需要在正確時間取得正確上下文。Mastra 將 conversation history、從 API、database 或檔案取回資料的 RAG，以及 observational memory 都列為 context management 的一部分。

這裡最容易犯的錯是把 memory 當成「把所有歷史訊息永久塞進上下文」。更好的做法是先定義資料的生命週期：哪些是本輪任務的暫時狀態，哪些是使用者偏好，哪些是需要權限控制的企業資料，哪些內容只能透過檢索即時取得。框架提供能力，不會替你決定資料保留期限、刪除流程、個資遮罩或租戶隔離；這些仍然是產品設計與治理責任。

6. Evals 與 observability：從「看起來能跑」到「知道哪裡壞」

官方文件將 evals 用於評估 Agent 輸出，並提供像是分類、摘要、工具選擇與 prompt engineering 等不同方向的 scorer；live evaluations 則可以在 Agent 或 workflow 執行時非同步評分。Observability 則讓團隊看見每次 Agent run、workflow step、tool call 與 model interaction。

這兩者應該一起設計。只做 observability，你會看到系統做了什麼，但不一定知道結果是否好；只做 evals，你可能知道分數下降，卻找不到是哪個工具、哪個步驟或哪次模型切換造成問題。對生產 AI 來說，trace 是除錯材料，eval 是品質訊號，兩者都不能等上線後才補。

如何開始：先建立一個可驗證的最小專案

Mastra 官方 README 建議使用以下 CLI 建立專案：

npm create mastra@latest

實際上手時，我會採用以下順序，而不是一開始就把所有功能打開：

準備執行環境。 先確認本機可以執行 npm、能安裝套件，並準備你要使用的模型供應商金鑰。不要把金鑰寫入 Git，也不要把它硬編碼進 Agent 的 instructions。
用 CLI 建立專案。 先選一個單一用途的 Agent，例如回答內部產品文件問題。第一個任務應該小到可以用三到五個測試案例判斷成功或失敗。
註冊 Agent。 官方文件的基本結構是從 @mastra/core/agent 匯入 Agent，建立 Agent 後，再於 src/mastra/index.ts 以 Mastra 註冊。這讓同一個 Agent 可以被 workflow、tool 或其他 Agent 取用。
先跑通 Studio。 官方 quickstart 指向 Mastra Studio，啟動開發伺服器後可在 http://localhost:4111 開啟，用來建立、測試與管理 agents、workflows 和 tools。這個介面很適合先檢查工具呼叫與輸出，再把整合接到正式 UI。
最後才增加外部工具與記憶。 每加入一個工具，就先定義輸入 schema、權限、錯誤結果與逾時策略；每加入一種 memory，就先寫清楚保存什麼、保存多久，以及誰可以讀取。

第一個可驗證任務不應是「做一個萬能助理」，而是像「讀取指定文件並回答三個固定問題」。這樣可以同時驗證模型設定、Agent 指令、上下文注入、輸出格式與錯誤處理。完成後，再把單一工具擴展成 workflow，最後才考慮多 Agent 協作。

Agent、workflow、skills 與多代理團隊不要混為一談

這幾個詞常被放在同一張簡報裡，但它們解決的層級不同。

Agent 是能根據目標進行推理與工具選擇的執行單位，適合步驟未知的任務。
Workflow 是可重跑、可檢查的協調邏輯，適合步驟、分支與依賴關係清楚的任務。
Skills 比較像可重用的知識、規則或操作包，讓 Agent 知道如何處理某一類工作；它不必然等於一個獨立的推理執行個體。
多代理團隊 是把多個角色組合起來，可能由一個 coordinator 分派任務，也可能由 workflow 控制順序。它的複雜度、成本與觀測需求都高於單一 Agent。

Mastra 的組件可以讓這些層級互相組合，但框架不會自動替你做架構判斷。我的建議是從單一 Agent 開始，只有當責任邊界、工具集合或上下文真的分裂時，才引入第二個 Agent。很多系統不是模型不夠強，而是協作層級太早增加，導致每次錯誤都要跨越更多不可見狀態。

限制與導入前的檢查清單

第一，模型差異仍然存在。統一的 model routing 不能抹平不同模型的能力、價格、延遲與安全政策。至少要準備一組自己的任務集，測試工具呼叫成功率、拒答、格式正確性與成本。

第二，Agent 的自主性需要邊界。工具的 schema、權限、可存取資料與可執行副作用都要在程式碼與基礎設施層限制，不要只依賴自然語言指令。尤其是會寫資料、寄信、付款或修改設定的工具，應該預設加入 human in the loop 或明確的 approval gate。

第三，可觀測不等於可治理。有 trace 只代表你能回看執行過程；你仍要決定哪些資料可以記錄、哪些內容必須遮罩、trace 保存多久，以及誰能查看。若系統處理客戶資料，這些問題應在第一個 prototype 就納入設計。

第四，授權模式需要看清楚。Mastra README 說明核心框架與大部分程式碼採 Apache License 2.0，但名稱為 ee 的目錄採 Mastra Enterprise License，正式環境使用相關企業功能需要有效授權。導入前要閱讀完整 LICENSE.md，不能因為 repository 是公開的，就假設所有目錄與所有使用情境都具有相同授權條件。

第五，不要把 Studio 當成完成品的替代物。Studio 適合開發、測試與理解 Agent 行為；正式產品仍需要自己的身份驗證、權限、網路隔離、錯誤回復、成本控制與部署策略。

我會怎麼評估是否採用？

我會把評估分成三個階段。第一階段只驗證開發體驗：能不能在團隊熟悉的 TypeScript 專案中建立 Agent、掛一個工具、跑通 Studio，並且讓新成員看懂檔案邊界。第二階段驗證可靠性：加入 workflow、暫停恢復、錯誤重試、trace 和一組固定 evals，觀察結果是否可重現。第三階段才驗證產品條件：模型成本、資料治理、權限、部署方式與授權。

如果團隊已經有成熟的 Node 或 TypeScript stack，又確實要做 agents、tool calling、RAG 與工作流協調，Mastra 值得放進短名單。它的優勢不是讓每個人都能一句 prompt 做出產品，而是把多個常見 AI application patterns 放入一個較完整的工程框架。

反過來說，如果產品只是單一 API 呼叫、團隊不需要 workflow 或 observability，直接使用既有 SDK 會更輕量。若團隊主要使用另一種語言，也應先評估跨語言服務邊界，而不是為了追逐熱門工具強行改變整個技術棧。

結語：真正的問題不是能不能建立 Agent，而是能不能長期維護

Mastra 的吸引力，在於它把 AI Agent 從一段 prompt 與 API call，拉回到熟悉的軟體工程語境：有模組、有流程、有工具契約、有狀態、有評估，也有觀測資料。這種轉變不會消除 Agent 的不確定性，但能讓不確定性被分隔、被測量、被限制。

我會把它推薦給正在從 demo 走向產品的 TypeScript 團隊，而不是推薦給只想快速試一次模型的個人開發者。最好的導入方式也不是一次採用全部模組，而是先用一個小型、可驗證的 Agent 建立基線，再逐步加入 workflow、memory、human approval、evals 與 observability。當每一個新增能力都有清楚的理由，Mastra 才會成為工程上的槓桿，而不是另一個需要被維護的抽象層。

參考資料