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

# ResponseCache

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

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

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

## 使用例

```typescript
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 }),
})
```

概念の概要、スコープ規則、推奨されるデプロイパターンについては、[レスポンスキャッシュ](https://mastra.zisheng.pro/ja/docs/agents/processors)を参照してください。

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

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

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

**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`): すべての呼び出しでキャッシュミスを強制します。読み取りはスキップしますが、完了時の書き込みは行います。明示的な更新処理に便利です。 (Default: `false`)

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

## 静的ヘルパー

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

### `ResponseCache.context(options)`

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

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

### `ResponseCache.applyContext(requestContext, options)`

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

```typescript
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` キー。オーバーライドをパイプラインの途中で消去する場合など、高度な用途向けに公開されています。通常はヘルパーを使用してください。

## 関連情報

- [レスポンスキャッシュ](https://mastra.zisheng.pro/ja/docs/agents/processors)
- [Processors](https://mastra.zisheng.pro/ja/docs/agents/processors)
- [Processor インターフェース](https://mastra.zisheng.pro/ja/reference/processors/processor-interface)