config.ts

Agent の config.ts では、モデルとランタイムオプションを設定します。Agent 自体に属するオプションにはこのファイルを使用し、指示、Tool、Skill などは同階層のファイルで指定します。

config.ts に記述する内容

config.ts は、ファイルベースの Agent のモデルとランタイムオプションを定義する必須のエントリーポイントです。モデル、説明、デフォルトの実行オプション、再試行動作、Scorer、表示上の識別情報など、専用ファイルを必要としない Agent レベルの設定をここに記述します。

ファイルベースのルーティングによって Agent に統合する関連項目は、同階層のファイルに分けてください。たとえば、常時適用するプロンプトには instructions.md、モデルから呼び出せるアクションには 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 から必須の指示が提供されます。

モデルの設定

agentConfig() で必須のフィールドは model だけです。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.md または instructions.ts	常時適用するプロンプトを読みやすい Markdown で記述するか、TypeScript で動的に生成できる
Tool	tools/	呼び出し可能な各アクションを型付きの個別モジュールにできる
Skill	skills/	必要に応じて読み込む手順を、常時適用する指示から分離できる
Memory	memory.ts	ランタイムオプションを煩雑にせずに永続 Memory を設定できる
Workspace	workspace.ts	ファイルと Sandbox の動作をモデル設定とは別に設定できる
Processor	processors/	入力と出力の処理パイプラインを分離できる
Subagent	subagents/	専門分野ごとの子 Agent に個別のディレクトリを割り当てられる

優先順位

config.ts は、次のルールに従って Agent の他のファイルと統合されます。

領域	ソース A	ソース B	優先されるもの
指示	動的な config.instructions	instructions.ts または instructions.md	動的な config.instructions
指示	静的な config.instructions	instructions.ts または instructions.md	指示ファイル
指示	instructions.ts	instructions.md	instructions.ts
Tool	config.tools	tools/	両方を統合し、キーが競合した場合は config.tools が優先される
Tool	関数形式の config.tools	tools/	関数形式の config.tools。検出された Tool は無視される
Skill	config.skills	skills/	両方を統合し、名前が競合した場合は config.skills が優先される
Skill	関数形式の 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 dev と mastra build の実行時に Mastra バンドラーによって検出されます。検出時に Mastra は、src/mastra/ 以下の対応ファイルを読み取り、TypeScript と JavaScript のモジュールをインポートし、Markdown の指示と Skill を読み込み、Workspace のシードファイルをコピーして、構成済みのプリミティブを Mastra アプリに登録します。

検出後、ファイルベースの 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 をライブラリとして使用する場合は、それらのプリミティブをコードで登録してください。