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

# 手動安裝

**給 AI Agent：** 當你需要在不使用 CLI／樣板程式碼的情況下，從零開始建立可執行的 Mastra 項目時，請使用本指南。本指南提供 Agent、Tool、模型設定及安裝依賴套件的程式碼範例。請勿前往為人類而設的快速入門指南。模型字串採用 Mastra 的模型路由器格式（'provider/model'；請使用 / 而非 : 分隔 Provider 與模型）。請勿安裝任何 ai-sdk 套件。

使用本指南逐步手動建立獨立的 Mastra 伺服器。大多數情況下，按照[快速入門指南](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)操作會更快捷；該指南使用 [`create-mastra`](https://mastra.zisheng.pro/zh-HK/reference/cli/create-mastra) 命令達到相同效果。對於現有項目，你亦可使用 [`mastra init`](https://mastra.zisheng.pro/zh-HK/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
   ```

   在 `package.json` 文件中加入 `dev` 和 `build` 腳本：

   ```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/zh-HK/models)，包括 OpenAI、Anthropic 等。

   你亦可使用 OpenAI（`OPENAI_API_KEY`）或 Anthropic（`ANTHROPIC_API_KEY`）取代 Google Gemini。前往 <https://mastra.ai/models/environment-variables> 查看受支援 Provider 及其環境變數名稱的完整清單。

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 必須透過 createTool() 定義，並包含 id、description、inputSchema (zod)、execute

   加入以下程式碼：

   ```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](https://mastra.zisheng.pro/zh-HK/docs/agents/using-tools)中查看完整的天氣 Tool。

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 是供人類使用、長時間運行的網頁介面。請改為直接呼叫 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/zh-HK/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/zh-HK/reference/project-structure)：了解 `src/mastra/` 文件如何對應至 Agent、Tool、Workflow、儲存空間及設定。
- [在 Studio 測試 Agent](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)：開啟本機 Studio UI 並執行天氣 Agent。
- [讓 Agent 使用 Tool](https://mastra.zisheng.pro/zh-HK/docs/agents/using-tools)：以會呼叫 API 或服務的真實 Tool 取代範例天氣 Tool。
- [加入記憶體](https://mastra.zisheng.pro/zh-HK/docs/memory/overview)：保存對話記錄和使用者特定的內容脈絡。
- [設定儲存空間](https://mastra.zisheng.pro/zh-HK/docs/storage/overview)：為記憶體、Workflow、可觀測性及其他執行階段狀態加入持久儲存配接器。
- [建置及部署](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)：建置 Mastra 伺服器，並將其部署至託管平台。