Le raisonnement dans les agents et les conversations

Leçon réécrite le 2 novembre 2026 pour Mistral Small 4 et Large 4. La documentation Mistral précise que reasoning_effort est disponible sur les endpoints Agents et Conversations, dans le champ completion_args. Sources : Reasoning · SDK Python — Conversations.

Trois façons d’appeler un modèle qui raisonne

Les leçons précédentes utilisaient l’API Chat Completions : vous envoyez l’historique complet à chaque appel, et reasoning_effort se passe directement dans la requête. Mistral propose deux autres interfaces, l’API Agents, qui enregistre une configuration réutilisable (modèle, instructions, outils, paramètres), et l’API Conversations, qui conserve l’historique côté serveur. Dans ces deux API, le réglage du raisonnement ne se passe pas à plat : il se range dans completion_args, avec les autres paramètres de génération.

Un agent qui raisonne

Fixer le niveau de raisonnement dans l’agent évite de le répéter à chaque appel et garantit que toute l’équipe utilise le même réglage :

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agent = client.beta.agents.create(
    model="mistral-small-2603",
    name="Analyste financier",
    instructions=(
        "Tu analyses des situations financières de PME. "
        "Termine chaque réponse par une recommandation chiffrée et ses hypothèses."
    ),
    completion_args={"reasoning_effort": "high"},
)

reponse = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Notre BFR a doublé en un an alors que le chiffre d'affaires a crû de 15 %. Que faut-il regarder en premier ?",
)

Lire les sorties d’une conversation

Une conversation ne renvoie pas choices mais une liste d’entrées (outputs). La réponse du modèle se trouve dans les entrées de type message.output, dont le contenu est, comme en Chat Completions, soit une chaîne, soit une liste de fragments pouvant contenir un ThinkChunk. La fonction separer de la leçon 3 s’applique donc telle quelle :

for entry in reponse.outputs:
    if entry.type == "message.output":
        reflexion, texte = separer(entry.content)
        print(texte)

Les autres entrées décrivent ce qui s’est passé pendant le tour, par exemple l’exécution d’un outil (tool.execution) ou un appel de fonction : ignorez-les si seule la réponse vous intéresse.

Une conversation sans agent

Pour un usage ponctuel, l’API Conversations accepte directement un modèle, sans agent préalable. L’historique est conservé côté serveur et vous poursuivez l’échange avec conversations.append, en ajustant au besoin le niveau de raisonnement pour un tour donné :

conv = client.beta.conversations.start(
    model="mistral-large-4-0",
    inputs="Propose un plan de migration d'une base PostgreSQL de 2 To sans interruption de service.",
    completion_args={"reasoning_effort": "high"},
)

suite = client.beta.conversations.append(
    conversation_id=conv.conversation_id,
    inputs="Résume ce plan en cinq étapes pour la direction.",
    completion_args={"reasoning_effort": "low"},   # un résumé n'a pas besoin d'une longue réflexion
)

C’est un avantage concret sur Chat Completions, où la documentation demande de rejouer le message complet de l’assistant, réflexion comprise, à chaque nouveau tour (leçon 7). Avec l’API Conversations, l’historique est conservé côté serveur : vous ne le renvoyez pas à chaque appel.

Raisonnement et outils

Un agent peut combiner raisonnement et outils : tools et completion_args sont deux champs indépendants de la création d’agent. Un agent d’analyse peut ainsi disposer de la recherche web et d’un raisonnement poussé :

agent_veille = client.beta.agents.create(
    model="mistral-small-2603",
    name="Veille concurrentielle",
    instructions="Tu compares des offres concurrentes à partir de sources publiques citées.",
    tools=[{"type": "web_search"}],
    completion_args={"reasoning_effort": "high"},
)

Mesurez cependant le coût de ces agents : réflexion et appels d’outils s’additionnent dans la facture d’un tour.

Comparaison des trois approches

Bonnes pratiques d’intégration

Fixez le niveau de raisonnement dans l’agent quand la tâche est homogène, et au tour quand elle varie : un premier tour d’analyse en high, des tours de reformulation en low ou none selon le modèle. Vérifiez que la valeur convient au modèle de l’agent : Small 4 accepte high et none, Large 4 low, medium et high. Enfin, journalisez l’usage en tokens de chaque tour : c’est la seule manière de savoir si le raisonnement paie sur votre cas.

Points clés à retenir

• Dans les API Agents et Conversations, reasoning_effort se passe dans completion_args
• Les réponses arrivent dans outputs ; le texte est dans les entrées message.output, réflexion comprise
• L’API Conversations conserve l’historique côté serveur : pas besoin de le renvoyer à chaque tour
• Le niveau peut changer à chaque tour avec conversations.append
• Un agent peut combiner outils intégrés et raisonnement, au prix d’un coût cumulé