Créer un agent avec l'API Python

Votre premier agent Mistral

Les trois leçons précédentes ont posé le vocabulaire ; celle-ci passe au clavier. Vous allez créer un agent via l’API Python, l’enrichir progressivement — instructions, paramètres de génération, outils — puis lancer une conversation avec lui. La progression est volontairement incrémentale : chaque ajout modifie un comportement observable, et vous verrez pourquoi la même méthode create() peut produire un assistant générique ou un expert au style verrouillé.

Prérequis

L’installation tient en deux gestes. Le SDK officiel, d’abord.

pip install mistralai

Puis une clé API disponible dans l’environnement, plutôt qu’écrite en dur dans votre code — une clé commitée par mégarde dans un dépôt est le premier incident de sécurité de tout projet LLM.

export MISTRAL_API_KEY="votre-cle-api"

Le client se construit ensuite en une ligne, et cet objet client sert de point d’entrée à tout le reste de la leçon.

from mistralai import Mistral
import os

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

Créer un agent minimal

La méthode client.beta.agents.create() prend trois paramètres requis et plusieurs optionnels. Commençons par le strict nécessaire.

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Assistant Simple",
    description="Un agent conversationnel avec état persistant."
)

print(f"Agent créé : {agent.id}")

Cet agent est minimaliste : pas d’instructions spécifiques, pas d’outils, pas de guardrails. Il se comporte comme un Chat Completions amélioré avec la persistance. Notez l’identifiant retourné dans agent.id : c’est lui que vous stockerez côté application, car c’est la seule référence stable vers cette configuration.

Donner un comportement avec les instructions

Les instructions jouent le rôle de system prompt et constituent le levier principal du comportement. L’exemple ci-dessous transforme l’assistant générique en expert juridique dont le périmètre, le format et les limites sont explicitement bornés.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Expert Juridique",
    description="Agent spécialisé en droit français des affaires.",
    instructions="""Vous êtes un expert en droit français des affaires.

Règles :
- Répondez toujours en français
- Citez les articles de loi pertinents
- Précisez quand une question nécessite un avis d'avocat
- Structurez vos réponses avec des titres et des listes
- Ne donnez jamais de conseil juridique définitif"""
)

Observez la structure de ce prompt : un rôle en ouverture, puis des règles numérotables. Cette organisation en sections aide le modèle à hiérarchiser les contraintes. Soyez spécifique sur le rôle, le ton et les limites plutôt que d’écrire « soyez utile ». Anticipez surtout les cas limites — que doit faire l’agent si la question sort de son domaine ? La ligne sur l’avis d’avocat répond précisément à cette question. Enfin, considérez les instructions comme du code : vous les testerez et les réviserez plusieurs fois avant qu’elles ne produisent le comportement attendu.

Contrôler la génération

Les completion_args règlent le sampler, c’est-à-dire la manière dont le modèle choisit ses mots. Un agent chargé de restituer des faits n’a pas besoin de la même liberté qu’un agent de brainstorming.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Agent Précis",
    description="Agent avec paramètres de génération contrôlés.",
    instructions="Répondez de manière factuelle et concise.",
    completion_args={
        "temperature": 0.2,    # Moins de créativité, plus de précision
        "top_p": 0.9,          # Noyau de probabilité
        "max_tokens": 2048     # Limite de longueur de réponse
    }
)

• temperature — 0.0 (déterministe) à 1.0 (créatif). Pour les tâches factuelles, préférez 0.1-0.3.
• top_p — Filtrage par probabilité cumulative. 0.9 est un bon défaut.
• max_tokens — Limite stricte de tokens en sortie.

Équiper l’agent d’outils

Un agent devient réellement autonome lorsqu’il peut agir hors du texte. La configuration suivante lui donne à la fois l’accès au web et l’exécution de code : face à une question sur un tarif du jour à comparer, il ira chercher les valeurs puis les calculera, sans que vous arbitriez.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Agent Recherche",
    description="Agent avec recherche web et exécution de code.",
    instructions="Utilisez la recherche web pour les informations actuelles et le code pour les calculs.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ],
    completion_args={"temperature": 0.3, "top_p": 0.95}
)

Les outils disponibles sont : web_search, web_search_premium, code_interpreter, image_generation, document_library.

Gérer le cycle de vie des agents

Vos agents sont des ressources persistantes du côté de Mistral, et vous les administrerez comme n’importe quelle ressource : les retrouver, les modifier, les supprimer. Le listing est particulièrement utile en développement, où l’on finit vite avec des dizaines d’agents de test dont on a perdu les identifiants.

# Lister tous vos agents
agents = client.beta.agents.list()
for a in agents.data:
    print(f"{a.name} ({a.id})")

# Récupérer un agent par son ID
agent = client.beta.agents.retrieve(agent_id="ag-xxxxxxxx")

La mise à jour est partielle : seuls les champs fournis sont modifiés, les autres restent en l’état. C’est ce qui permet d’affiner des instructions en production sans redéclarer toute la configuration.

agent = client.beta.agents.update(
    agent_id=agent.id,
    instructions="Nouvelles instructions mises à jour.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}]
)

La suppression, elle, est définitive.

client.beta.agents.delete(agent_id=agent.id)

Exemple complet

Rassemblons tout dans un agent fonctionnel de bout en bout : création, conversation, lecture de la réponse. Reprenez ce script tel quel, changez le nom et les instructions, et vous aurez votre propre analyste opérationnel en quelques minutes.

from mistralai import Mistral
import os

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

# Créer l'agent
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Analyste Tech",
    description="Analyse les tendances technologiques avec des sources web.",
    instructions="""Vous êtes un analyste technologique.
- Utilisez la recherche web pour des données récentes
- Citez toujours vos sources
- Structurez vos analyses en points clés""",
    tools=[{"type": "web_search"}],
    completion_args={"temperature": 0.3}
)

# Lancer une conversation
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Quelles sont les dernières avancées en IA agentique en 2026 ?"
)

# Afficher la réponse
for entry in response.outputs:
    if hasattr(entry, "content"):
        print(entry.content)

La boucle finale mérite un instant d’attention : elle parcourt response.outputs au lieu de lire un champ unique, car un agent outillé produit plusieurs entrées — l’exécution de la recherche, puis le texte. C’est le point de vigilance de la leçon suivante.

Points clés à retenir

• client.beta.agents.create() crée un agent avec modèle, nom et description (requis)
• Les instructions définissent le comportement — c’est le levier principal
• Les completion_args contrôlent la génération (temperature, top_p, max_tokens)
• Un agent peut avoir plusieurs outils activés simultanément
• Les agents sont des configurations réutilisables — pas des instances de conversation