Créer un agent dans Mistral Studio

Pour créer un agent dans Mistral Studio, créez une clé API dans la console Studio, générez un projet avec l’Agents SDK, décrivez l’agent en Python (modèle, instructions, outils), testez-le dans votre terminal, puis déployez-le chez Mistral ou sur vos propres serveurs.

En bref

• Mistral Studio est la plateforme d’entreprise de Mistral AI pour bâtir des agents, des workflows et des applications reliés aux données et aux outils de l’entreprise.
• Un agent se crée en code avec l’Agents SDK, le paquet Python mistralai-agents : il n’y a pas d’assistant visuel décrit dans la documentation des agents.
• Managed Agents et l’Agents SDK sont en préversion publique : l’API, le comportement et les limites peuvent changer, et une mise à jour peut demander de modifier votre code.
• Il faut uv, Python 3.12, 3.13 ou 3.14, et le droit de créer une clé API dans votre espace de travail Studio.
• Trois modes d’exécution existent : local dans votre programme, auto-hébergé avec la commande agents serve, ou géré par Mistral avec agents deploy.
• Au niveau de la plateforme, Studio se déploie dans le cloud, dans votre propre VPC, sur site ou dans une combinaison de ces environnements.
• Les tarifs propres aux agents et les quotas de déploiement des agents sont non communiqués sur les pages officielles consacrées aux agents.

Ce qu’est un agent dans Mistral Studio

Mistral Studio regroupe trois briques : l’agent enquête et agit, le workflow coordonne l’exécution et les validations, l’application donne aux salariés un moyen d’utiliser ces systèmes. Vous partez d’un modèle, par exemple Mistral Large 4 surnommé Le Chonk, et vous le reliez aux données de l’entreprise par des connecteurs et des serveurs MCP. Studio gère ensuite l’exécution et permet d’inspecter ce qui s’est passé.

Côté technique, un agent Managed Agents est un modèle associé à un harnais. Le modèle décide de l’étape suivante : répondre ou appeler un outil. Le harnais fait tourner la boucle : il appelle le modèle, exécute les outils choisis et enregistre chaque étape dans une session. La session garde chaque message, chaque appel d’outil et chaque résultat, regroupés en tours. Un tour va de votre message jusqu’à la réponse de l’agent. Un environnement optionnel, le bac à sable, permet à l’agent de lancer des commandes shell et de modifier des fichiers ; par défaut, un agent n’en a pas.

Les agents de Studio peuvent recevoir des compétences qui décrivent les procédures de l’équipe, des bacs à sable pour exécuter du code et des sous-agents pour déléguer une partie d’une tâche. Des points d’accroche, appelés hooks, ajoutent une logique personnalisée à des moments clés de l’exécution. Point utile avant la production : dans Studio, vous définissez les instructions et contrôlez le comportement de l’agent avant qu’il ne touche un utilisateur.

Si vous avez utilisé l’ancienne API Agents de Mistral, retenez que l’Agents API v1 est sur le point d’être dépréciée. Les agents se construisent avec l’Agents SDK, et un guide de migration accompagne le passage depuis l’interface client.beta.agents. Pour un usage grand public sans code, l’assistant Le Chat de Mistral reste l’outil adapté. Les équipes qui veulent un agent intégré à leurs systèmes passent par l’Agents SDK.

Les prérequis avant de commencer

Trois éléments sont nécessaires avant la première commande. Le premier est un compte Mistral sur une offre qui donne accès à l’API, avec un moyen de paiement si votre offre l’exige : c’est la condition posée par le guide de création de clé API. Le deuxième est le droit de créer une clé API dans votre espace de travail Studio. Le troisième est l’outil uv, le gestionnaire de projets Python qui lance la commande d’initialisation.

Pour une installation manuelle dans un projet existant, l’Agents SDK demande Python 3.12, 3.13 ou 3.14 dans sa version standard, et non la variante sans verrou global 3.14t. Si vous partez de zéro, la commande d’initialisation choisit Python 3.12 pour vous. Pour déployer ensuite l’agent chez Mistral, ajoutez un dépôt GitHub et un rôle d’espace de travail qui donne accès aux workflows, comme Developer ou Workspace Contributor.

Créer la clé API dans la console

