Architecture de l'API Agents Mistral

Les trois objets fondamentaux

L’API Agents de Mistral repose sur trois objets qui interagissent ensemble : Agent, Conversation et Entry. Comprendre leur rôle et leurs relations est essentiel avant d’écrire 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 pas de données de conversation — c’est un template réutilisable.

Paramètres requis

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
)

• model — Le modèle de chat completion (mistral-medium-latest ou mistral-large-latest)
• name — Un identifiant pour retrouver et référencer l’agent
• description — Une description orientée tâche (aide le modèle à comprendre son rôle)

Paramètres optionnels

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

L’objet Conversation

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

Démarrer une conversation

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

Caractéristiques clés

• Persistante — L’historique est stocké côté Mistral (sauf si store=False)
• Indépendante de l’agent — Une conversation peut exister sans agent (mode modèle direct)
• Immutable — Chaque ajout retourne un nouveau conversation_id (l’ancien reste accessible)

L’objet Entry

Une Entry est une action individuelle dans une conversation. C’est l’unité atomique de l’historique.

Types d’entries

Quand vous recevez une réponse, le champ outputs contient une liste d’entries :

• message.output — Réponse textuelle de l’agent
• tool.execution — Résultat d’exécution d’un outil (code, recherche web, etc.)
• agent.handoff — Événement de transfert vers un autre agent

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

Voici comment les trois objets interagissent :

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

Stockage

# Désactiver le stockage cloud
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Question sensible",
    store=False  # Rien n'est sauvegardé côté Mistral
)

Mode d’exécution des handoffs

# 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