mastra-ai/mastra TypeScript 開源代理框架教學:全端工程師必學的工作流、RAG 與評估工具

由 Gatsby 團隊打造的 TypeScript 開源代理框架 Mastra,整合代理記憶、工作流引擎、RAG 與內建本地開發介面,讓前端與全端工程師直接用 TS 建構 AI 應用。

Share
Mastra官方 GitHub 專案封面圖:Mastra TypeScript 教學
Mastra官方開源專案視覺圖。 圖片來源:官方原文。

過去兩年想開發 AI 代理或檢索增強生成應用,工程師幾乎別無選擇,只能硬著頭皮寫 Python。這讓廣大的 TypeScript 與 Next.js 全端團隊非常痛苦,明明前端介面、資料庫存取與商業邏輯全都是型別安全的 TypeScript,唯獨 AI 層要另外架一套 Python 微服務。

由原 Gatsby 核心團隊打造的開源框架 mastra-ai/mastra,正是為了解決這個技術棧斷層而生。它把模型路由、代理記憶、圖形化工作流、RAG 檢索以及評估追蹤,全部用現代 TypeScript 原生重構。

從工程實務角度來看,Mastra 最大的突破不只是「換個語言重寫」,而是把網站開發者最熟悉的開發體驗帶進了 AI 工程。只要一行指令就能啟動本地視覺化工作台 Mastra Studio,即時測試代理思考路徑與工具呼叫。

這篇 Mastra TypeScript 教學會帶你一次掌握它的核心架構、五分鐘快速安裝指令、三大主力功能解析,以及與 Next.js 整合時必須注意的授權與安全邊界。

為什麼全端工程師都在看 Mastra:架構與設計哲學

在 AI 代理框架百花齊放的時代,Python 生態雖然資源豐富,但將 Python 原型放進以 Node.js 或邊緣運算為主的現代網頁架構時,往往會多出一層跨語言序列化的維護成本。Mastra 的設計哲學非常明確,就是讓 TypeScript 團隊能用同一套語言、同一套型別檢查與同一份套件管理檔,完成從模型呼叫到前端介面的所有開發工作。

根據官方文件,Mastra 並不是一個封閉的黑盒子,而是一套模組化的全端 AI 基礎設施,核心圍繞以下幾個關鍵能力展開:

  • 統一模型路由:透過單一標準介面即可對接超過 40 家模型供應商,支援 OpenAI、Anthropic、Gemini 與 xAI 等主流模型,不必為不同廠商重寫呼叫邏輯。
  • 自主代理系統:支援具備工具呼叫能力的 AI 代理,讓模型根據目標自主決定何時呼叫外部函式、何時迭代推論,直到產生最終答案或觸發停止條件。
  • 圖形化工作流引擎:當任務步驟需要嚴格控制順序與分支時,不必把所有邏輯塞進系統提示詞,而是用 .then()、.branch() 與 .parallel() 等明確語法編排多步驟流程。
  • 狀態保存與人類介入:內建儲存層支援將執行到一半的代理或工作流暫停,等待人類使用者確認或補充輸入後,再從中斷點無縫恢復執行。
  • 上下文與記憶管理:整合對話歷史紀錄、外部資料檢索 RAG,以及獨特的觀察式記憶機制,確保代理在長對話中依然維持一致的判斷力。

更貼近實務的是,Mastra 團隊非常清楚「上線後的除錯」才是開發者最頭痛的環節。因此框架直接內建了評估工具與可觀測性追蹤,並且原生支援將代理或工具發布成標準的 MCP 伺服器,讓其他支援該協定的系統也能直接呼叫你開發的功能。

Mastra官方 GitHub 專案封面圖:Mastra TypeScript 教學
Mastra官方開源專案視覺圖。 圖片來源:官方原文。

五分鐘快速上手:安裝指令與 Mastra Studio 本地介面

要開始使用 Mastra,不需要手動設定繁瑣的設定檔。官方最推薦的起步方式是透過 npm create 指令建立專案範本,系統會自動產生標準的目錄結構、設定好 TypeScript 環境,並偵測你本機的開發輔助工具自動安裝對應技能設定。

