Skip to main content

手动安装

🌐 Manual Install

info

使用本指南逐步手动构建独立的 Mastra 服务器。在大多数情况下，按照入门指南会更快，该指南使用mastra create命令实现相同的结果。对于现有项目，也可以使用mastra init。

如果你不想使用我们的自动 CLI 工具，你可以按照下面的指南自行设置你的项目。

🌐 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.

  1. 创建一个新项目并切换目录：

    🌐 Create a new project and change directory:

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

    生成一个新的 package.json 文件：

    🌐 Generate a new package.json file:

    npm init

    安装以下依赖：

    🌐 Install the following dependencies:

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

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

    🌐 Add dev and build scripts to your package.json file:

    package.json
    {
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "mastra dev",
        "build": "mastra build"
      }
    }

  2. 创建一个 tsconfig.json 文件：

    🌐 Create a tsconfig.json file:

    touch tsconfig.json

    添加以下配置：

    🌐 Add the following configuration:

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

    Mastra 需要现代的 module 和 moduleResolution 设置。使用 CommonJS 或 node 会导致分辨率错误。

    🌐 Mastra requires modern module and moduleResolution settings. Using CommonJS or node will cause resolution errors.

  3. 创建一个 .env 文件：

    🌐 Create an .env file:

    touch .env

    添加你的 API 密钥：

    🌐 Add your API key:

    .env
    GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
    note

    本指南使用 Google Gemini，但你可以使用任何支持的 模型提供商，包括 OpenAI、Anthropic 等。

    🌐 This guide uses Google Gemini, but you can use any supported model provider, including OpenAI, Anthropic, and more.

  4. 创建一个 weather-tool.ts 文件：

    🌐 Create a weather-tool.ts file:

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

    添加以下代码：

    🌐 Add the following code:

    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 () => {
        return {
          output: "The weather is sunny",
        };
      },
    });
    info

    我们在这里简化并缩短了 weatherTool 示例。你可以在 给代理提供工具 中查看完整的天气工具。

    🌐 We've shortened and simplified the weatherTool example here. You can see the complete weather tool under Giving an Agent a Tool.

  5. 创建一个 weather-agent.ts 文件：

    🌐 Create a weather-agent.ts file:

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

    添加以下代码：

    🌐 Add the following code:

    src/mastra/agents/weather-agent.ts
    import { Agent } from "@mastra/core/agent";
    import { weatherTool } from "../tools/weather-tool";

    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 入口并注册你的代理：

    🌐 Create the Mastra entry point and register your agent:

    touch src/mastra/index.ts

    添加以下代码：

    🌐 Add the following code:

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

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

  7. 你现在可以启动 Studio 并测试你的代理。

    🌐 You can now launch Studio and test your agent.

    npm run dev