Dans la console Studio, ouvrez la page API Keys et choisissez New key. Donnez un nom qui identifie l’usage de la clé, par exemple agent-support, puis fixez une date d’expiration. Choisissez enfin la portée des connecteurs : connecteurs partagés avec l’espace de travail uniquement, ou connecteurs privés et partagés. La clé complète ne s’affiche qu’une fois : copiez-la aussitôt dans un gestionnaire de mots de passe ou un coffre de secrets. Dans un terminal, enregistrez-la dans une variable : export MISTRAL_API_KEY="votre-cle". La variable dure le temps de la session du terminal.

Créer votre premier agent pas à pas

La méthode suivante reprend le parcours officiel, de la création du projet au déploiement.

1. Créez le projet avec uvx --from mistralai-agents --python 3.12 agents init hello-agent, puis entrez dans le dossier avec cd hello-agent. La commande crée pyproject.toml, main.py, un Dockerfile, un README.md et verrouille les dépendances dans uv.lock.
2. Répondez à la demande de clé : la commande ouvre la page des clés API de Studio ou accepte une clé collée, puis l’écrit dans le fichier d’environnement du projet, exclu de git. Elle propose aussi de créer un dépôt git et d’y faire un premier commit.
3. Ouvrez main.py : l’agent y est déjà défini avec le modèle mistral-large-4, un nom, des instructions et un outil d’exemple, get_weather, qui renvoie un texte fixe.
4. Réécrivez les instructions pour votre cas d’usage, par exemple instructions="Tu réponds en français aux questions des clients sur leurs commandes. Tu demandes le numéro de commande avant toute recherche.".
5. Ajoutez vos propres outils : une fonction Python, synchrone ou asynchrone, décorée par @agents.tool, avec une docstring claire et des paramètres typés. Ajoutez ensuite son nom à la liste tools=[...] de l’agent.
6. Discutez avec l’agent dans votre terminal : uv run agents chat ouvre une conversation, et uv run agents chat -m "Quel temps fait-il à Lyon ?" envoie une seule question, à condition que la variable MISTRAL_API_KEY soit exportée ou que vous ajoutiez l’option --env-file qui pointe vers le fichier d’environnement du projet. Chaque appel d’outil et son résultat s’affichent pendant le tour.
7. Poussez le projet sur GitHub avec git add --all, git commit -m "Premier agent" et git push -u origin HEAD, après avoir connecté le connecteur GitHub dans Studio.
8. Déployez avec uv run agents deploy pour un agent géré par Mistral, ou lancez uv run agents serve pour le faire tourner sur vos serveurs.

Le modèle lit le nom de l’outil, sa docstring et ses paramètres typés pour décider quand l’appeler. Dans l’exemple officiel, une question sur la pluie des trois prochains jours suffit pour que le modèle remplisse seul la ville et le nombre de jours, sous forme d’entier. Modifiez main.py, relancez la conversation, et recommencez : c’est la boucle la plus rapide tant que l’agent est en construction.

Écrire des instructions et des outils utiles

Des instructions courtes et vérifiables

Les instructions fixent le rôle, la langue, le ton et les règles de l’agent. Une bonne consigne dit ce que l’agent doit faire, ce qu’il doit refuser et quand il doit demander une information manquante. Exemple pour un agent interne : Tu aides l'équipe commerciale à préparer ses rendez-vous. Tu synthétises le compte client en cinq points, tu cites la source de chaque information et tu signales toute donnée absente. Testez chaque version avec les mêmes questions pour comparer les réponses.

Des outils qui font une seule chose

Un outil est une fonction Python ordinaire. Donnez-lui un nom explicite, une docstring d’une phrase et des paramètres typés : le modèle s’appuie sur ces trois éléments pour choisir l’outil. Si un outil a des effets de bord, comme ouvrir un ticket ou rembourser une commande, rendez-le idempotent : une fois déployé, un appel interrompu par une panne peut être relancé, et un outil à effet de bord peut alors s’exécuter deux fois. La solution officielle consiste à transmettre au service appelé une clé d’idempotence tirée de la requête, comme le numéro de commande.

Connecter l’agent à vos outils et à vos données

Un agent appelle des services externes de deux façons. Les connecteurs du catalogue Mistral agissent au nom de l’utilisateur qui lance la session. Vos propres serveurs MCP servent quand le catalogue ne propose pas le service ou quand le serveur prend un identifiant fixe, comme une clé API que vous détenez.

