Créer un agent avec l'API Python

Votre premier agent Mistral

Dans cette leçon, vous allez passer à la pratique : créer un agent via l’API Python, le configurer, et lancer votre première conversation.

Prérequis

Avant de commencer, assurez-vous d’avoir :

pip install mistralai

Et une clé API Mistral configurée :

export MISTRAL_API_KEY="votre-cle-api"

Initialiser le client

from mistralai import Mistral
import os

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

Créer un agent simple

La méthode client.beta.agents.create() prend trois paramètres requis et plusieurs optionnels :

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.

Ajouter des instructions

Les instructions (system prompt) définissent le comportement de l’agent :

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

Bonnes pratiques pour les instructions

• Soyez spécifique — Définissez le rôle, le ton, les limites
• Structurez — Utilisez des sections (Rôle, Règles, Format de réponse)
• Anticipez les cas limites — Que faire si la question est hors sujet ?
• Testez itérativement — Les instructions sont le levier principal du comportement

Configurer les paramètres de completion

Les completion_args contrôlent la génération de texte :

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.

Ajouter des outils

Vous pouvez équiper votre agent d’outils intégrés :

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.

Lister et récupérer vos agents

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

Mettre à jour un agent

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

La mise à jour est partielle : seuls les champs fournis sont modifiés.

Supprimer un agent

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

Exemple complet

Voici un agent fonctionnel de bout en bout :

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)

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