跳至主要內容

手動安裝

使用本指南逐步手動建立獨立的 Mastra 伺服器。大多數情況下，按照快速入門指南操作會更快；該指南使用 create-mastra 指令達成相同結果。如果是既有專案，也可以使用 mastra init。

操作說明
「操作說明」的直接連結

如果你不想使用自動化 CLI Tool，可以依照下列指南自行設定專案。

  1. 建立新專案並切換目錄：

    mkdir my-first-agent && cd my-first-agent

    產生新的 package.json 檔案：

    npm init

    安裝下列相依套件：

    npm install -D typescript @types/node mastra@latest
    npm install @mastra/core@latest zod@^4

    在 package.json 檔案中加入 dev 和 build 指令碼：

    package.json
    {
      "scripts": {
        "dev": "mastra dev",
        "build": "mastra build"
      }
    }

  2. 建立 tsconfig.json 檔案：

    touch tsconfig.json

    加入下列設定：

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

    Mastra 需要使用現代化的 module 和 moduleResolution 設定。使用 CommonJS 或 node 會導致解析錯誤。

  3. 建立 .env 檔案：

    touch .env

    加入 API 金鑰：

    .env
    GOOGLE_API_KEY=<your-api-key>
    備註

    本指南使用 Google Gemini，但你可以使用任何受支援的模型 Provider，包括 OpenAI、Anthropic 等。

  4. 建立 weather-tool.ts 檔案：

    mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts

    加入下列程式碼：

    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({
        output: z.string(),
      }),
      execute: async ({ location }) => {
        return {
          output: `The weather in ${location} is sunny`,
        }
      },
    })
    資訊

    此處已縮短並簡化 weatherTool 範例。你可以在為 Agent 提供 Tool 中查看完整的天氣 Tool。

  5. 建立 weather-agent.ts 檔案：

    mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts

    加入下列程式碼：

    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:
          - Always ask for a location if none is provided
          - If the location name isn't in English, please translate it
          - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
          - Include relevant details like humidity, wind conditions, and precipitation
          - Keep responses concise but informative

          Use the weatherTool to fetch current weather data.
    `,
      model: 'google/gemini-2.5-pro',
      tools: { weatherTool },
    })

  6. 建立 Mastra 入口點並註冊 Agent：

    touch src/mastra/index.ts

    加入下列程式碼：

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

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

  7. 現在可以啟動 Studio 並測試 Agent。

    npm run dev

後續步驟
「後續步驟」的直接連結

On this page