Pour ajouter un connecteur par son nom, passez par exemple agents.connector("github") dans la liste connectors de la définition de l’agent. Pour donner à l’agent tous les connecteurs disponibles pour l’utilisateur, utilisez agents.all_connectors(), avec l’option exclude= pour en retirer. Le connecteur doit être disponible dans l’organisation, ce que l’utilisateur ou un administrateur règle dans Studio, et connecté par l’utilisateur qui lance la session.

Si un connecteur est introuvable ou ne se charge pas, la session démarre sans lui : le modèle est prévenu et votre code reçoit un avis agents.Notice. Pour un serveur MCP distant, déclarez-le dans mcps= avec agents.RemoteMCP(url=...). Ces mécanismes rappellent les nœuds d’outils d’un agent IA dans n8n, avec une différence : tout s’écrit en Python.

Garder le contrôle avec les validations

Avant qu’un outil ne s’exécute, le tour peut demander l’autorisation : c’est une validation, ou approval. Une politique de permissions définie sur l’agent décide, outil par outil et même argument par argument, si l’appel passe, demande une réponse ou est refusé. Trois décisions existent : allow exécute l’appel sans question, ask attend la réponse de votre fonction de validation ou d’une personne, deny bloque l’appel et le modèle reçoit une erreur.

La pratique la plus sûre consiste à tout refuser par défaut, puis à autoriser les lectures et à demander une validation pour les actions sensibles. Exemple : un agent de revue de paiement lit une alerte sans demander, mais attend un analyste avant d’ouvrir un dossier. Une fois l’agent déployé, la validation survit à la fermeture de votre application et attend la réponse pendant une heure par défaut.

Choisir où l’agent s’exécute

Le mode d’exécution décide quelle machine fait tourner les sessions de l’agent : la boucle, le code des outils et les hooks. La définition de l’agent et les appels de session restent identiques dans les trois modes, ce qui permet de passer de l’un à l’autre sans réécrire l’agent.

Mode	Où tournent les outils et où vit la session	Usage conseillé
Local, dans votre programme	Les outils tournent dans votre processus, et la session reste en mémoire : elle disparaît avec le processus.	Développement, tests, scripts
Auto-hébergé	Les outils tournent dans votre processus serveur, sur votre machine ou votre cluster. La session est stockée par Mistral et survit à une panne.	Production avec des outils qui doivent rester dans votre réseau
Géré par Mistral	Les outils tournent sur l’infrastructure de Mistral. La session est stockée par Mistral et survit à une panne.	Production sans rien à héberger

En mode auto-hébergé, vous lancez un worker, un processus de longue durée qui exécute les sessions, et le code de vos outils tourne chez vous. Le plan de contrôle de Mistral stocke toujours les sessions, les répartit entre les workers et sert les appels au modèle. Les raisons officielles d’auto-héberger un déploiement sont la résidence des données, l’accès privé à des API internes et à des bases que le cloud de Mistral ne peut pas atteindre, la réutilisation de capacités de calcul existantes et la maîtrise des coûts.

En mode géré, agents deploy construit le Dockerfile du projet à partir du commit poussé, et non de votre copie de travail : il refuse les commits non poussés. Le nom de l’agent est unique dans l’espace de travail, et un déploiement sous le même nom remplace l’agent. Une fois en ligne, agents chat hello-agent discute avec l’agent déployé, agents logs hello-agent --follow affiche ses journaux, agents list liste les agents de l’espace de travail et agents shutdown hello-agent l’arrête. Dans votre application, agents.Agent.load_from(agent_name="hello-agent") charge l’agent par son nom, comme le montre la page de déploiement.

Cloud, VPC ou sur site : ce que couvre chaque option

Au niveau de la plateforme, les agents, workflows et applications de Studio se déploient dans le cloud, dans votre propre VPC, sur site ou dans une combinaison de ces environnements. Les modèles comme la plateforme peuvent tourner dans votre cloud, votre VPC ou votre environnement sur site, et vous pouvez aussi utiliser des déploiements hébergés par Mistral ou combiner les environnements. Les données sensibles et les processus construits autour peuvent rester dans votre périmètre. Studio propose aussi des déploiements hybrides entre cloud et sur site, des environnements dédiés pour isoler les charges de travail et l’auto-hébergement.

