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

# 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](https://mastra.zisheng.pro/fr/docs/editor/overview) 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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/server/request-context). 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 :

```typescript
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`](https://mastra.zisheng.pro/fr/reference/editor/mastra-editor) pour connaître les signatures complètes des méthodes.

Créez un bloc de prompt :

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/editor/overview) pour découvrir le cycle de vie commun de création de brouillons, de publication et de restauration.