ResponseCache

ResponseCache は、Agent ループ内のリクエスト／レスポンス境界で LLM レスポンスをキャッシュする input processor です。キャッシュ検索には processLLMRequest を使用し、ヒットした場合は処理を短絡します。完了したレスポンスの書き込みには processLLMResponse を使用します。

キャッシュキーは、Mastra がモデルへ送信しようとしている解決済みの LanguageModelV2Prompt（つまり、Memory が読み込まれ、先行する input processor がプロンプトを変換した_後_）から導出されます。そのため、Memory コンテキストが異なる2人のユーザーには異なるキャッシュキーが生成されます。Agent の Tool ループ内の各ステップは個別にキャッシュされます。

レスポンスキャッシュ用の Agent レベルのオプションはありません。ResponseCache を inputProcessors に明示的に登録してください。呼び出しごとのオーバーライドは、ResponseCache.context() と ResponseCache.applyContext() を介して RequestContext から渡されます。

使用例

import { Agent } from '@mastra/core/agent'
import { InMemoryServerCache } from '@mastra/core/cache'
import { ResponseCache } from '@mastra/core/processors'

const cache = new InMemoryServerCache()

const agent = new Agent({
  id: 'search-agent',
  name: 'Search Agent',
  instructions: 'You answer questions concisely.',
  model: 'openai/gpt-5',
  inputProcessors: [new ResponseCache({ cache, ttl: 600 })],
})

// First call hits the LLM and writes to the cache.
await agent.generate('What is the capital of France?')

// Second identical call replays the cached response.
await agent.generate('What is the capital of France?')

// Force a fresh call but still update the cache.
await agent.generate('What is the capital of France?', {
  requestContext: ResponseCache.context({ bust: true }),
})

概念の概要、スコープ規則、推奨されるデプロイパターンについては、レスポンスキャッシュを参照してください。

コンストラクターパラメーター

cache:

MastraServerCache

キャッシュバックエンド。必須です。任意の MastraServerCache 実装を渡せます。ローカル開発には InMemoryServerCache、本番環境には @mastra/redis の RedisCache、カスタムバックエンドには独自のサブクラスを使用します。

ttl?:

number

= 300

この Processor が書き込むエントリの有効期間（秒）。デフォルトは OpenRouter のリファレンス実装と同じ 300 秒（5分）です。

scope?:

string | null

キャッシュキーに追加するテナントスコープ。null を指定するとスコープを無効にします。省略した場合、Processor は Request コンテキストから解決したリソース ID（MASTRA_RESOURCE_ID_KEY）を使用し、ユーザーごとに自動分離します。

key?:

string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>

自動導出されるキャッシュキーをオーバーライドします。キーを固定するには文字列を渡します。または、{ agentId, scope, model, prompt, stepNumber } を受け取りキーを返す関数を渡します。関数が例外をスローした場合、Processor は決定論的ハッシュへフォールバックするため、呼び出しは引き続きキャッシュを利用できます。

bust?:

boolean

= false

すべての呼び出しでキャッシュミスを強制します。読み取りはスキップしますが、完了時の書き込みは行います。明示的な更新処理に便利です。

agentId?:

string

= 'mastra-response-cache'

キャッシュキーの名前空間で使用する論理 ID。デフォルトは 'mastra-response-cache' です。キャッシュエントリを Agent ごとにスコープする場合は、所有する Agent の ID を設定します。

静的ヘルパー

ResponseCache は、RequestContext に呼び出しごとのオーバーライドを設定する2つの静的ヘルパーを公開します。これらのヘルパーにより、内部のコンテキストキーは非公開の実装詳細として維持されます。生のキーを直接読み書きせず、ヘルパーを使用してください。

ResponseCache.context(options)

呼び出しごとのレスポンスキャッシュのオーバーライドを事前に読み込んだ、新しい RequestContext を作成します。

await agent.stream('hello', {
  requestContext: ResponseCache.context({ key: 'custom', bust: true }),
})

ResponseCache.applyContext(requestContext, options)

既存の RequestContext に、呼び出しごとのレスポンスキャッシュのオーバーライドをマージします。チェーンできるよう、同じコンテキストを返します。

const ctx = new RequestContext()
ctx.set('caller-meta', { userId: 'u-123' })
ResponseCache.applyContext(ctx, { bust: true })
await agent.stream('hello', { requestContext: ctx })

ResponseCacheContextOptions

ResponseCache.context() / ResponseCache.applyContext() に渡す形式です。

key?:

string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>

このリクエストに限り、自動導出されるキャッシュキーをオーバーライドします。

scope?:

string | null

このリクエストに限り、テナントスコープをオーバーライドします。null を指定するとスコープを無効にします。

bust?:

boolean

キャッシュの読み取りをスキップしますが、完了時の書き込みは行います。

cache、ttl、agentId は、意図的に呼び出しごとのオーバーライドを許可していません。これらはリクエストごとに変えるべきではない、インスタンスレベルの設定です。

ResponseCacheKeyInputs

（コンストラクターまたは呼び出しごとの）key 関数に渡す引数です。デフォルトでは、すべてのフィールドが決定論的ハッシュに反映されます。

agentId:

string

キャッシュキーの名前空間に使用する論理 Processor ID。

scope?:

string | null | undefined

このリクエストで解決されたスコープ。スコープが無効な場合は null です。

model:

{ provider?: string; modelId?: string; specVersion?: string }

Provider／モデルの識別情報。モデルが異なれば、生成されるレスポンスも異なります。

prompt:

LanguageModelV2Prompt

Memory の読み込みと、プロンプトを変更する input processor の処理を終えた後、Provider が実際に受け取るプロンプト。

stepNumber:

number

Agent ループ内の0始まりのステップ番号。Tool ステップでは0より大きくなります。

ヘルパーのエクスポート

• buildResponseCacheKey(inputs)：デフォルトで使用される決定論的ハッシュ。標準のキー形式の残りを維持したまま個々のフィールドをオーバーライドするために、再エクスポートできます。
• DEFAULT_RESPONSE_CACHE_TTL_SECONDS：デフォルトの ttl（300）。
• RESPONSE_CACHE_CONTEXT_KEY：静的ヘルパーが書き込む RequestContext キー。オーバーライドをパイプラインの途中で消去する場合など、高度な用途向けに公開されています。通常はヘルパーを使用してください。

関連情報

• レスポンスキャッシュ
• Processors
• Processor インターフェース