# 使用官方推薦指令建立全新 Mastra 專案
npm create mastra@latest

如果你想跳過互動式問答,直接指定專案名稱與預設的大型語言模型供應商,也可以在指令後方帶入參數。目前範本初始化支援的模型供應商包含 openai、anthropic、google 與 xai。

# 直接指定專案名稱與模型供應商進行初始化
npm create mastra@latest my-mastra-app -- --llm openai

專案建立完成並填妥環境變數中的 API 金鑰後,進入專案目錄並啟動本地開發伺服器,就能開啟 Mastra 最具代表性的視覺化工作台 Mastra Studio。

cd my-mastra-app
npm run dev

啟動成功後,打開瀏覽器前往 http://localhost:4111,你就會看到完整的本機開發儀表板。在這個介面裡,工程師可以直接測試不同系統提示詞的差異、單步檢視工作流每個節點的輸入與輸出 JSON 資料,甚至直接模擬工具呼叫失敗的情境,大幅縮短反覆修改程式與重啟伺服器的時間。

核心功能實戰解析:工作流編排、上下文記憶與 MCP 整合

很多團隊在導入 AI 代理時,最常犯的錯誤是「什麼都想交給單一自主代理去猜」。實務上,企業流程往往既有需要彈性判斷的環節,也有絕對不能出錯的固定步驟。Mastra 把這兩種需求拆得很乾淨,這也是它比純對話式框架更容易維護的原因。

用圖形工作流取代脆弱的長提示詞

當你的系統需要先驗證訂單格式、平行查詢兩套資料庫、再根據金額大小決定要走自動核准還是人工審核時,把這些規則寫進自然語言提示詞幾乎注定會出錯。Mastra 的工作流引擎讓開發者用鏈式呼叫語法把確定性邏輯鎖死:

  • 使用 .then() 串接有嚴格先後順序的處理步驟,確保前一步的輸出型別完全符合下一步的輸入要求。
  • 使用 .parallel() 同時派發多個互不依賴的任務,例如同時對文件做摘要與擷取關鍵實體,縮短整體回應延遲。
  • 使用 .branch() 根據條件分流,只有特定情境才觸發昂貴的推理模型,其餘情況直接走輕量級規則或快速模型。

這種「外層用 TypeScript 程式碼控制流程、內層特定節點才交給模型推理」的混合設計,兼顧了軟體工程的可預測性與 AI 的語意理解彈性。

結合 RAG 與觀察式記憶管理上下文

大型語言模型一旦超過上下文視窗限制,或是塞入過多無關的歷史訊息,回答準確度就會急劇下降。Mastra 在上下文管理上提供三層防護:基本的對話歷史管理、從 API 與檔案庫即時撈取資料的 RAG 管線,以及協助整理長期背景資訊的觀察式記憶。

搭配人類介入暫停機制與持久化儲存層,系統可以在等待主管核准的數小時甚至數天內,把整個執行狀態完整凍結在資料庫裡,不會因為伺服器重啟或無伺服器函式逾時而遺失上下文。

無縫整合 Next.js 前端與發布 MCP 伺服器

對於已經在使用 React 或 Next.js 的團隊來說,Mastra 並不會強迫你搬家。你可以把寫好的代理與工作流直接打包進既有的 Next.js 或 Node.js 專案中當作後端 API 路由,也能與 Vercel AI SDK UI 或 CopilotKit 等前端互動套件搭配,快速做出支援串流文字與動態元件渲染的對話介面。

此外,如果你寫好了一組非常好用的內部資料庫查詢代理,Mastra 支援直接將這些代理與工具封裝成符合 Model Context Protocol 規範的 MCP 伺服器。這麼一來,團隊成員就能直接在支援 MCP 的編輯器或桌面端助手中呼叫這些工具,不需要再為不同平台重複開發外掛。

