指示

Agent の指示には、常時適用するシステムプロンプトを記述します。モデルはターンごとにこの指示を読み取ります。Agent のアイデンティティ、トーン、役割、常設ルールを定義するために使用します。

指示は Agent ルートにある2種類のファイルのいずれかに記述します。プロンプトが固定テキストの場合は instructions.md、共有定数から組み立てる場合やリクエストごとに解決する場合など、プロンプトにコードが必要な場合は instructions.ts を使用します。

指示は常にコンテキストに含まれるため、すべてのリクエストに適用する安定した動作だけを記述してください。条件付きの内容、大規模な内容、アクション指向の内容は、モデルが関連するときだけ使用する tools/ または skills/ に移します。

クイックスタート

Agent ルートに instructions.md を追加します。記述した内容がそのままプロンプトになるため、最も短い形式は1文だけです。

src/mastra/agents/weather/instructions.md

You are a helpful weather assistant. Answer questions about current conditions and forecasts.

指示に記述する内容

効果的な指示には、リクエスト間で変化しない Agent の動作を記述します。

• 役割とアイデンティティ
• トーンとスタイル
• 常設ルール
• 出力形式

条件付きの内容、大規模な内容、アクション指向のガイダンスは、モデルが関連するときだけ使用する tools/ または skills/ に移します。

TypeScript での指示

Markdown ではプロンプトを表現できない場合は、instructions.ts を使用します。このファイルは、文字列、システムメッセージ、またはそのいずれかを返す関数をデフォルトエクスポートします。agentInstructions() はエクスポートの内容を変更せずに型を付与します。

アプリの他の部分と共有する定数などを使ってコード内でプロンプトを組み立てる場合は、文字列をエクスポートします。

src/mastra/agents/weather/instructions.ts

import { agentInstructions } from '@mastra/core/agent'
import { SUPPORTED_UNITS } from '../../constants'

export default agentInstructions(`
You are a helpful weather assistant.
Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
`)

プロンプトがリクエストに依存する場合は、関数をエクスポートします。Mastra はターンごとにこの関数を呼び出し、リクエストコンテキストを渡します。

src/mastra/agents/support/instructions.ts

import { agentInstructions } from '@mastra/core/agent'

export default agentInstructions(({ requestContext }) => {
  const tier = requestContext.get('tier') ?? 'standard'
  return `You are a support agent. Treat this as a ${tier}-tier customer.`
})

この関数は async にすることもでき、requestContext とともに mastra を受け取ります。そのため、プロンプトを返す前にストレージや別の登録済みプリミティブから情報を読み取れます。

どちらのファイルも、同じルールに従う Subagent のディレクトリに配置できます。

ビルド時の動作

デプロイされる Agent への instructions.md と instructions.ts の組み込み方は異なります。

• instructions.md：Mastra はファイルを読み取り、ビルド時にその内容を生成コードへインライン化します。
• instructions.ts：生成コードがモジュールをインポートするため、他の TypeScript ファイルと同様にバンドルされ、プロジェクトの他の部分からインポートできます。

mastra dev では、どちらのファイルを編集しても再ビルドが実行されます。デプロイ済みアプリでは、実行時にどちらのファイルもディスクから読み取られないため、変更は次回のビルド後に反映されます。

config との優先順位

指示は、instructions.ts、instructions.md、または config.ts の instructions フィールドから指定できます。

• config.ts でランタイム定義された関数形式の instructions は、両方のファイルより優先されます。
• それ以外の場合、instructions.ts は instructions.md より優先されます。
• instructions.md は、config.ts の静的な instructions 文字列より優先されます。
• いずれも存在しない場合、ビルドは失敗し、Agent ディレクトリの名前がエラーに表示されます。

複数の場所に指示を定義すると、両方のソースとどちらが優先されるかを示す警告がログに記録されます。Agent ごとにソースを1つだけ使用してください。