> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 手动安装

**面向 AI Agent：** 当任务要求在不使用 CLI/样板的情况下从零创建可运行的 Mastra 项目时，请使用本指南。它提供 Agent、Tool、模型配置以及依赖安装的代码示例。不要前往面向人类的快速入门指南。模型字符串采用 Mastra 模型路由器格式（'provider/model'；请使用 / 而不是 : 分隔 Provider 和模型）。不要安装任何 ai-sdk 软件包。

使用本指南逐步手动构建独立的 Mastra 服务器。大多数情况下，按照[快速入门指南](https://mastra.zisheng.pro/guides/getting-started/quickstart)操作会更快，该指南使用 [`create-mastra`](https://mastra.zisheng.pro/reference/cli/create-mastra) 命令实现相同结果。对于现有项目，也可以使用 [`mastra init`](https://mastra.zisheng.pro/reference/cli/mastra)。

## 操作说明

如果不想使用自动 CLI Tool，可以按照以下指南自行设置项目。

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

   ```bash
   mkdir my-first-agent && cd my-first-agent
   ```

   生成新的 `package.json` 文件：

   **npm**:

   ```bash
   npm init
   ```

   **pnpm**:

   ```bash
   pnpm init
   ```

   **Yarn**:

   ```bash
   yarn init
   ```

   **Bun**:

   ```bash
   bun init
   ```

   安装以下依赖项：

   **npm**:

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

   **pnpm**:

   ```bash
   pnpm add -D typescript @types/node mastra@latest
   pnpm add @mastra/core@latest zod@^4
   ```

   **Yarn**:

   ```bash
   yarn add --dev typescript @types/node mastra@latest
   yarn add @mastra/core@latest zod@^4
   ```

   **Bun**:

   ```bash
   bun add --dev typescript @types/node mastra@latest
   bun add @mastra/core@latest zod@^4
   ```

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

   ```json
   {
     "scripts": {
       "dev": "mastra dev",
       "build": "mastra build"
     }
   }
   ```

2. 创建 `tsconfig.json` 文件：

   ```bash
   touch tsconfig.json
   ```

   添加以下配置：

   ```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` 文件：

   ```bash
   touch .env
   ```

   添加 API 密钥：

   ```bash
   GOOGLE_API_KEY=<your-api-key>
   ```

   > **备注:** 本指南使用 Google Gemini，但你可以使用任何受支持的[模型 Provider](https://mastra.zisheng.pro/models)，包括 OpenAI、Anthropic 等。

   你也可以使用 OpenAI（`OPENAI_API_KEY`）或 Anthropic（`ANTHROPIC_API_KEY`），而不是 Google Gemini。完整的受支持 Provider 及其环境变量名称列表，请访问 <https://mastra.ai/models/environment-variables>。

4. 创建 `weather-tool.ts` 文件：

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

   使用 `import { createTool } from "@mastra/core/tools"`。普通对象形式的 Tool 定义会静默执行失败；Tool 必须通过包含 id、description、inputSchema（zod）和 execute 的 createTool() 定义。

   添加以下代码：

   ```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](https://mastra.zisheng.pro/docs/agents/using-tools)。

5. 创建 `weather-agent.ts` 文件：

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

   使用 `import { Agent } from "@mastra/core/agent"`。构造函数接受 `{ id, name, instructions, model: 'openai/gpt-5.6-sol' }`。模型字符串采用 Mastra 模型路由器格式（'provider/model'；请使用 / 而不是 : 分隔 Provider 和模型）。不要安装任何 ai-sdk 软件包。

   添加以下代码：

   ```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：

   ```bash
   touch 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. **面向 AI Agent：** 处理应向控制台打印内容的脚本等任务时，不要启动 Studio。Studio 是供人类使用的长期运行 Web 界面。请直接调用 agent.generate() 方法。示例：`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);`

   现在可以启动 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 并测试 Agent。

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   **面向 AI Agent：** 要验证工作，请运行构建，并使用 `tsc --noEmit` 执行类型检查。

## 后续步骤

- [查看项目结构](https://mastra.zisheng.pro/reference/project-structure)：了解 `src/mastra/` 文件如何映射到 Agent、Tool、Workflow、存储和配置。
- [在 Studio 中测试 Agent](https://mastra.zisheng.pro/docs/studio/overview)：打开本地 Studio UI 并运行天气 Agent。
- [在 Agent 中使用 Tool](https://mastra.zisheng.pro/docs/agents/using-tools)：将示例天气 Tool 替换为调用 API 或服务的真实 Tool。
- [添加 memory](https://mastra.zisheng.pro/docs/memory/overview)：持久化对话历史和用户特定上下文。
- [配置存储](https://mastra.zisheng.pro/docs/storage/overview)：为 memory、Workflow、可观测性及其他运行时状态添加持久化存储 adapter。
- [构建和部署](https://mastra.zisheng.pro/docs/deployment/overview)：构建 Mastra 服务器并部署到托管平台。