延伸閱讀:LangChain 完成 3 億美元 C 輪融資!CapitalG 領投、估值衝上 30 億美元,企業級 AI 代理基礎設施拼什麼?

雙重授權機制與選型比較:免費開源與企業版的界線

導入任何標榜開源的框架前,法務與架構師一定要先看清楚授權條款。Mastra 採用的是「核心開源加上企業擴充雙授權」模式,這在現代開源基礎設施中相當常見,但沒看清楚很容易在日後踩到商業合規問題。

根據 Mastra 官方倉庫的授權說明,框架絕大多數的核心程式碼與主要功能都採用對商業極為友善的 Apache License 2.0 授權,團隊可以自由修改、整合並部署到商業產品中。然而,只要是位於 ee/ 目錄底下的程式碼,例如進階的企業級身份驗證模組 packages/core/src/auth/ee/,則屬於原始碼可見但受 Mastra Enterprise License 規範的企業功能。這些功能在開發與測試階段可以免費試用,但若要部署到正式生產環境,就必須取得有效的企業授權。

為了幫你快速判斷團隊是否該選擇 Mastra,以下整理它與傳統 Python 代理框架的實務比較。

比較項目 Mastra 傳統 Python 代理框架
主要開發語言 原生 TypeScript,型別系統貫穿前後端 Python 為主,跨前端需透過 API 轉接
適合的團隊背景 React、Next.js、Node.js 全端工程團隊 資料科學、機器學習或純後端 Python 團隊
本地視覺化除錯 內建 Mastra Studio,4111 埠即開即用 多數需額外註冊雲端追蹤平台或自行架設
流程控制彈性 支援自主代理與 .then() 明確圖形工作流 早期偏重對話迴圈,近期才逐步強化圖形編排
授權模式注意事項 核心採 Apache-2.0,ee/ 目錄需企業授權 視個別框架而定,部分平台服務採雲端收費

如果你們公司的技術核心本來就是 TypeScript,選擇 Mastra 能省下維護雙語言架構與重複定義資料型別的大量人力。相反地,如果團隊高度依賴 PyTorch、Hugging Face 本機推論或複雜的科學計算函式庫,留在 Python 生態系依然是更務實的選擇。

延伸閱讀:Kindo 募資 3,000 萬美元打造企業 AI 代理控制中心:從權限管控到 Deep Hat 降本策略全解析

實戰導入的資安與維運提醒

即使 Mastra 提供了極佳的開發體驗,把代理接上真實系統時仍有四個關鍵邊界必須守住。

首先,在呼叫外部模型路由時,務必確保超過 40 家供應商的 API 金鑰只存在於伺服器端環境變數中,絕不可透過前端打包腳本外洩至瀏覽器。對 Next.js 開發者來說,所有模型呼叫與工具執行都應該封裝在伺服器動作或 API 路由裡,絕對不能在帶有 "use client" 標記的用戶端元件中直接初始化模型用戶端。

其次,針對可暫停並等待人類審核的工作流,要對恢復執行的輸入資料做嚴格的結構驗證,避免惡意使用者在核准階段注入異常參數。實務上建議搭配 Zod 等 TypeScript 型別驗證工具,在工作流每個節點的入口與出口檢查資料格式,一旦模型回傳不符合預期的欄位,就能在程式碼層級直接攔截並觸發重試機制,而不是讓錯誤資料一路流進資料庫。

第三,在整合 RAG 檢索管線與觀察式記憶時,一定要把「權限過濾」做在檢索階段之前。許多團隊把所有部門的文件都塞進同一個向量資料庫,卻忘了在查詢時帶入使用者的存取權限標籤,結果客服機器人不小心把內部薪資或未公開的合約片段撈出來給一般客戶看,這種權限外洩風險絕對不能只靠提示詞去約束。

最後,若打算在生產環境啟用模型評估與可觀測性追蹤,記得針對個人隱私資料與敏感商業內容設定遮罩規則,避免測試紀錄意外變成資料外洩破口。同時建議為每一個自主代理設定明確的步數與預算上限,防止模型在呼叫外部工具失敗時陷入無窮重試迴圈,造成雲端帳單暴增或資料庫遭到大量異常請求灌爆。

