Blocs de prompt

Les blocs de prompt sont des templates d’instructions réutilisables gérés par Editor. Les instructions d’un Agent peuvent combiner du texte inline, des blocs de prompt intégrés et des références à des blocs de prompt dont les versions sont gérées indépendamment.

Consultez les blocs de prompt pour découvrir le Workflow dans Studio et les usages courants.

Types de blocs

Type	Description
text	Texte libre stocké uniquement dans la version de l’Agent
prompt_block	Bloc de prompt intégré à la version de l’Agent
prompt_block_ref	Référence à un bloc de prompt stocké et versionné indépendamment

Les blocs référencés sont résolus lors de l’exécution. Une référence absente ou non publiée est omise des instructions finales. Les blocs résolus non vides sont reliés par deux sauts de ligne.

L’exemple suivant associe un bloc stocké et du texte inline à un Agent :

src/scripts/attach-prompt.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: [
    { type: 'prompt_block_ref', id: 'brand-voice' },
    { type: 'text', content: 'Answer only questions about Acme products.' },
  ],
})

Valeurs des templates

Les templates résolvent les valeurs depuis le contexte de requête lors de l’exécution.

Syntaxe	Contexte de requête	Sortie
{{userName}}	{ userName: 'Maya' }	Maya
{{user.name}}	{ user: { name: 'Maya' } }	Maya
{{task || 'request'}}	{}	request
{{missingValue}}	{}	{{missingValue}}

Les noms de variables doivent commencer par une lettre ou un trait de soulignement. Les valeurs de repli doivent être des chaînes entre guillemets simples ou doubles. Les placeholders non résolus sans valeur de repli restent inchangés. Les objets et les tableaux sont sérialisés au format JSON. Les autres valeurs sont converties en chaînes.

Transmettez les valeurs par l’intermédiaire du contexte de requête. Editor ne lit pas de champ variables distinct sur l’Agent.

Conditions d’affichage

Un bloc de prompt peut inclure une condition d’affichage qui détermine s’il figure dans les instructions finales. Chaque condition comporte trois parties :

• Clé : champ du contexte de requête à vérifier, tel que user.role ou account.plan.
• Opérateur : comparaison à effectuer, telle que equals, contains ou exists.
• Valeur : valeur à laquelle effectuer la comparaison. Les opérateurs exists et not_exists n’en ont pas besoin.

Par exemple, la condition user.role equals admin inclut le bloc uniquement lorsque le contexte de requête contient { user: { role: 'admin' } }.

Opérateur	Exemple	Le bloc est inclus lorsque
equals / not_equals	user.role equals admin	Le champ est strictement égal, ou n’est pas égal, à la valeur
contains / not_contains	user.tags contains beta	Une chaîne contient la valeur ou un tableau contient l’élément
greater_than / less_than	order.total greater than 100	Le champ numérique est supérieur ou inférieur à la valeur
greater_than_or_equal / less_than_or_equal	account.seats greater than or equal to 10	Le champ numérique est supérieur ou égal, ou inférieur ou égal, à la valeur
in / not_in	user.region in ['US', 'CA']	Le champ appartient, ou n’appartient pas, au tableau fourni
exists / not_exists	account.plan exists	Le champ possède, ou ne possède pas, une valeur non nulle

Les groupes combinent les conditions avec AND ou OR. Par exemple, ce groupe inclut un bloc pour les administrateurs disposant d’un forfait payant :

const rules = {
  operator: 'AND',
  conditions: [
    {
      field: 'user.role',
      operator: 'equals',
      value: 'admin',
    },
    {
      field: 'account.plan',
      operator: 'in',
      value: ['pro', 'enterprise'],
    },
  ],
}

Les chemins à points sont pris en charge. Un groupe vide est évalué à true, tandis qu’un opérateur inconnu est évalué à false. Le type de stockage prend en charge jusqu’à trois niveaux de groupes imbriqués.

Les blocs sans condition sont toujours inclus.

API programmatique

Accédez aux blocs de prompt avec mastra.getEditor().prompt. Consultez l’espace de noms prompt pour connaître les signatures complètes des méthodes.

Créez un bloc de prompt :

src/scripts/seed-prompts.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.prompt.create({
  id: 'brand-voice',
  name: 'Brand voice',
  description: 'Acme tone and style guidelines',
  content: 'Write in a friendly, concise tone. Address the user as {{userName || "there"}}.',
})

Mettez à jour un bloc existant :

src/scripts/update-prompt.ts

await editor.prompt.update({
  id: 'brand-voice',
  content: 'Write in a friendly, concise tone. Greet the user by name when available.',
})

update() crée un nouveau brouillon lorsque le contenu change. Utilisez list() pour parcourir les blocs stockés avec pagination, getById() pour récupérer un bloc et preview(blocks, context) pour résoudre les templates et les conditions avec les références aux brouillons.

REST API

Le préfixe par défaut du serveur Mastra est /api. Un préfixe de serveur personnalisé modifie les chemins ci-dessous.

Méthode	Chemin	Description
GET	/api/stored/prompt-blocks	Répertorie les blocs de prompt stockés
POST	/api/stored/prompt-blocks	Crée un bloc de prompt stocké
GET	/api/stored/prompt-blocks/:storedPromptBlockId	Récupère un bloc de prompt stocké
PATCH	/api/stored/prompt-blocks/:storedPromptBlockId	Met à jour un bloc de prompt stocké
DELETE	/api/stored/prompt-blocks/:storedPromptBlockId	Supprime un bloc de prompt stocké

Résolution des versions

Lors de l’exécution, les références résolvent le bloc publié actif. Les aperçus d’Editor résolvent le brouillon le plus récent. Consultez la gestion des versions d’Editor pour découvrir le cycle de vie commun de création de brouillons, de publication et de restauration.