Intégration dans les Agents et Conversations — Raisonnement IA — Magistral et Mistral Small 4

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 offre des possibilités d’intégration distinctes.

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 :

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.

Raisonnement dans les Agents

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

# 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 ?"}
    ]
)

Avantages de l’approche Agent

Le raisonnement est configuré une seule fois à la création de l’agent
Pas besoin de repasser reasoning_effort à chaque requête
Les instructions système guident le raisonnement dans une direction spécifique
Idéal pour les assistants spécialisés (analyste, debugger, tuteur)

Pattern : Agent avec raisonnement conditionnel

Vous pouvez créer plusieurs agents avec des niveaux de raisonnement différents et router les requêtes selon leur complexité :

# 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 :

# 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"}
    ]
)

Avantages des Conversations

L’historique est géré côté serveur, pas besoin de renvoyer tout le contexte
Le raisonnement s’applique à chaque tour de la conversation
Le modèle peut raisonner en tenant compte de l’ensemble de la conversation
Idéal pour les sessions de debugging ou de tutorat itératif

Comparaison des trois approches

Chaque endpoint a ses cas d’usage privilégiés :

Chat Completions : contrôle total par requête, idéal pour les pipelines automatisés où le raisonnement n’est nécessaire que ponctuellement
Agents : configuration une fois, utilisation multiple. Parfait pour les assistants spécialisés avec un niveau de raisonnement fixe
Conversations : sessions interactives avec historique. Idéal pour le tutorat, le debugging itératif, et l’analyse progressive

Bonnes pratiques d’intégration

1. System prompt adapté au raisonnement

Quand le raisonnement est actif, adaptez vos instructions système pour guider la réflexion :

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
"""

2. Gestion des erreurs

Le raisonnement peut échouer ou produire des chunks inattendus. Prévoyez une gestion robuste :

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