TypeScript 全端常見踩坑速查表

為了讓團隊在從原型邁向正式環境的過程中少走彎路,這裡整理出導入 Mastra 時最常見的四種工程問題與對應解法。

  • 開發環境正常但部署無伺服器環境逾時:因為雲端無伺服器函式通常有十秒到六十秒的執行時間限制,遇到需要等待外部 API 或人類審核的長流程時,務必啟用工作流持久化儲存與暫停恢復機制,不要讓單一 HTTP 請求一直卡在線上等待模型思考。
  • 跨模型切換後工具呼叫格式錯亂:雖然統一模型路由支援超過 40 家供應商,但不同模型對複雜巢狀 JSON 參數的遵循程度仍有落差。切換底層模型前,務必利用內建的評估工具跑過一次核心測試集,確認工具呼叫成功率沒有下降。
  • 把工作流所有邏輯都塞進單一代理:當業務規則其實是固定順序時,硬要代理自己判斷下一步只會增加延遲與出錯率。正確做法是拆成細粒度的 .then() 節點,只在真正需要語意推理的節點才呼叫語言模型。
  • 誤將企業版目錄程式碼打包進免費商業專案:團隊成員在引入認證或進階管理模組時,建議在持續整合檢查中加入路徑掃描規則,避免不小心引用 ee/ 目錄底下的原始碼而引發授權合規爭議。

常見問題

不會寫 Python,只會 TypeScript 可以用 Mastra 嗎?

完全可以。Mastra 就是專為 TypeScript 開發者設計的框架,從模型路由、工具定義、RAG 檢索到圖形工作流編排全部使用 TypeScript 撰寫,非常適合熟悉 React、Next.js 或 Node.js 的工程師直接上手。

Mastra Studio 要額外付費或連線到雲端嗎?

不需要。Mastra Studio 是框架內建的本機開發介面,執行 npm run dev 後就會在電腦的 4111 埠啟動,方便你在本機安全地測試代理、檢視工作流狀態與除錯,不用把開發過程中的測試資料傳上第三方雲端平台。

Mastra 可以免費部署在商業產品中嗎?

可以,但要避開企業專屬目錄。Mastra 的核心框架與多數功能採用 Apache-2.0 開源授權,可以免費用於商業用途;唯有原始碼中標註在 ee/ 目錄下的進階企業功能,在正式生產環境使用時才需要購買企業授權。

已經有 Next.js 專案了,還需要把 Mastra 架成獨立伺服器嗎?

不一定需要。Mastra 支援兩種部署型態,你可以把它當作獨立的後端服務運行,也可以直接把代理與工作流整合進既有的 Next.js 或 Node.js 專案中,搭配 Vercel AI SDK UI 等工具在同一個專案內完成前後端整合。

結語

Mastra 的出現,正式宣告 TypeScript 全端工程師不再只是 AI 應用的「介面包裝工」,而是能用自己最熟悉的工具鏈,從底層建構具備記憶、工作流與評估機制的完整代理系統。

  • 適合誰:以 TypeScript、Next.js 與 Node.js 為主力的前端與全端團隊、希望在同一個程式碼庫內統一前後端型別與 AI 邏輯的新創公司,以及重視本機視覺化除錯體驗的工程師。
  • 不適合誰:核心業務高度綁定 Python 資料科學套件與本機模型訓練的團隊,或是需要開箱即用企業級權限控制卻沒有預算購買企業授權的專案。
  • 為什麼:因為選擇框架的本質是選擇團隊的長期維護成本,Mastra 讓 Web 團隊免於跨語言撕裂,但前提是你的工作負載本來就屬於應用程式編排而非底層模型研發。

想掌握更多開源 AI 工具的實戰評測、框架對比與上線避坑清單,歡迎立即免費訂閱 AI 郵報,讓最精煉的技術情報每週準時送達你的信箱。

資料來源