> ## Documentation Index
> Fetch the complete documentation index at: https://docsmlx.otterly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Instructions

> Définir le rôle, le ton et le format attendus pour une session

Les instructions servent à cadrer le modèle pour toute la durée d'une session. Elles définissent le comportement général, alors que le prompt représente la demande du moment.

Si vous voulez des réponses cohérentes d'un appel à l'autre, commencez par de bonnes instructions.

***

## Exemple minimal

```swift theme={null}
import FoundationModels

let session = LanguageModelSession(
    instructions: """
    You are a concise assistant for Swift developers.
    Keep answers short, practical, and easy to scan.
    """
)
```

Ces instructions seront prises en compte pour chaque prompt envoyé à cette session.

***

## Version builder

Le framework propose aussi `Instructions` :

```swift theme={null}
let instructions = Instructions {
    "You are a Swift UI writing assistant."
    "Prefer concise answers."
    "When you list steps, keep them actionable."
}

let session = LanguageModelSession(instructions: instructions)
```

Cette forme est pratique si vous composez les instructions à partir d'états contrôlés par l'app.

***

## Instructions vs prompt

| Question             | Instructions                                         | Prompt                                     |
| -------------------- | ---------------------------------------------------- | ------------------------------------------ |
| Quand ça change      | Quand le rôle, la feature ou le format stable change | À chaque requête                           |
| Ce que vous y mettez | Le ton, les limites, le style, le format durable     | La demande du moment et son contexte local |
| Qui le contrôle      | Votre code                                           | Votre code et souvent l'action utilisateur |

En général :

* mettez les règles persistantes dans les instructions
* mettez la demande concrète dans le prompt

Si vous avez un doute, posez-vous cette question : "est-ce que cette consigne doit survivre à plusieurs requêtes ?" Si oui, elle a plus de chances d'appartenir aux instructions.

***

## Ce qui doit rester stable dans les instructions

Mettez dans `Instructions` ce que votre feature veut répéter sans le redire à chaque appel :

* le rôle du modèle
* le niveau de détail attendu
* le format général
* les limites métier stables

Exemple :

```text theme={null}
You help intermediate Swift developers.
Prefer short, concrete answers.
Do not invent APIs.
```

Le prompt, lui, doit rester libre de décrire la tâche du moment.

***

## Ce qu'une bonne instruction doit contenir

### Le rôle

Exemple :

```text theme={null}
You are a documentation assistant for intermediate Swift developers.
```

### Le niveau de détail

Exemple :

```text theme={null}
Keep answers concise and practical.
```

### Le format attendu

Exemple :

```text theme={null}
Use a short title and then 3 bullet points maximum.
```

### Les limites utiles

Exemple :

```text theme={null}
Do not invent APIs. If something is uncertain, say so.
```

***

## Un exemple plus réaliste

```swift theme={null}
let session = LanguageModelSession(
    instructions: """
    You help intermediate Swift developers understand on-device AI features.
    Prefer clear explanations over jargon.
    When relevant, compare Foundation Models and MLX.
    Keep the answer short unless the user asks for depth.
    """
)
```

Avec ce type de cadrage, les réponses deviennent plus régulières.

***

## Ce qu'il faut éviter

### Des instructions trop longues

Des instructions verbeuses coûtent plus cher en contexte et sont plus difficiles à maintenir.

### Des instructions qui dupliquent le prompt

Si une contrainte ne vaut que pour une demande précise, laissez-la dans le prompt.

### Des instructions pilotées par la saisie libre de l'utilisateur

N'injectez pas directement du texte utilisateur dans `instructions`.

```swift theme={null}
// A éviter
let session = LanguageModelSession(instructions: userInput)
```

Gardez les instructions sous le contrôle du code de l'app.

***

## Quand créer une nouvelle session

Créez une nouvelle session si :

* le rôle du modèle change
* le format attendu change fortement
* la conversation précédente n'a plus de rapport avec la nouvelle tâche

Une session claire et ciblée fonctionne mieux qu'une session globale qui essaie de tout faire.

***

<CardGroup cols={2}>
  <Card title="Prompts" icon="pen-fancy" href="/mlx/foundation-models/prompts">
    Poser la bonne question pour chaque requête.
  </Card>

  <Card title="Cycle de vie" icon="arrows-rotate" href="/mlx/foundation-models/session-lifecycle">
    Gérer les sessions proprement dans l'app.
  </Card>
</CardGroup>