Intégration dans les Agents et Conversations

⚠️ Modèle déprécié (mise à jour du 28 juillet 2026) : les modèles Magistral sont dépréciés par Mistral, avec des retraits échelonnés jusqu’à mi-2026. Le raisonnement est désormais intégré aux modèles généralistes (Mistral Small 4, Medium 3.5). Les concepts de ce cours restent instructifs, mais ne construisez plus de nouveau projet sur Magistral — consultez le cours « Mistral en 2026 » pour la migration.

Au-delà du Chat Completions

Jusqu’ici, vous avez utilisé le raisonnement ajustable via l’endpoint Chat Completions. Mais Mistral AI met également le raisonnement à disposition dans deux autres contextes, les Agents et les Conversations, chacun avec sa mécanique propre. Le choix entre les trois n’est pas cosmétique : il détermine où vit la configuration du raisonnement et qui porte la charge de l’historique.

Raisonnement dans Chat Completions

C’est l’intégration la plus directe : le paramètre reasoning_effort est passé au niveau de la requête, aux côtés du modèle et des messages.

from mistralai import Mistral

client = Mistral(api_key="VOTRE_CLE_API")

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {"role": "system", "content": "Vous êtes un expert en mathématiques."},
        {"role": "user", "content": "Démontrez que la racine de 2 est irrationnelle."}
    ],
    reasoning_effort="high"
)

Cette méthode convient aux appels ponctuels où vous contrôlez directement chaque requête — un pipeline de traitement par lots, par exemple, qui n’active la réflexion que sur certains documents.

Raisonnement dans les Agents

L’endpoint Agents permet de créer des assistants persistants avec des instructions, des outils et des paramètres prédéfinis. Le raisonnement s’y active via le champ completion_args, une fois pour toutes :

# Création d'un agent avec raisonnement actif
agent = client.beta.agents.create(
    model="mistral-small-latest",
    name="Analyste Technique",
    instructions="Vous êtes un analyste technique senior. Analysez chaque problème en profondeur avant de formuler vos recommandations.",
    completion_args={
        "reasoning_effort": "high"
    }
)

# Utilisation de l'agent
response = client.beta.agents.complete(
    agent_id=agent.id,
    messages=[
        {"role": "user", "content": "Notre API a un temps de réponse de 3 secondes en P99. Comment optimiser ?"}
    ]
)

L’intérêt tient à cette configuration unique : le raisonnement est défini à la création, plus personne n’a besoin de repasser reasoning_effort à chaque appel, et les instructions système orientent la réflexion dans une direction précise. C’est le format naturel des assistants spécialisés — analyste, debugger, tuteur — où le niveau de réflexion attendu ne varie pas d’une question à l’autre.

Cette rigidité devient un atout si vous instanciez plusieurs agents de niveaux différents et routez les requêtes entre eux :

# Agent rapide pour les questions simples
agent_fast = client.beta.agents.create(
    model="mistral-small-latest",
    name="Assistant Rapide",
    instructions="Répondez de manière concise et directe.",
    completion_args={"reasoning_effort": "none"}
)

# Agent analytique pour les problèmes complexes
agent_deep = client.beta.agents.create(
    model="mistral-small-latest",
    name="Analyste",
    instructions="Analysez chaque problème méthodiquement.",
    completion_args={"reasoning_effort": "high"}
)

def route_query(client, question):
    """Route vers l'agent approprié selon la complexité."""
    complex_indicators = ["pourquoi", "compare", "analyse", "optimise", "debug"]
    is_complex = any(ind in question.lower() for ind in complex_indicators)

    agent_id = agent_deep.id if is_complex else agent_fast.id
    return client.beta.agents.complete(
        agent_id=agent_id,
        messages=[{"role": "user", "content": question}]
    )

Raisonnement dans les Conversations

L’endpoint Conversations gère l’historique des échanges côté serveur. Le raisonnement s’active de la même manière, via completion_args à la création :

# Créer une conversation avec raisonnement
conversation = client.beta.conversations.create(
    model="mistral-small-latest",
    completion_args={
        "reasoning_effort": "high"
    }
)

# Premier message
response1 = client.beta.conversations.append(
    conversation_id=conversation.id,
    messages=[
        {"role": "user", "content": "J'ai un bug dans mon code Python. La fonction retourne None au lieu d'une liste."}
    ]
)

# Suivi — le contexte est conservé automatiquement
response2 = client.beta.conversations.append(
    conversation_id=conversation.id,
    messages=[
        {"role": "user", "content": "Voici le code : def get_items(data): for item in data: if item > 0: return item"}
    ]
)

Observez le second appel : vous ne renvoyez que le nouveau message. L’historique étant géré côté serveur, le modèle raisonne en tenant compte de l’ensemble de la conversation — il se souvient que la fonction retourne None et rapproche ce symptôme du return placé dans la boucle. Le raisonnement s’applique à chaque tour, ce qui rend cet endpoint particulièrement adapté aux sessions de debugging et au tutorat itératif.

Comparaison des trois approches

Chaque endpoint a donc son terrain. Chat Completions offre un contrôle total par requête, idéal pour les pipelines automatisés où le raisonnement n’est nécessaire que ponctuellement. Les Agents se configurent une fois et s’utilisent mille fois, ce qui convient aux assistants spécialisés à niveau de raisonnement fixe. Les Conversations, elles, servent les sessions interactives avec historique : tutorat, debugging itératif, analyse progressive.

Bonnes pratiques d’intégration

Quel que soit l’endpoint, adaptez votre system prompt au raisonnement. Un modèle qui réfléchit sans consigne explore dans le désordre ; un modèle guidé suit une méthode reproductible. Décrivez donc la démarche attendue plutôt que le seul rôle :

system_prompt = """Vous êtes un expert en architecture logicielle.

Quand vous analysez un problème :
1. Identifiez d'abord les contraintes techniques
2. Énumérez les solutions possibles
3. Évaluez chaque solution selon les critères de performance, maintenabilité et coût
4. Recommandez la meilleure option avec justification
"""

Prévoyez ensuite l’échec. Le raisonnement peut produire des chunks inattendus ou l’appel échouer pour des raisons de quota ; dans les deux cas, mieux vaut une réponse dégradée qu’une exception remontée à l’utilisateur. Le repli le plus simple consiste à rejouer la requête sans réflexion :

def safe_reasoning_call(client, messages, effort="high"):
    """Appel avec raisonnement et gestion d'erreurs."""
    try:
        response = client.chat.complete(
            model="mistral-small-latest",
            messages=messages,
            reasoning_effort=effort
        )
        return response
    except Exception as e:
        # Fallback sans raisonnement
        return client.chat.complete(
            model="mistral-small-latest",
            messages=messages,
            reasoning_effort="none"
        )

Points clés à retenir

• Le raisonnement ajustable fonctionne dans trois contextes : Chat Completions, Agents, Conversations
• Dans les Agents et Conversations, utilisez le champ completion_args pour configurer le raisonnement
• Les Agents sont idéaux pour des assistants spécialisés avec un niveau de raisonnement fixe
• Les Conversations gèrent l’historique côté serveur, parfait pour les sessions itératives
• Adaptez votre system prompt pour guider la réflexion du modèle dans la bonne direction