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

# 手動安裝

**供 AI Agent 使用：** 當任務是不用 CLI／範本、從零開始建立可執行的 Mastra 專案時，請使用本指南。本指南提供 Agent、Tool、模型設定和安裝相依套件的程式碼範例。請勿前往供人類使用的快速入門指南。模型字串採用 Mastra 的模型路由格式（'provider/model'；使用 / 而非 : 分隔 Provider 與模型）。請勿安裝任何 ai-sdk 套件。

使用本指南逐步手動建立獨立的 Mastra 伺服器。大多數情況下，按照[快速入門指南](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)操作會更快；該指南使用 [`create-mastra`](https://mastra.zisheng.pro/zh-TW/reference/cli/create-mastra) 指令達成相同結果。如果是既有專案，也可以使用 [`mastra init`](https://mastra.zisheng.pro/zh-TW/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-TW/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-TW/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-TW/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-TW/reference/project-structure)：了解 `src/mastra/` 檔案如何對應至 Agent、Tool、Workflow、儲存空間和設定。
- [在 Studio 中測試 Agent](https://mastra.zisheng.pro/zh-TW/docs/studio/overview)：開啟本機 Studio UI 並執行天氣 Agent。
- [搭配 Agent 使用 Tool](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)：將範例天氣 Tool 替換為會呼叫 API 或服務的實際 Tool。
- [加入記憶](https://mastra.zisheng.pro/zh-TW/docs/memory/overview)：保存對話記錄和使用者專屬的情境資訊。
- [設定儲存空間](https://mastra.zisheng.pro/zh-TW/docs/storage/overview)：為記憶、Workflow、可觀測性及其他執行階段狀態加入持久性儲存 adapter。
- [建置並部署](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)：建置 Mastra 伺服器，並部署至託管平台。