開始使用

Mastra 是用來建置 AI Agent 與應用程式的 TypeScript 框架。只需一個指令即可建立第一個 Agent 並開始開發。

給 AI Agent： 若你的任務是從零開始建立 Mastra 專案，請依照以下精簡指示操作，直到下一個標題為止。請依需求調整 Agent 與 Tool 的範例程式碼。後續步驟的重要事項：請將 model 定義為 provider/model 格式的字串，例如 openai/gpt-5.6-sol。若使用 OpenAI，請使用 openai/<model>，不要使用 openai:<model>，也不要匯入或傳入 Provider 物件。

建立包含 { "type": "module" } 的 package.json 檔案。安裝必要的相依套件：npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest

建立 tsconfig.json 檔案：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

若需要為 Agent 新增 Tool，請建立新檔案並使用 import { createTool } from "@mastra/core/tools"。以純物件定義的 Tool 會無聲地執行失敗；Tool 必須透過 createTool() 定義，並包含 id、description、inputSchema（zod）及 execute()。execute() 會接收兩個參數：第一個參數是依 inputSchema 驗證過的輸入資料，第二個參數是選用的執行環境物件，其中包含 requestContext、tracingContext、abortSignal 及其他執行中繼資料。

範例：

// src/mastra/tools/weather-tool.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

若需要建立 Agent，請建立新檔案並使用 import { Agent } from "@mastra/core/agent"。建構函式接收 { id, name, instructions, model }。model 屬性是採用 Mastra 模型路由器格式的字串。此格式不需要匯入 Provider。除非 Mastra 文件另有說明，否則不要安裝任何 AI SDK 套件。

使用 provider/model 格式定義模型後，Mastra 會自動尋找該 Provider 的環境變數。所定義的模型必須設定對應 Provider 的環境變數。OpenAI：OPENAI_API_KEY。Anthropic：ANTHROPIC_API_KEY。Google：GOOGLE_API_KEY。例如，任何 openai/<model> 都需要 OPENAI_API_KEY 環境變數。前往 https://mastra.ai/models/environment-variables 查看完整的支援 Provider 及其環境變數名稱清單。

以下是已知模型 ID 的簡短清單：

openai/gpt-5.6-sol、openai/gpt-5-mini
anthropic/claude-sonnet-4-6、anthropic/claude-opus-4-7、anthropic/claude-haiku-4-5
google/gemini-2.5-flash

前往 https://mastra.ai/models 查看支援模型的完整清單。

若要為 Agent 新增 Tool，請匯入該 Tool，並以 tools 物件形式傳入 Agent 建構函式。

範例：

// src/mastra/agents/weather-agent.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: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

在 src/mastra/index.ts 建立 Mastra 進入點並註冊 Agent：

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

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

現在你可以直接執行 Agent。為此，請匯入 Mastra 執行個體，依 ID 取得 Agent 後呼叫 agent.generate()。Node.js 22.18.0 以上版本可直接執行 TypeScript 檔案。匯入本機檔案時，請務必加上副檔名。範例：

// 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)