Mastra：TypeScript 專案該不該把 agent 交給這套框架

Mastra 想解決的是散落各處的 AI 黏著層

多數 TypeScript 團隊做 AI 功能的路徑都差不多：先用官方 SDK 打通一次模型呼叫，接著自己寫一層 provider 切換，然後補上工具呼叫的迴圈、對話歷史的儲存、retry 與逾時。等到要加人工審核關卡，才發現前面那套臨時結構撐不住，只能再包一層狀態機。Mastra 的定位就是把這幾層收斂成同一個框架，README 的敘述是「a framework for building AI-powered applications and agents with a modern TypeScript stack」，並強調可以整合 React、Next.js、Node，或當成獨立 server 部署。它的目標讀者不是剛接觸 LLM 的人，而是已經在寫正式服務、不想再自己維護一套 agent runtime 的工程團隊。

值得注意的是它把 agent 與 workflow 當成兩種不同的東西並列，而不是硬把兩者揉成一個抽象。README 對 agent 的描述是：agent 會推理目標、決定用哪些工具，並在模型給出最終答案或命中停止條件前反覆迭代。workflow 則是另一條路，當你需要對執行順序有明確控制時才用。這個切分在實務上很關鍵，因為「讓模型自己想」和「流程必須照順序跑」是兩種完全不同的除錯體驗，混在一起寫的框架通常兩邊都做不好。

agent 迴圈與 workflow 圖是兩套不同的執行模型

agent 的執行機制在 README 裡寫得相當直白：模型負責推理與選工具，框架負責迭代，直到模型輸出最終答案，或觸發可選的停止條件。也就是說控制權在模型手上，你能介入的地方是工具集合與停止條件，而不是每一步的順序。這種設計適合開放式任務，例如查資料、比對、再彙整，但你很難事先保證它會走哪條路。

workflow 走的是相反的路。README 說明它是以圖為基礎的執行引擎，用 .then()、.branch()、.parallel() 這幾個方法表達控制流。這代表分支與並行是寫在程式碼裡、可被檢視的結構，不是模型臨場決定。對需要合規紀錄、或流程本身有法定順序的場景，這個差異決定了能不能上線。

兩者交界處是 human-in-the-loop。README 的 suspend-and-resume 章節說明：agent 或 workflow 可以暫停，等待使用者輸入或核准後再繼續，而執行狀態是靠 storage 記住的，所以可以無限期暫停，之後從中斷處接回。這裡的關鍵字是 storage：暫停能力不是憑空來的，它綁定在你選的儲存後端上。如果你的部署環境沒有穩定的持久化儲存，這個功能就只是文件上的承諾。

從 npm create mastra 到 Studio 的第一條路徑

README 把 CLI 列為建議的起手方式，指令是 npm create mastra@latest。它同時提供一段可貼給 coding assistant 的提示，裡面把參數講得更清楚：先問專案名稱（預設 my-mastra-app），再問 provider，選項限於 openai、anthropic、google、xai，若填了不支援的值就重新詢問。實際執行的形式是 npm create mastra@latest <project-name> -- --llm <provider>。

依 README 描述，這道指令會建立預設專案、為偵測到的 coding assistant 安裝 Mastra skills，並在合適的情況下初始化 Git。接著進入專案目錄啟動 dev server，README 給的例子是 npx bgproc start -n <project-name> -w -- npm run dev，然後開 http://localhost:4111 進 Mastra Studio，在那裡建置、測試與管理 agent、workflow 與工具。

有幾點文件沒有交代清楚，導入時要自己確認。第一，provider 清單只有四個，但模型路由頁面聲稱可接 40+ 個 provider，兩者關係在 README 裡沒有說明，CLI 是否只負責預設設定、其餘靠路由層補上，得看官方文件。第二，bgproc 是專案提供的輔助工具還是通用工具，README 沒有解釋。第三，Studio 預設綁在 4111 埠，正式環境要不要暴露這個介面、如何加上驗證，README 沒有著墨。這些不是缺點，而是文件在入門段落刻意留白，實作前要自己去原始碼或官方文件補齊。