Attention à une nuance de la documentation des déploiements : auto-héberger un déploiement n’est pas la même chose que faire tourner toute la plateforme Studio dans vos locaux. Avec agents serve, seul le worker de l’agent tourne chez vous. L’installation de Studio sur site relève d’une documentation séparée, et ses conditions, prérequis et tarifs sont non communiqués sur les pages consacrées aux agents.

Les limites à connaître

• Préversion publique. Managed Agents et l’Agents SDK peuvent changer d’API, de comportement et de limites, et une mise à jour peut casser votre code. Figez la version du paquet dans votre projet.
• Création en code. La documentation des agents décrit un parcours en Python et en ligne de commande. Une interface de création d’agent sans code dans la console Studio est non communiquée sur ces pages.
• Durée des sessions. Une session déployée se termine par défaut après 24 heures au total ou après 4 heures d’inactivité. Ces limites se relèvent, jusqu’à une semaine au total pour un agent déployé chez Mistral.
• Session locale fragile. En mode local, la session vit en mémoire et disparaît si le processus s’arrête ou plante.
• Outils rejoués. Après une panne de worker, un appel d’outil en cours peut être relancé : tout outil à effet de bord doit être idempotent.
• Prérequis du déploiement géré. Il faut un dépôt GitHub, le connecteur GitHub connecté et un rôle avec accès aux workflows. Les conditions d’offre et les quotas propres aux agents déployés sont non communiqués sur les pages des agents.
• Tarifs. Aucun tarif propre aux agents n’est publié sur les pages officielles des agents : le coût d’un agent local, auto-hébergé ou géré est non communiqué.

Questions fréquentes

Faut-il savoir coder pour créer un agent dans Mistral Studio ?
Oui, pour le parcours officiel des agents : vous écrivez la définition de l’agent et ses outils en Python, puis vous utilisez la ligne de commande agents. Pour un assistant sans code, Le Chat de Mistral est l’outil grand public de Mistral AI.

Quel modèle utiliser pour un premier agent ?
Le projet généré utilise mistral-large-4, le modèle Mistral Large 4 surnommé Le Chonk. Vous pouvez changer le modèle dans la définition de l’agent, puis tester les réponses avec les mêmes questions.

L’ancienne API Agents fonctionne-t-elle toujours ?
L’Agents API v1 est sur le point d’être dépréciée, et Mistral recommande de construire les agents avec l’Agents SDK. Un guide officiel explique comment migrer le code qui utilise client.beta.agents.

Peut-on garder les données dans son propre réseau ?
Oui, à deux niveaux. Avec agents serve, les outils tournent sur vos serveurs, mais Mistral stocke toujours les sessions et sert le modèle. Pour aller plus loin, Studio peut être déployé avec ses modèles dans votre cloud, votre VPC ou sur site.

Combien coûte un agent Mistral Studio ?
Aucun tarif propre aux agents n’est publié sur les pages officielles des agents. Il faut un compte sur une offre avec accès à l’API, et le détail du coût d’un agent déployé est non communiqué.

Comment arrêter un agent déployé ?
Lancez agents shutdown suivi du nom de l’agent. Le nom est libéré et aucune session ne peut plus atteindre l’agent.

Un agent peut-il agir sans validation humaine ?
Oui, si la politique de permissions autorise l’appel avec allow. Pour les actions sensibles, choisissez ask afin qu’une personne ou votre code valide l’appel avant son exécution.

Avant de mettre votre agent en production

• Quelles actions de l’agent doivent passer par une validation humaine, et lesquelles peuvent être refusées par défaut ?
• Vos outils doivent-ils rester dans votre réseau, ce qui oriente vers agents serve, ou un déploiement géré par Mistral suffit-il ?
• Chaque outil à effet de bord est-il idempotent, avec une clé d’idempotence transmise au service appelé ?
• Vos sessions risquent-elles de dépasser 24 heures, ou de rester inactives plus de 4 heures en attendant une réponse ?
• Avez-vous figé la version de mistralai-agents pour absorber les changements de la préversion publique ?

Pour aller plus loin, comparez cette approche avec un agent IA construit dans n8n ou un agent IA pour WhatsApp Business, revoyez les bases des agents autonomes en IA, découvrez l’assistant de code Mistral Vibe et, pour des modèles hors cloud, la méthode pour faire tourner une IA en local sur PC.