Architecture de l'API Agents Mistral — Agents Mistral — Créer des IA Autonomes

Les trois objets fondamentaux

L’API Agents de Mistral repose sur trois objets qui interagissent ensemble : Agent, Conversation et Entry. La plupart des erreurs de conception rencontrées en début de projet — un agent recréé à chaque requête, un conversation_id périmé réutilisé, un parsing de réponse qui plante sur une entrée inattendue — viennent d’une confusion entre ces trois niveaux. Comprendre leur rôle et leurs relations est donc un préalable à la moindre ligne de code.

L’objet Agent

Un Agent est un ensemble de configuration qui définit le comportement du modèle. Il ne contient aucune donnée de conversation : c’est un template réutilisable, que vous créez une fois et que des milliers de conversations peuvent référencer.

La création exige au minimum un modèle, un nom et une description.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Modèle LLM à utiliser
    name="Mon Agent",                     # Identifiant lisible
    description="Agent pour l'analyse financière"  # Description orientée tâche
)

Le paramètre model désigne le modèle de chat completion qui animera l’agent, soit mistral-medium-latest, soit mistral-large-latest. Le name est un identifiant lisible qui vous sert à retrouver et à référencer l’agent : dans un projet qui en compte une vingtaine, c’est lui qui vous évite de fouiller les journaux pour savoir lequel répond aux clients. La description, elle, est orientée tâche et ne relève pas de la seule documentation interne — elle aide le modèle à comprendre le rôle qu’on attend de lui, ce qui explique la formulation « agent pour l’analyse financière » plutôt qu’un vague « agent numéro 3 ».

Le reste se configure de manière optionnelle, et c’est là que se joue la personnalité réelle de l’agent.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Agent Complet",
    description="Agent avec tous les paramètres",
    instructions="Vous êtes un expert en finance. Répondez toujours avec des sources.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ],
    completion_args={"temperature": 0.3, "top_p": 0.95},
    guardrails={"enabled": True}
)

instructions — Le system prompt de l’agent (définit sa personnalité, ses règles, son style)
tools — Liste des outils disponibles : web_search, web_search_premium, code_interpreter, image_generation, document_library, ou des fonctions custom
completion_args — Paramètres du sampler (temperature, top_p, max_tokens, etc.)
guardrails — Configurations de sécurité et de modération

Dans l’exemple ci-dessus, l’agent financier hérite d’une exigence de sourçage par ses instructions, de la capacité à vérifier un chiffre par ses outils, et d’une température basse qui limite la créativité là où l’on attend de la rigueur.

L’objet Conversation

Une Conversation est l’historique des interactions entre un utilisateur et un agent — ou entre un utilisateur et un modèle seul. Elle contient les messages, les résultats d’exécution des outils et les événements de handoff.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Analysez les tendances du marché européen de l'IA."
)

# Récupérer l'ID de conversation pour la continuer plus tard
conversation_id = response.conversation_id

Le comportement de cet objet réserve quelques surprises. La conversation est persistante : l’historique est stocké côté Mistral, sauf si vous passez store=False. Elle est indépendante de l’agent, ce qui signifie qu’une conversation peut parfaitement exister sans agent, en mode modèle direct. Elle est enfin immutable : chaque ajout retourne un nouveau conversation_id, l’ancien restant accessible. C’est ce dernier point qui surprend le plus : si vous stockez l’identifiant initial dans votre base et le réutilisez au troisième tour, vous repartirez du contexte du premier échange.

L’objet Entry

Une Entry est une action individuelle dans une conversation : l’unité atomique de l’historique. Quand vous recevez une réponse, le champ outputs contient une liste d’entries dont le type dépend de ce que l’agent a fait. Une entrée message.output porte une réponse textuelle de l’agent, c’est-à-dire le texte que votre interface affichera. Une entrée tool.execution porte le résultat d’exécution d’un outil, code ou recherche web par exemple : le script lancé et sa sortie, ou les pages remontées par le moteur. Une entrée agent.handoff signale un événement de transfert vers un autre agent, et n’apparaît donc que dans les scénarios multi-agents.

Une même réponse mélange couramment ces types. Demandez un calcul à un agent outillé et vous recevrez l’exécution, puis le commentaire qui l’accompagne : votre code doit donc parcourir cette liste plutôt que lire un champ unique.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Calcule la racine carrée de 144"
)

for entry in response.outputs:
    print(f"Type: {entry.type}")
    if entry.type == "message.output":
        print(f"Message: {entry.content}")
    elif entry.type == "tool.execution":
        print(f"Outil: {entry.tool_name}")

Relations entre les objets

Le schéma suivant résume l’articulation des trois niveaux : une configuration réutilisable, un fil d’historique, des actions unitaires.

Agent (configuration)
  ├── model, instructions, tools, guardrails
  └── Peut être référencé par N conversations

Conversation (historique)
  ├── Liée à 0 ou 1 Agent (optionnel)
  ├── Contient N entries ordonnées
  └── Chaque append crée un nouveau conversation_id

Entry (action unitaire)
  ├── message.output (réponse texte)
  ├── tool.execution (résultat d'outil)
  └── agent.handoff (transfert d'agent)

Options de conversation

Le démarrage d’une conversation accepte des réglages qui engagent votre conformité autant que votre architecture, et qu’il vaut mieux décider que subir. Le stockage d’abord : store=False empêche toute sauvegarde côté Mistral, ce que vous utiliserez pour traiter des données que votre politique interne interdit de laisser sur un serveur tiers.

# Désactiver le stockage cloud
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Question sensible",
    store=False
)

Le second réglage définit qui exécute les handoffs. En mode server, valeur par défaut, Mistral enchaîne les transferts d’agents sans que vous interveniez ; en mode client, vous recevez les événements de handoff et gardez la main pour les journaliser, les filtrer ou les refuser.

# Mode serveur (défaut) — Mistral gère les handoffs automatiquement
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Requête complexe",
    handoff_execution="server"
)

# Mode client — Vous recevez les événements de handoff et décidez quoi faire
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Requête complexe",
    handoff_execution="client"
)

Points clés à retenir

Agent = configuration réutilisable (modèle, instructions, outils, guardrails)
Conversation = historique persistant côté serveur, indépendant de l’agent
Entry = action unitaire (message, exécution d’outil, handoff)
Les conversations peuvent exister sans agent (mode modèle direct)
Chaque ajout à une conversation crée un nouveau conversation_id
Le mode store=False empêche le stockage côté Mistral