config.ts

Agent 的 config.ts 會設定模型與執行階段選項。請用它設定屬於 Agent 本身的選項，而 instructions、Tool、Skill 等則由同層檔案提供。

config.ts 應包含的內容

config.ts 是檔案式 Agent 模型與執行階段選項所需的進入點。若 Agent 層級設定不需要專屬檔案，請放在這裡，例如模型、description、預設執行選項、重試行為、scorer 與顯示身分。

如果你希望檔案式路由將相鄰的關注事項合併至 Agent，請將它們放在同層檔案中。例如，持續生效的 prompt 使用 instructions.md，模型可呼叫的動作使用 tools/。

快速開始

以下 config.ts 搭配 instructions.md 檔案，即可建立可運作的檔案式 Agent：

src/mastra/agents/weather/config.ts

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

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/weather/instructions.md

You are a helpful weather assistant. Answer questions about current conditions and forecasts.

Mastra 使用 weather 目錄名稱作為預設 Agent id 與 name。同層的 instructions.md 會提供必要的 instructions。

設定模型

model 欄位是 agentConfig() 唯一的必填欄位。Agent 目錄未提供模型時，建置會失敗。其他能力可來自同層檔案，或使用預設值。

src/mastra/agents/weather/config.ts

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

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

從目錄取得身分

檔案式 Agent 的 id 與 name 預設為目錄名稱。對於 src/mastra/agents/weather/，除非覆寫這些欄位，否則 Mastra 會將 Agent 註冊為 weather。

當穩定的路由 key 與顯示名稱應有所不同時，請覆寫 id 或 name。

src/mastra/agents/weather/config.ts

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

export default agentConfig({
  id: 'weather-assistant',
  name: 'Weather Assistant',
  model: 'openai/gpt-5.6-sol',
})

設定執行階段選項

agentConfig() 接受 Agent constructor 選項，但 id、name 與同層檔案的欄位可由檔案式慣例提供。完整選項清單請參閱 Agent 參考文件。

請注意：

• 檔案式 subagent 必須具有非空白的 description，因為父模型會使用它進行委派路由。
• 如果 defaultOptions、maxRetries、scorers 與其他 Agent 選項不需要專屬檔案，可放在 config.ts 中。

相鄰設定的所在位置

讓 config.ts 專注於執行階段選項。對於適合使用專屬位置的關注事項，請使用同層檔案。

設定	檔案或資料夾	放在該處的原因
Instructions	instructions.md 或 instructions.ts	讓持續生效的 prompt 可用 markdown 閱讀，或在 TypeScript 中計算
Tool	tools/	讓每個可呼叫動作都有自己的型別化模組
Skill	skills/	將按需載入的處理程序與持續生效的 instructions 分開
Memory	memory.ts	設定持久化 Memory，避免執行階段選項過於擁擠
Workspace	workspace.ts	將檔案與 Sandbox 行為同模型設定分開
Processor	processors/	分隔輸入與輸出處理 pipeline
Subagent	subagents/	讓每個專門子 Agent 都有自己的目錄

優先順序

config.ts 會依照以下規則，與 Agent 的其他檔案合併：

Domain	來源 A	來源 B	優先採用
Instructions	動態 config.instructions	instructions.ts 或 instructions.md	動態 config.instructions
Instructions	靜態 config.instructions	instructions.ts 或 instructions.md	instructions 檔案
Instructions	instructions.ts	instructions.md	instructions.ts
Tool	config.tools	tools/	兩者合併；key 衝突時以 config.tools 為準
Tool	函式 config.tools	tools/	函式 config.tools；忽略探索到的 Tool
Skill	config.skills	skills/	兩者合併；名稱衝突時以 config.skills 為準
Skill	函式 config.skills	skills/	函式 config.skills；忽略探索到的 Skill
Memory	config.memory	memory.ts	config.memory
Workspace	config.workspace	workspace.ts	config.workspace

缺少 instructions.md、instructions.ts 與 config.instructions 時，建置會失敗。同時缺少 config.memory 與 memory.ts 時，Agent 將不具備 Memory。

探索生命週期

Mastra bundler 會在 mastra dev 與 mastra build 下探索檔案式 primitive。探索期間，Mastra 會讀取 src/mastra/ 下支援的檔案、匯入 TypeScript 與 JavaScript 模組、讀取 markdown instructions 和 Skill、複製 Workspace 種子檔案，並向 Mastra 應用程式註冊組合完成的 primitive。

探索完成後，檔案式 Agent 會像一般 Agent 一樣執行。從 Agent API、Studio、Workflow 或應用程式的程式碼呼叫它，使用的執行階段與以程式碼定義的 Agent 相同。

探索以來源為基礎，且採保守原則。

它會略過 symlink、測試檔案，以及不是 Agent 目錄的目錄。Workflow 與專案單例檔案只有在具有 default export 時，才會依檔案路由。

透過 Mastra CLI 啟動應用程式，以便執行探索：

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

如果你直接匯入 mastra instance，系統不會探索 agents/<name>/ 目錄與其他慣例。以 library 形式使用 Mastra 時，請改為在程式碼中註冊這些 primitive。