跳到主要内容

手动安装

使用本指南逐步手动构建独立的 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

    将 dev 和 build 脚本添加到 package.json 文件：

    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 示例。完整天气 Tool 请参阅为 Agent 提供 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