雙軌授權：ee/ 目錄不是 Apache-2.0

這是本文最需要讀者停下來看的一段。README 的 Licensing 章節寫明這個 repository 採雙軌授權：核心框架與絕大多數程式碼是 Apache-2.0；但任何名為 ee/ 的目錄，例如 packages/core/src/auth/ee/，是以 Mastra Enterprise License 釋出，屬於 source-available。README 的措辭是這些功能在正式環境需要有效的 enterprise license，但可自由用於開發與測試。

對工程團隊的實際影響是：你不能只看 npm 上的套件名稱就假設整包是 Apache-2.0。授權邊界畫在目錄層級，而不是套件層級。以 auth 相關路徑為例，如果你的產品需要身分驗證功能，就要先確認你依賴的是哪一個目錄下的實作，再對照 LICENSE.md 的完整對應表與 ee/LICENSE 的條文。

這裡不提供法律意見，只指出操作面的做法：在架構評估計畫裡加一項「列出所有會用到的功能，逐一對照它在 repo 中的路徑」，而不是等上線前才由法務翻授權。GitHub 的授權標示顯示為 NOASSERTION，這與雙軌授權的實況一致，也提醒自動化授權掃描工具在這類專案上容易給出誤導性的結果。

記憶、RAG 與 MCP 是它的整合面，也是抽象成本

README 把 context management 拆成三塊：對話歷史、從 API 或資料庫或檔案檢索資料（RAG）、以及它稱為 Observational Memory 的機制，用來讓 agent 行為保持連貫。這三塊各自有文件頁面，但 README 沒有說明它們在儲存層如何共用或隔離。對已經有自己 RAG 管線的團隊，這意味著你要嘛把現有管線接進來，要嘛改用它的檢索層，兩者的取捨在文件首頁看不出來。

MCP 是另一個整合面。README 說明你可以用 Mastra 撰寫 Model Context Protocol server，把 agent、工具與其他結構化資源透過 MCP 介面暴露出去，供任何支援該協定的系統或 agent 存取。這個方向的好處是把你的 agent 變成可被外部消費的端點，而不是鎖在自己的應用裡。代價是你要多維護一層協定邊界，且 MCP 的存取控制與授權並不在 README 的說明範圍內。

前端整合方面，README 提到可搭配 Vercel 的 AI SDK UI 與 CopilotKit 這類 agentic 函式庫。這代表 Mastra 沒有打算自己做完 UI 層，而是把串流與狀態同步交給既有生態。這個選擇合理，但也意味著你的前端堆疊若不在這個名單上，整合成本要自己承擔。

什麼情況下 Mastra 是錯的工具

第一種情況是流程本身高度確定。如果你的「AI 功能」其實是固定的三步：取輸入、呼叫模型、寫回資料庫，那 workflow 引擎、storage、Studio 全都是多餘的。你需要的是一層薄薄的 SDK 封裝，而不是一套 runtime。框架帶來的抽象在這種規模下只會讓除錯變慢。

第二種情況是團隊主力在 Python。Mastra 的定位寫得很清楚，是為 TypeScript 打造，README 全篇圍繞 npm、Node、Next.js 與 React。跨語言使用不是它的設計目標，硬接只會讓兩邊的型別與部署流程都變複雜。

第三種情況是你需要對模型呼叫做非常細緻的控制，例如自訂的 token 預算演算法、非標準的串流協定、或特殊的重試語意。agent 迴圈把迭代交給框架，你能調整的是工具與停止條件；當你的需求落在框架沒有開放的位置，就得往下讀原始碼或繞過它。這不是缺陷，而是「框架」與「函式庫」的根本差別，選之前要想清楚你要哪一種。

