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

# config.ts

Agent 的 `config.ts` 用于设置模型和运行时选项。请在其中配置属于 [`Agent`](https://mastra.zisheng.pro/reference/agents/agent) 本身的选项，instructions、Tool、Skill 等则由同级文件提供。

## `config.ts` 中应包含的内容

`config.ts` 是 File-based Agent 模型和运行时选项的必需入口点。当 Agent 级设置不需要单独文件时，请放在这里，例如模型、描述、默认执行选项、重试行为、Scorer 和显示身份。

如果希望基于文件的路由将相邻关注点合并到 Agent 中，请将它们保留在同级文件中。例如，使用 `instructions.md` 存放始终启用的 prompt，使用 `tools/` 存放模型可调用的操作。

## 快速开始

以下 `config.ts` 和一个 `instructions.md` 文件可创建可运行的 File-based 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',
})
```

## 根据目录确定身份

File-based 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/reference/agents/agent)，但 `id`、`name` 和同级文件字段可以由基于文件的约定提供。有关完整的选项列表，请参阅 Agent 参考。

请注意：

- 基于文件的子 Agent 必须提供非空的 `description`，因为父级模型会使用它进行委派路由。
- 当 `defaultOptions`、`maxRetries`、`scorers` 和其他 Agent 选项不需要单独文件时，可以放在 `config.ts` 中。

## 相邻设置的存放位置

让 `config.ts` 专注于运行时选项。对于适合单独存放的关注点，请使用同级文件。

| 设置           | 文件或文件夹                                                                                                       | 存放于此的原因                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| Instructions | [`instructions.md` 或 `instructions.ts`](https://mastra.zisheng.pro/reference/file-based-agents/instructions) | 将始终启用的 prompt 以易读的 Markdown 保存，或在 TypeScript 中动态计算 |
| Tools        | [`tools/`](https://mastra.zisheng.pro/reference/file-based-agents/tools)                                     | 为每个可调用操作提供独立的类型化模块                                 |
| Skills       | [`skills/`](https://mastra.zisheng.pro/reference/file-based-agents/skills)                                   | 将按需加载的流程与始终启用的 instructions 分开                     |
| Memory       | [`memory.ts`](https://mastra.zisheng.pro/reference/file-based-agents/memory)                                 | 配置持久化 memory，而不会让运行时选项过于拥挤                         |
| Workspace    | [`workspace.ts`](https://mastra.zisheng.pro/reference/file-based-agents/workspace)                           | 将文件和 sandbox 行为与模型设置分开配置                           |
| Processors   | [`processors/`](https://mastra.zisheng.pro/reference/file-based-agents/processors)                           | 分离输入和输出处理 pipeline                                 |
| Subagents    | [`subagents/`](https://mastra.zisheng.pro/reference/file-based-agents/subagents)                             | 为每个专业子 Agent 提供独立目录                                |

## 优先级

`config.ts` 根据以下规则与 Agent 的其他文件合并：

| 领域           | 来源 A                                                                                     | 来源 B                                                                                                         | 优先项                            |
| ------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| Instructions | 动态 `config.instructions`                                                                 | [`instructions.ts` 或 `instructions.md`](https://mastra.zisheng.pro/reference/file-based-agents/instructions) | 动态 `config.instructions`       |
| Instructions | 静态 `config.instructions`                                                                 | [`instructions.ts` 或 `instructions.md`](https://mastra.zisheng.pro/reference/file-based-agents/instructions) | Instructions 文件                |
| Instructions | [`instructions.ts`](https://mastra.zisheng.pro/reference/file-based-agents/instructions) | [`instructions.md`](https://mastra.zisheng.pro/reference/file-based-agents/instructions)                     | `instructions.ts`              |
| Tools        | `config.tools`                                                                           | [`tools/`](https://mastra.zisheng.pro/reference/file-based-agents/tools)                                     | 两者合并；键冲突时 `config.tools` 优先    |
| Tools        | 函数 `config.tools`                                                                        | [`tools/`](https://mastra.zisheng.pro/reference/file-based-agents/tools)                                     | 函数 `config.tools`；忽略发现的 Tool   |
| Skills       | `config.skills`                                                                          | [`skills/`](https://mastra.zisheng.pro/reference/file-based-agents/skills)                                   | 两者合并；名称冲突时 `config.skills` 优先  |
| Skills       | 函数 `config.skills`                                                                       | [`skills/`](https://mastra.zisheng.pro/reference/file-based-agents/skills)                                   | 函数 `config.skills`；忽略发现的 Skill |
| Memory       | `config.memory`                                                                          | [`memory.ts`](https://mastra.zisheng.pro/reference/file-based-agents/memory)                                 | `config.memory`                |
| Workspace    | `config.workspace`                                                                       | [`workspace.ts`](https://mastra.zisheng.pro/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` 下发现基于文件的组件。发现期间，Mastra 会读取 `src/mastra/` 下受支持的文件、导入 TypeScript 和 JavaScript 模块、读取 Markdown instructions 和 Skill、复制 Workspace 种子文件，并将组装后的组件注册到 Mastra 应用。

发现后，File-based Agent 会像普通 [`Agent`](https://mastra.zisheng.pro/reference/agents/agent) 一样运行。通过 Agent API、Studio、Workflow 或应用代码调用它时，使用的运行时与代码定义的 Agent 相同。

发现过程以源文件为基础，并采取保守策略。

它会跳过符号链接、测试文件和并非 Agent 目录的目录。仅当 Workflow 和项目级单例文件包含默认导出时，才会按文件路由它们。

通过 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` 实例，则不会发现 `agents/<name>/` 目录及其他约定。将 Mastra 作为库使用时，请改为在代码中注册这些组件。