ResponseCache

ResponseCache est un Processor d'entrée qui met en cache les réponses du LLM à la limite requête/réponse au sein de la boucle agentique. Il se raccorde à processLLMRequest pour rechercher une entrée dans le cache et court-circuite l'exécution en cas de correspondance. Il utilise processLLMResponse pour enregistrer la réponse terminée.

La clé de cache est dérivée du LanguageModelV2Prompt résolu que Mastra s'apprête à envoyer au modèle (c'est-à-dire après le chargement de la mémoire et la transformation du prompt par les Processors d'entrée précédents). Deux utilisateurs dont les contextes de mémoire diffèrent produisent donc des clés de cache différentes. Chaque étape d'une boucle agentique de Tools est mise en cache indépendamment.

Il n'existe aucune option de mise en cache des réponses au niveau de l'Agent. Enregistrez explicitement ResponseCache dans inputProcessors. Les remplacements propres à chaque appel transitent par RequestContext au moyen de ResponseCache.context() et de ResponseCache.applyContext().

Exemple d'utilisation

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

Consultez la page Mise en cache des réponses pour découvrir les concepts, les règles de portée et les modèles de déploiement recommandés.

Paramètres du constructeur

cache:

MastraServerCache

Système de cache sous-jacent. Obligatoire. Transmettez n'importe quelle implémentation de MastraServerCache : InMemoryServerCache pour le développement local, RedisCache de @mastra/redis pour la production ou votre propre sous-classe pour un système personnalisé.

ttl?:

number

= 300

Durée de vie, en secondes, des entrées écrites par ce Processor. La valeur par défaut est de 300 secondes (5 minutes), conformément à l'implémentation de référence d'OpenRouter.

scope?:

string | null

Portée du locataire ajoutée à la clé de cache. null désactive la portée. Lorsque cette option est omise, le Processor utilise par défaut l'identifiant de ressource résolu à partir du contexte de requête (MASTRA_RESOURCE_ID_KEY) afin d'isoler automatiquement chaque utilisateur.

key?:

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

Remplace la clé de cache dérivée automatiquement. Transmettez une chaîne pour fixer une clé, ou une fonction qui reçoit { agentId, scope, model, prompt, stepNumber } et renvoie une clé. Si la fonction lève une erreur, le Processor utilise par défaut le hachage déterministe afin que l'appel bénéficie tout de même de la mise en cache.

bust?:

boolean

= false

Force l'absence de correspondance dans le cache à chaque appel : ignore la lecture, mais effectue tout de même l'écriture à la fin. Utile pour les chemins d'actualisation explicites.

agentId?:

string

= 'mastra-response-cache'

Identifiant logique utilisé dans l'espace de noms de la clé de cache. La valeur par défaut est 'mastra-response-cache'. Définissez cette option sur l'identifiant de l'Agent propriétaire lorsque vous souhaitez limiter la portée des entrées de cache à chaque Agent.

Fonctions utilitaires statiques

ResponseCache expose deux fonctions utilitaires statiques permettant de définir les remplacements propres à chaque appel dans un RequestContext. Ces fonctions préservent le caractère privé de la clé de contexte sous-jacente, qui constitue un détail d'implémentation : privilégiez-les plutôt que de lire ou d'écrire directement la clé brute.

ResponseCache.context(options)

Construit un nouveau RequestContext préchargé avec les remplacements du cache de réponses propres à l'appel.

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

ResponseCache.applyContext(requestContext, options)

Fusionne les remplacements du cache de réponses propres à l'appel dans un RequestContext existant. Renvoie le même contexte afin de permettre le chaînage.

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

ResponseCacheContextOptions

Structure transmise à ResponseCache.context() / ResponseCache.applyContext().

key?:

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

Remplace la clé de cache dérivée automatiquement pour cette requête uniquement.

scope?:

string | null

Remplace la portée du locataire pour cette requête uniquement. null désactive la portée.

bust?:

boolean

Ignore la lecture du cache, mais effectue tout de même une écriture à la fin.

cache, ttl et agentId ne peuvent volontairement pas être remplacés à chaque appel : ils relèvent de l'instance et ne doivent pas varier selon la requête.

ResponseCacheKeyInputs

Argument transmis à une fonction key (dans le constructeur ou à chaque appel). Par défaut, tous les champs contribuent au hachage déterministe.

agentId:

string

Identifiant logique du Processor utilisé pour placer la clé de cache dans un espace de noms.

scope?:

string | null | undefined

Portée résolue pour cette requête, ou null lorsque la portée est désactivée.

model:

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

Identité du Provider et du modèle. Des modèles différents produisent des réponses différentes.

prompt:

LanguageModelV2Prompt

Prompt exact que le Provider recevrait après le chargement de la mémoire et l'exécution de tous les Processors d'entrée qui modifient le prompt.

stepNumber:

number

Numéro de l'étape, indexé à partir de 0, dans la boucle agentique. Supérieur à zéro pour les étapes de Tool.

Exports utilitaires

• buildResponseCacheKey(inputs) : hachage déterministe utilisé par défaut. Réexportez-le pour remplacer certains champs tout en conservant le reste de la structure de clé standard.
• DEFAULT_RESPONSE_CACHE_TTL_SECONDS : valeur par défaut de ttl (300).
• RESPONSE_CACHE_CONTEXT_KEY : clé RequestContext dans laquelle les fonctions utilitaires statiques écrivent. Exposée pour les cas avancés (par exemple, la suppression du remplacement au milieu du pipeline). Privilégiez les fonctions utilitaires.

Voir aussi

• Mise en cache des réponses
• Processors
• Interface Processor