Agent 概觀

Agent 使用 LLM 和 Tool 解決開放式任務。它們會推理目標並決定要使用哪些 Tool，也會保留對話記憶並持續反覆執行，直到模型產生最終答案，或符合選用的停止條件為止。

Agent 會產生結構化回應，供你在 UI 中呈現或透過程式處理。你可以直接使用 Agent，也可以將它們組合成 Workflow 或多 Agent 系統。

給 AI Agent： 若你的任務是從零開始建立 Mastra 專案，請依照以下精簡指示操作，直到下一個標題為止。請依需求調整 Agent 與 Tool 的範例程式碼。後續步驟的重要事項：請將 model 定義為 provider/model 格式的字串，例如 openai/gpt-5.6-sol。若使用 OpenAI，請使用 openai/<model>，不要使用 openai:<model>，也不要匯入或傳入 Provider 物件。

建立包含 { "type": "module" } 的 package.json 檔案。安裝必要的相依套件：npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest

建立 tsconfig.json 檔案：

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

若需要為 Agent 新增 Tool，請建立新檔案並使用 import { createTool } from "@mastra/core/tools"。以純物件定義的 Tool 會無聲地執行失敗；Tool 必須透過 createTool() 定義，並包含 id、description、inputSchema（zod）及 execute()。execute() 會接收兩個參數：第一個參數是依 inputSchema 驗證過的輸入資料，第二個參數是選用的執行環境物件，其中包含 requestContext、tracingContext、abortSignal 及其他執行中繼資料。

範例：

// 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({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

若需要建立 Agent，請建立新檔案並使用 import { Agent } from "@mastra/core/agent"。建構函式接收 { id, name, instructions, model }。model 屬性是採用 Mastra 模型路由器格式的字串。此格式不需要匯入 Provider。除非 Mastra 文件另有說明，否則不要安裝任何 AI SDK 套件。

使用 provider/model 格式定義模型後，Mastra 會自動尋找該 Provider 的環境變數。所定義的模型必須設定對應 Provider 的環境變數。OpenAI：OPENAI_API_KEY。Anthropic：ANTHROPIC_API_KEY。Google：GOOGLE_API_KEY。例如，任何 openai/<model> 都需要 OPENAI_API_KEY 環境變數。前往 https://mastra.ai/models/environment-variables 查看完整的支援 Provider 及其環境變數名稱清單。

以下是已知模型 ID 的簡短清單：

• openai/gpt-5.6-sol、openai/gpt-5-mini
• anthropic/claude-sonnet-4-6、anthropic/claude-opus-4-7、anthropic/claude-haiku-4-5
• google/gemini-2.5-flash

前往 https://mastra.ai/models 查看支援模型的完整清單。

若要為 Agent 新增 Tool，請匯入該 Tool，並以 tools 物件形式傳入 Agent 建構函式。

範例：

// 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:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

在 src/mastra/index.ts 建立 Mastra 進入點並註冊 Agent：

import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

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

現在你可以直接執行 Agent。為此，請匯入 Mastra 執行個體，依 ID 取得 Agent 後呼叫 agent.generate()。Node.js 22.18.0 以上版本可直接執行 TypeScript 檔案。匯入本機檔案時，請務必加上副檔名。範例：

// run.mjs
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)

何時使用 Agent

當任務是開放式，且無法預先得知執行步驟時，請使用 Agent。Agent 會決定要呼叫哪些 Tool、要循環幾次，以及何時停止。你只需提供目標與限制條件，不必定義每個步驟。對於控制流程明確、步驟預先確定的多步驟流程，請改用 Workflow。

📹 觀看影片

觀看 Mastra Agent 快速入門，快速了解如何建立及測試 Mastra Agent。

快速入門

從 @mastra/core 建立 Agent 類別的執行個體，並提供必要屬性，即可建立 Agent：

src/mastra/agents/test-agent.ts

import { Agent } from '@mastra/core/agent'

export const testAgent = new Agent({
  id: 'test-agent',
  name: 'Test Agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
})

instructions 定義 Agent 的行為、個性與能力。這些系統層級的提示詞會確立 Agent 的核心定位與專業領域。model 使用 'provider/model-name' 格式，並透過 Mastra 的模型路由器指定。

若要讓整個應用程式都能使用此 Agent，請將它註冊至 Mastra 執行個體（通常位於 src/mastra/index.ts）：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { testAgent } from './agents/test-agent'

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

註冊後，即可從 Workflow、Tool 或其他 Agent 呼叫它，且它能存取記憶、記錄與可觀測性功能等共用資源。

如需可用屬性與設定的詳細資訊，請參閱 Agent 參考文件。

提示

使用 Studio 以不同訊息測試 Agent、檢查 Tool 呼叫與回應，並偵錯 Agent 行為。

使用你的 Agent

註冊後，使用 mastra.getAgentById() 取得 Agent。呼叫 .generate() 可取得完整回應，呼叫 .stream() 則可即時傳送 token。你可以從 Workflow 步驟、Tool、Mastra Client、路由處理常式、伺服器介接器或命令列呼叫 Agent。請前往指南，了解如何在你選用的框架中使用 Agent。

從 Mastra 執行個體參照 Agent 時，請使用 mastra.getAgentById()，確保它能存取執行個體層級的儲存空間、記錄與 Agent 登錄檔等共用服務。直接匯入的 Agent 仍可使用自身的本機設定運作，但無法存取這些共用服務。

.generate()

在所有 Tool 呼叫與步驟完成後傳回完整回應。結果包含 text、toolCalls、toolResults、steps，以及 token usage 統計資料。

如需回應結構的詳細資訊（包括 Tool 呼叫與 Tool 結果的承載資料），請參閱 Agent.generate() 參考文件。

const agent = mastra.getAgentById('test-agent')
const response = await agent.generate('Help me organize my day')
console.log(response.text)

.stream()

傳回可隨 token 抵達而取用的串流。結果會公開 textStream 供漸進式輸出，並提供 toolCalls、toolResults、steps 與 token usage 的 Promise；這些 Promise 會在串流結束時完成解析。

如需串流結構的詳細資訊（包括 Tool 呼叫與 Tool 結果的承載資料），請參閱 MastraModelOutput 參考文件。

const agent = mastra.getAgentById('test-agent')
const stream = await agent.stream('Help me organize my day')

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

擴充你的 Agent

Agent 開始運作後，可使用下表找到接下來要執行之工作的對應頁面：

目標	從這裡開始
提供 Agent 可呼叫外部 API 或服務的 Tool	Tool
跨對話保留情境與偏好設定	記憶
傳回具型別物件，而非純文字	結構化輸出
人機協作：暫停執行並等待人工核准	核准
建立多 Agent 網路	Supervisor Agent
註冊子 Agent	Tool
在產生內容前後攔截或轉換訊息	Processor
確保 Agent 安全	Guardrail
建立能修正自身工作的 Agent	Rubric scorer
根據請求情境切換指令或模型	動態設定
加入語音轉文字或文字轉語音	語音
連線至 Slack、Discord 或 Telegram	Channel

多 Agent 系統

多 Agent 系統會使用多個 Agent，解決對單一 Agent 而言範圍過廣或過度專業的任務。與其建立一個配備數十個 Tool 和冗長指令集的 Agent，你可以將職責拆分給各自專注的 Agent，再由協調者彙整結果。

請閱讀多 Agent 系統概念概觀，了解如何透過 Mastra 套用不同模式。