> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt # config.ts Agent 的 `config.ts` 會設定模型與執行階段選項。請用它設定屬於 [`Agent`](https://mastra.zisheng.pro/zh-TW/reference/agents/agent) 本身的選項，而 instructions、Tool、Skill 等則由同層檔案提供。 ## `config.ts` 應包含的內容 `config.ts` 是檔案式 Agent 模型與執行階段選項所需的進入點。若 Agent 層級設定不需要專屬檔案，請放在這裡，例如模型、description、預設執行選項、重試行為、scorer 與顯示身分。 如果你希望檔案式路由將相鄰的關注事項合併至 Agent，請將它們放在同層檔案中。例如，持續生效的 prompt 使用 `instructions.md`，模型可呼叫的動作使用 `tools/`。 ## 快速開始 以下 `config.ts` 搭配 `instructions.md` 檔案，即可建立可運作的檔案式 Agent： ```typescript import { agentConfig } from '@mastra/core/agent' export default agentConfig({ model: 'openai/gpt-5.6-sol', }) ``` ```markdown You are a helpful weather assistant. Answer questions about current conditions and forecasts. ``` Mastra 使用 `weather` 目錄名稱作為預設 Agent `id` 與 `name`。同層的 `instructions.md` 會提供必要的 instructions。 ## 設定模型 `model` 欄位是 `agentConfig()` 唯一的必填欄位。Agent 目錄未提供模型時，建置會失敗。其他能力可來自同層檔案，或使用預設值。 ```typescript 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`。 ```typescript import { agentConfig } from '@mastra/core/agent' export default agentConfig({ id: 'weather-assistant', name: 'Weather Assistant', model: 'openai/gpt-5.6-sol', }) ``` ## 設定執行階段選項 `agentConfig()` 接受 [`Agent` constructor 選項](https://mastra.zisheng.pro/zh-TW/reference/agents/agent)，但 `id`、`name` 與同層檔案的欄位可由檔案式慣例提供。完整選項清單請參閱 Agent 參考文件。 請注意： - 檔案式 subagent 必須具有非空白的 `description`，因為父模型會使用它進行委派路由。 - 如果 `defaultOptions`、`maxRetries`、`scorers` 與其他 Agent 選項不需要專屬檔案，可放在 `config.ts` 中。 ## 相鄰設定的所在位置 讓 `config.ts` 專注於執行階段選項。對於適合使用專屬位置的關注事項，請使用同層檔案。 | 設定 | 檔案或資料夾 | 放在該處的原因 | | ------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | Instructions | [`instructions.md` 或 `instructions.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/instructions) | 讓持續生效的 prompt 可用 markdown 閱讀，或在 TypeScript 中計算 | | Tool | [`tools/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/tools) | 讓每個可呼叫動作都有自己的型別化模組 | | Skill | [`skills/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/skills) | 將按需載入的處理程序與持續生效的 instructions 分開 | | Memory | [`memory.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/memory) | 設定持久化 Memory，避免執行階段選項過於擁擠 | | Workspace | [`workspace.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/workspace) | 將檔案與 Sandbox 行為同模型設定分開 | | Processor | [`processors/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/processors) | 分隔輸入與輸出處理 pipeline | | Subagent | [`subagents/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/subagents) | 讓每個專門子 Agent 都有自己的目錄 | ## 優先順序 `config.ts` 會依照以下規則，與 Agent 的其他檔案合併： | Domain | 來源 A | 來源 B | 優先採用 | | ------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | Instructions | 動態 `config.instructions` | [`instructions.ts` 或 `instructions.md`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/instructions) | 動態 `config.instructions` | | Instructions | 靜態 `config.instructions` | [`instructions.ts` 或 `instructions.md`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/instructions) | instructions 檔案 | | Instructions | [`instructions.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/instructions) | [`instructions.md`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/instructions) | `instructions.ts` | | Tool | `config.tools` | [`tools/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/tools) | 兩者合併；key 衝突時以 `config.tools` 為準 | | Tool | 函式 `config.tools` | [`tools/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/tools) | 函式 `config.tools`；忽略探索到的 Tool | | Skill | `config.skills` | [`skills/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/skills) | 兩者合併；名稱衝突時以 `config.skills` 為準 | | Skill | 函式 `config.skills` | [`skills/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/skills) | 函式 `config.skills`；忽略探索到的 Skill | | Memory | `config.memory` | [`memory.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/memory) | `config.memory` | | Workspace | `config.workspace` | [`workspace.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/workspace) | `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`](https://mastra.zisheng.pro/zh-TW/reference/agents/agent) 一樣執行。從 Agent API、Studio、Workflow 或應用程式的程式碼呼叫它，使用的執行階段與以程式碼定義的 Agent 相同。 探索以來源為基礎，且採保守原則。 它會略過 symlink、測試檔案，以及不是 Agent 目錄的目錄。Workflow 與專案單例檔案只有在具有 default export 時，才會依檔案路由。 透過 Mastra CLI 啟動應用程式，以便執行探索： **npm**: ```bash npx mastra dev ``` **pnpm**: ```bash pnpm dlx mastra dev ``` **Yarn**: ```bash yarn dlx mastra dev ``` **Bun**: ```bash bun x mastra dev ``` 如果你直接匯入 `mastra` instance，系統不會探索 `agents//` 目錄與其他慣例。以 library 形式使用 Mastra 時，請改為在程式碼中註冊這些 primitive。