還有一種容易被忽略的情況：暫停續跑依賴 storage，而 storage 的行為在 README 裡只有一句帶過。如果你的環境無法保證執行狀態被可靠寫入與讀回，human-in-the-loop 這條路就不成立，而你可能是為了這個功能才評估 Mastra 的。

替代路線：Vercel AI SDK 與自己組裝的差別

最直接的替代是 Vercel 的 AI SDK。README 本身就把 AI SDK UI 列為前端整合選項，說明兩者不是互斥關係。差別在責任範圍：AI SDK 處理的是模型呼叫與串流到前端的這一段，它不提供圖狀 workflow 引擎，也不內建以 storage 為基礎的暫停續跑。你要多步驟流程，得自己用程式碼或狀態機組出來。

Mastra 則是把 workflow、agent 迴圈、記憶、evals、observability 一起放進來。這個差別在專案早期是負擔，在專案長大後是省下的工。判斷標準很具體：你的流程需不需要 .branch() 這種寫在程式碼裡的分支，需不需要暫停等人工核准，需不需要把 agent 以 MCP 對外。三個都是「不需要」，選 AI SDK 這類較薄的層會更輕鬆。

另一條路是自建。用 provider SDK 加上自己的工具呼叫迴圈、自己的狀態儲存，前期確實自由，但你會逐步重造 evals、observability 與暫停機制，而且這些程式碼的維護責任完全落在你身上。Mastra 的價值就在這裡：它把這些重複出現的部分先做成了有文件、有 release 節奏的套件。代價是你接受它的抽象邊界，以及前面提到的授權分界。

升級節奏與維護成本要看套件層級

從 release 紀錄看，@mastra/core 在 2026 年 9 月 9 日發布 1.65.0，前一版 1.64.0 是 9 月 3 日，再前一版 1.63.0 是 8 月 26 日。大約每週一版的節奏，而且版號已經在 1.x，代表 API 仍在演進而非凍結。對照 repo 首頁的 npm 徽章指向 @mastra/core，可以看出框架是以套件為單位發布，而不是整包 monorepo 一起跳版。

這件事對維護成本有兩個實際影響。第一，你依賴的是特定套件版本，升級時要讀的是該套件的 changelog，而不是 repo 的整體動態。第二，週更的節奏意味著如果你打算鎖定版本、半年升一次，中間累積的變更會相當可觀，升級前最好先確認 agent 與 workflow 這兩個核心介面在該區間內有沒有破壞性變更。

授權層面的維護成本則是另一回事：ee/ 目錄下的程式碼可以自由用於開發與測試，正式環境需要 enterprise license。這代表你的 CI 可以照跑，但上線前的授權檢核要變成流程的一部分，而不是一次性動作。當你升級 @mastra/core 時，ee/ 目錄的內容也可能變動，原本落在 Apache-2.0 的功能不保證永遠留在同一側。把「升級時重新核對路徑與授權對應表」寫進你的升級清單，比事後補救便宜得多。

編輯結論

如果你已經在用 TypeScript 寫後端或 Next.js，而且需要 workflow 的明確分支、暫停等待人工核准、再把 agent 掛上 MCP 對外，Mastra 值得進一次 spike：跑 npm create mastra@latest，把一個真實的多步驟流程改寫成 .then()/.branch()/.parallel()，並刻意觸發一次 suspend 與 resume。如果你的團隊以 Python 為主、或只需要單次 LLM 呼叫，導入它只會多一層抽象。動手之前先確認兩件事：把 packages/core/src/auth/ee/ 這類路徑與你打算上線的功能對照，確認是否落在 Mastra Enterprise License 範圍；以及你選定的 storage 後端在正式環境的持久性與還原行為。這兩點沒查清楚，後面的架構決策都會建立在錯誤前提上。

官方來源

1. Issues
2. mastra-ai/mastra on GitHub
3. Project website
4. README
5. Releases