config.ts

Agent 的 config.ts 會設定其模型及執行階段選項。屬於 Agent 本身的選項應放在此檔案，而同層檔案則提供 instructions、tools、skills 等內容。

config.ts 應包含的內容

config.ts 是檔案式 Agent 模型及執行階段選項的必要進入點。當 Agent 層級設定不需要獨立檔案時，應放在這裏，例如模型、描述、預設執行選項、重試行為、scorers 及顯示身分。

如希望檔案式路由把相關設定合併至 Agent，請將這些設定保留在同層檔案。例如，使用 instructions.md 提供始終生效的 prompt，並使用 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。

當穩定的路由鍵與顯示名稱應有所不同時，請覆寫 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 建構函數選項，但 id、name 及同層檔案欄位可由檔案式慣例提供。完整選項清單請參閱 Agent 參考文件。

請注意：

• 檔案式 subagent 必須提供非空白的 description，因為父模型會使用它進行委派路由。
• 當 defaultOptions、maxRetries、scorers 及其他 Agent 選項不需要獨立檔案時，可放在 config.ts 中。

相關設定的存放位置

讓 config.ts 專注於執行階段選項。適合獨立存放的內容應使用同層檔案。

設定	檔案或資料夾	存放於該處的原因
Instructions	instructions.md 或 instructions.ts	以易讀的 markdown 保留始終生效的 prompt，或使用 TypeScript 動態產生內容
Tools	tools/	讓每項可調用操作各自擁有具型別的模組
Skills	skills/	將按需要載入的程序與始終生效的 instructions 分開
Memory	memory.ts	設定持久 memory，避免執行階段選項過於擁擠
Workspace	workspace.ts	將檔案及 Sandbox 行為與模型設定分開設定
Processors	processors/	分隔輸入及輸出處理管線
Subagents	subagents/	讓每個專門的子 Agent 擁有獨立目錄

優先次序

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

範疇	來源 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
Tools	config.tools	tools/	兩者合併；鍵發生衝突時以 config.tools 為準
Tools	函數 config.tools	tools/	函數 config.tools；忽略已探索的 tools
Skills	config.skills	skills/	兩者合併；名稱發生衝突時以 config.skills 為準
Skills	函數 config.skills	skills/	函數 config.skills；忽略已探索的 skills
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 期間探索檔案式 primitives。探索期間，Mastra 會讀取 src/mastra/ 下支援的檔案、匯入 TypeScript 及 JavaScript 模組、讀取 markdown instructions 及 skills、複製 Workspace 種子檔案，並向你的 Mastra 應用程式註冊組合完成的 primitives。

探索完成後，檔案式 Agent 會以一般 Agent 的方式運作。透過 Agent API、Studio、Workflow 或應用程式程式碼調用它時，會使用與程式碼定義 Agent 相同的執行階段。

探索以原始碼為基礎，並採取保守方式。

它會略過符號連結、測試檔案及並非 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>/ 目錄及其他慣例。當你將 Mastra 用作函式庫時，請改為在程式碼中註冊這些 primitives。