Mastra 是什麼、怎麼用：TypeScript 智能體框架的安裝與第一個 Agent

本文根據 Mastra 官方文檔《Installation》整理，資料核對於 2026-10-11。文中代碼取自官方頁面，沒有在本機運行驗證。

適用於誰

• 搜「mastra 是什麼」「mastra 教學」「mastra 框架」「mastra agent」的人；
• 用 TypeScript 寫後端或全棧應用，想在項目裏加智能體的人；
• 用過 Python 的智能體框架，想找一個 TypeScript 生態裏對應的東西的人。

結論先說

1. Mastra 是一個用 TypeScript 構建 AI 智能體和應用的框架。
2. 需要 Node.js 22.18.0 或更高版本。官方選這個版本的原因是它可以直接運行 TypeScript 文件。
3. 最快的起步方式是一條命令：npm create mastra@latest。
4. 模型用 'provider/model' 字符串指定，不需要單獨導入各家的包；API Key 通過環境變量提供。
5. 核心結構很簡單：用 new Agent({...}) 定義智能體，在 new Mastra({ agents: {...} }) 裏註冊，之後用 mastra.getAgentById(...) 取出來調用。

一、準備

• Node.js 22.18.0 或更高。在終端運行 node --version 確認；
• 模型廠商的 API Key。官方舉的例子：OpenAI 用 OPENAI_API_KEY，Anthropic 用 ANTHROPIC_API_KEY，Google 用 GOOGLE_API_KEY。其他廠商對應的環境變量名，官方有一張完整的表。

Key 的獲取見《OpenAI API Key 怎麼獲取》、《Claude API Key》、《Gemini API Key》。

二、快速開始：一條命令

按你用的包管理器選一條：

bash
npm create mastra@latest

bash
pnpm create mastra@latest

bash
yarn create mastra

bash
bunx create-mastra

按提示完成即可。官方文檔對腳手架內容的描述是：一個通用的智能體框架，帶本地工作區、終端工具、記憶、任務跟蹤、聯網訪問和定時任務；同時會為你的編程智能體安裝 Mastra 的 Skills。

文檔還提到 Studio：一個用來和項目交互的介面，項目建好後可以直接打開。啟動方式看腳手架生成的 package.json 裏的腳本和官方文檔。

三、手動安裝：七步

想弄清楚每個文件是幹什麼的，或者要把 Mastra 加進已有項目，按官方的手動步驟來。

第 1 步：創建 package.json，內容裏要有：

json
{ "type": "module" }

第 2 步：安裝依賴

bash
npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest

第 3 步：創建 tsconfig.json。官方給出的關鍵設定：

第 4 步：設定環境變量，例如 OPENAI_API_KEY。

第 5 步：定義智能體，文件放在 src/mastra/agents/weather-agent.ts：

ts
import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool.ts'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `...`, // full instructions on the page
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

• id：之後用它來取這個智能體；
• instructions：系統提示詞，官方示例裏是一段關於如何回答天氣問題的說明，完整內容見官方頁面；
• model：'provider/model' 形式的字符串；
• tools：這個智能體可以用的工具。示例裏的 weatherTool 來自 ../tools/weather-tool.ts，用 @mastra/core/tools 裏的 createTool() 創建，代碼見官方頁面。

第 6 步：註冊，文件是 src/mastra/index.ts：

ts
import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

export const mastra = new Mastra({
  agents: { weatherAgent },
})

第 7 步：從腳本里調用

ts
// run.mjs
import { mastra } from './src/mastra/index.ts'

const agent = mastra.getAgentById('weather-agent')
const response = await agent.generate('Weather in SF')
console.log(response.text)

官方提醒：本地文件的導入要帶上文件擴展名（.ts）。這和 tsconfig.json 裏的 allowImportingTsExtensions 是配套的。

四、目錄結構怎麼理解

按上面的步驟，項目裏和 Mastra 有關的部分是：

src/mastra/
├── index.ts               # 創建 Mastra 實例，註冊智能體
├── agents/
│   └── weather-agent.ts   # 智能體定義
└── tools/
    └── weather-tool.ts    # 工具定義

Mastra 實例是總入口：智能體都註冊在它上面，應用的其他部分通過它來獲取。新增一個智能體就是在 agents/ 下加一個文件，再到 index.ts 裏註冊。

五、寫智能體時的幾點

這些是通用的做法，不限於 Mastra：

• instructions 寫清邊界：它負責什麼、不負責什麼、資訊不足時該問用戶還是該拒絕；
• 工具說明寫給模型看：模型靠工具的名稱和描述決定何時調用；
• 有副作用的工具謹慎提供：能發消息、改數據、執行命令的工具，先想好要不要人工確認；
• 密鑰只放環境變量，不要寫進代碼或提交進倉庫。

系統提示詞的寫法見《系統提示詞怎麼寫》。

六、接下來

官方安裝頁列出的後續方向：

• 模板：官方提供了一批起步模板；
• 接入現有框架：有 Next.js、React + Vite、Astro、Express、SvelteKit、Hono 的集成指南。

框架的其他能力見官方文檔的對應章節。

常見問題

Q：Node 版本低於 22.18 行不行？

官方寫的要求是 22.18.0 或更高。上面的寫法依賴 Node 直接運行 TypeScript 文件，低版本不滿足。

Q：一定要用 OpenAI 的模型嗎？

不是。把 model 換成其他廠商的 'provider/model' 字符串，並設定對應的環境變量。各廠商的變量名見官方的環境變量表。

Q：和 Vercel AI SDK 是什麼關係、怎麼選？

兩者都是 TypeScript 生態的。AI SDK 是偏底層的工具包，見《Vercel AI SDK 是什麼》；Mastra 是在更高一層提供智能體定義、註冊和 Studio 等一整套結構的框架。只需要調模型和流式輸出，用前者就夠；要組織多個智能體和工具，可以看 Mastra。

Q：Python 項目能用嗎？

Mastra 是 TypeScript 框架。Python 的選擇見《Pydantic AI 是什麼》和《OpenAI Agents SDK 教學》。

參考資料

• Installation（Mastra 官方文檔）：https://mastra.ai/docs/getting-started/installation