config.ts

Agent 的 config.ts 用于设置模型和运行时选项。请在其中配置属于 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：

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',
})

根据目录确定身份

File-based 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 参考。

请注意：

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

相邻设置的存放位置

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

设置	文件或文件夹	存放于此的原因
Instructions	instructions.md 或 instructions.ts	将始终启用的 prompt 以易读的 Markdown 保存，或在 TypeScript 中动态计算
Tools	tools/	为每个可调用操作提供独立的类型化模块
Skills	skills/	将按需加载的流程与始终启用的 instructions 分开
Memory	memory.ts	配置持久化 memory，而不会让运行时选项过于拥挤
Workspace	workspace.ts	将文件和 sandbox 行为与模型设置分开配置
Processors	processors/	分离输入和输出处理 pipeline
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；忽略发现的 Tool
Skills	config.skills	skills/	两者合并；名称冲突时 config.skills 优先
Skills	函数 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 下发现基于文件的组件。发现期间，Mastra 会读取 src/mastra/ 下受支持的文件、导入 TypeScript 和 JavaScript 模块、读取 Markdown instructions 和 Skill、复制 Workspace 种子文件，并将组装后的组件注册到 Mastra 应用。

发现后，File-based Agent 会像普通 Agent 一样运行。通过 Agent API、Studio、Workflow 或应用代码调用它时，使用的运行时与代码定义的 Agent 相同。

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

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

通过 Mastra CLI 启动应用以运行发现过程：

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

如果直接导入 mastra 实例，则不会发现 agents/<name>/ 目录及其他约定。将 Mastra 作为库使用时，请改为在代码中注册这些组件。