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

# config.ts

Agent 的 `config.ts` 會設定其模型及執行階段選項。屬於 [`Agent`](https://mastra.zisheng.pro/zh-HK/reference/agents/agent) 本身的選項應放在此檔案，而同層檔案則提供 instructions、tools、skills 等內容。

## `config.ts` 應包含的內容

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

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

當穩定的路由鍵與顯示名稱應有所不同時，請覆寫 `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` 建構函數選項](https://mastra.zisheng.pro/zh-HK/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-HK/reference/file-based-agents/instructions) | 以易讀的 markdown 保留始終生效的 prompt，或使用 TypeScript 動態產生內容 |
| Tools        | [`tools/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/tools)                                     | 讓每項可調用操作各自擁有具型別的模組                                 |
| Skills       | [`skills/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/skills)                                   | 將按需要載入的程序與始終生效的 instructions 分開                    |
| Memory       | [`memory.ts`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/memory)                                 | 設定持久 memory，避免執行階段選項過於擁擠                           |
| Workspace    | [`workspace.ts`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/workspace)                           | 將檔案及 Sandbox 行為與模型設定分開設定                           |
| Processors   | [`processors/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/processors)                           | 分隔輸入及輸出處理管線                                        |
| Subagents    | [`subagents/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/subagents)                             | 讓每個專門的子 Agent 擁有獨立目錄                               |

## 優先次序

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

| 範疇           | 來源 A                                                                                           | 來源 B                                                                                                               | 優先採用者                            |
| ------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| Instructions | 動態 `config.instructions`                                                                       | [`instructions.ts` 或 `instructions.md`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/instructions) | 動態 `config.instructions`         |
| Instructions | 靜態 `config.instructions`                                                                       | [`instructions.ts` 或 `instructions.md`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/instructions) | instructions 檔案                  |
| Instructions | [`instructions.ts`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/instructions) | [`instructions.md`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/instructions)                     | `instructions.ts`                |
| Tools        | `config.tools`                                                                                 | [`tools/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/tools)                                     | 兩者合併；鍵發生衝突時以 `config.tools` 為準   |
| Tools        | 函數 `config.tools`                                                                              | [`tools/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/tools)                                     | 函數 `config.tools`；忽略已探索的 tools   |
| Skills       | `config.skills`                                                                                | [`skills/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/skills)                                   | 兩者合併；名稱發生衝突時以 `config.skills` 為準 |
| Skills       | 函數 `config.skills`                                                                             | [`skills/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/skills)                                   | 函數 `config.skills`；忽略已探索的 skills |
| Memory       | `config.memory`                                                                                | [`memory.ts`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/memory)                                 | `config.memory`                  |
| Workspace    | `config.workspace`                                                                             | [`workspace.ts`](https://mastra.zisheng.pro/zh-HK/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` 期間探索檔案式 primitives。探索期間，Mastra 會讀取 `src/mastra/` 下支援的檔案、匯入 TypeScript 及 JavaScript 模組、讀取 markdown instructions 及 skills、複製 Workspace 種子檔案，並向你的 Mastra 應用程式註冊組合完成的 primitives。

探索完成後，檔案式 Agent 會以一般 [`Agent`](https://mastra.zisheng.pro/zh-HK/reference/agents/agent) 的方式運作。透過 Agent API、Studio、Workflow 或應用程式程式碼調用它時，會使用與程式碼定義 Agent 相同的執行階段。

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

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