Références de la CLI

La commande agents crée un projet d'agent, exécute l'agent sur votre machine, le déploie sur Mistral et permet de lui parler depuis le terminal. Les guides présentent l'utilisation de chaque commande : Guide de démarrage, Auto-hébergés (agents serve), Gérés par Mistral (agents deploy) et Cycle de vie d'un agent.

La commande agents est fournie avec le package mistralai-agents : consultez Installer sans agents init.

Commandes

Je souhaite	Commande
Créer un projet prêt à être déployé	`agents init NAME`
Voir ce que la CLI charge depuis mon projet	`agents info [PATH]`
Exécuter l'agent sur ma machine en auto-hébergement	`agents serve [PATH]`
Déployer l'agent avec une gestion par Mistral	`agents deploy [PATH]`
Voir les agents de mon espace de travail	`agents list`
Lire les logs d'un agent déployé	`agents logs NAME`
Parler à un agent	`agents chat [NAME]`
Arrêter définitivement un agent	`agents shutdown NAME`
Installer un skill pour mon agent de codage	`agents skills add NAME`

Un projet passe par quatre étapes :

agents init my-agent le crée.
agents info affiche ce que la CLI charge depuis le projet.
agents serve l'exécute sur votre machine, et agents chat my-agent permet de lui parler.
agents deploy le déploie sur Mistral.

agents info, agents serve et agents deploy prennent comme argument la racine du projet, . par défaut. Les commandes y recherchent agent dans main.py, ou le module:attr défini dans pyproject.toml :

[tool.mistralai.agents]
entrypoint = "src.service:support_agent"

[tool.mistralai.agents]
entrypoint = "src.service:support_agent"

L'agent doit définir name=. Consultez Auto-hébergés (agents serve).

Options globales

agents [OPTIONS] COMMAND [ARGS]...

agents [OPTIONS] COMMAND [ARGS]...

Option	Fonction
`--version`	Affiche la version installée, par exemple `mistralai-agents 1.1.0`, puis se termine.
`--install-completion`	Installe l'autocomplétion pour le shell actuel.
`--show-completion`	Affiche le script d'autocomplétion du shell actuel pour vous permettre de le copier ou de le personnaliser.
`--help`	Affiche l'aide, puis se termine. Chaque commande accepte aussi cette option.

Sans commande, agents affiche l'aide, puis se termine avec le code de sortie 2.

agents init

agents init [OPTIONS] [NAME]

agents init [OPTIONS] [NAME]

Crée un projet d'agent dans un dossier nommé NAME, prêt pour agents deploy. La commande verrouille les dépendances du projet avec uv, puis vous demande votre clé API et l'enregistre dans .env.

Argument ou option	Fonction
`NAME`	Le nom de l'agent et du dossier du projet.
`--name NAME`	Même fonction, sous forme d'option. Fournir deux noms différents provoque une erreur.
`--yes`, `-y`	Installe uv s'il est absent, ne demande pas de clé API, crée un fichier `.env` vide et crée un commit du projet dans un nouveau dépôt git. Si vous n'avez pas fourni de nom, la commande le demande tout de même lorsqu'un terminal est disponible.
`--no-git`	Ne crée pas de dépôt git.
`--exempt-from-exclude-newer`	Exempte le SDK de la date limite uv `exclude-newer`, qui pourrait masquer une version récente.

Sans nom ni terminal permettant de le demander, la commande s'arrête avec le message No agent name was given. Run `agents init NAME`. Pour en savoir plus, consultez Guide de démarrage.

agents info

agents info [PATH]

agents info [PATH]

Affiche l'agent que la CLI charge depuis le projet situé à PATH : son modèle, ses instructions, ses outils, connecteurs, MCP, skills, mécanismes de contrôle, hooks, sous-agents et autorisations. Pour un fichier main.py contenant un seul outil :

Output

pr-reviewer mistral-large-4

instructions You review pull requests.

sandbox none

tools

client.search

connectors (none)

mcps (none)

skills (none)

guardrails (none)

hooks (none)

subagents (none)

subagent policy (none)

permissions auto · no policy

Lorsque les vérifications détectent des problèmes, la commande les liste sous checks : ✗ pour une erreur, ⚠ pour un avertissement. Elle indique le premier élément qu'elle n'a pas pu charger et se termine avec le code de sortie 1 si elle ne trouve aucun agent ou si une vérification détecte une erreur. Pour en savoir plus, consultez Auto-hébergés (agents serve).

agents serve

agents serve [OPTIONS] [PATH]

agents serve [OPTIONS] [PATH]

Exécute l'agent sur votre machine, l'enregistre dans votre espace de travail et affiche un lien pour le déclencher. Ctrl+C l'arrête.

Argument ou option	Fonction
`PATH`	La racine du projet. Par défaut : `.`.
`--name NAME`	Enregistre l'agent sous ce nom plutôt que celui défini dans son code.
`--send-config` / `--no-send-config`	Envoie la configuration de l'agent à Mistral, comme le fait `agents deploy`, pour qu'elle s'affiche avec l'agent et ses sessions dans votre espace de travail. Un redémarrage avec la même configuration et la même version du code n'enregistre pas de nouvelle copie. Par défaut : `--send-config` ; `--no-send-config` enregistre l'agent sans sa configuration. Variable d'environnement : `AGENTS_SDK_SERVE_SEND_CONFIG`.

La commande affiche uniquement les avertissements et la bannière ; AGENTS_SDK_DEBUG=1 affiche les logs complets. Pour en savoir plus, consultez Auto-hébergés (agents serve).

agents deploy

agents deploy [OPTIONS] [PATH]

agents deploy [OPTIONS] [PATH]

Construit une image à partir du projet et la déploie sur Mistral, dans votre espace de travail. Un nouveau déploiement sous un nom existant remplace l'agent qui porte ce nom.

Argument ou option	Fonction
`PATH`	La racine du projet. Par défaut : `.`.
`--name NAME`	Déploie l'agent sous ce nom plutôt que celui défini dans son code.
`--hardened` / `--no-hardened`	Renforce la sécurité du déploiement pour que l'agent puisse utiliser des connecteurs et des MCP au nom de l'utilisateur qui a démarré la session. Par défaut : sécurité renforcée lorsque l'agent agit au nom de l'utilisateur de la session. Cette protection est nécessaire pour un tel agent : avec `--no-hardened`, son déploiement ne démarre pas.
`--dockerfile PATH`	Le Dockerfile à utiliser pour la construction, avec un chemin relatif au projet. Par défaut : `Dockerfile`.
`--secret-binding ENV_VAR=secret:workspace:NAME`	Lie un secret de l'espace de travail à une variable d'environnement de l'agent déployé. Fournissez la référence, jamais la valeur du secret. Répétez l'option pour chaque variable. Ces options définissent l'ensemble des liaisons : un déploiement sans cette option supprime les liaisons aux secrets établies par un déploiement précédent.
`--yes`, `-y`	Crée les fichiers `Dockerfile` et `.python-version` manquants sans demander de confirmation.

Ctrl+C pendant l'attente du déploiement arrête l'attente, pas le déploiement : le déploiement de l'agent se poursuit, et agents deploy se termine avec le code de sortie 130. Pour en savoir plus, consultez Gérés par Mistral (agents deploy) : utilisation de votre propre Dockerfile, secrets et traçage.

agents list

agents list

agents list

Liste les agents de votre espace de travail, leur mode d'exécution et leur état d'exécution. Cette commande n'accepte aucune option.

Output

NAME KIND STATUS

hello-agent deployed running

draft-agent served not observed

not observed signifie que Mistral n'a observé aucune exécution de l'agent : il est arrêté, ou son état n'a pas pu être lu. Pour en savoir plus, consultez Cycle de vie d'un agent.

agents logs

agents logs [OPTIONS] NAME

agents logs [OPTIONS] NAME

Affiche les dernières lignes des logs d'un agent déployé. Les logs d'un agent exécuté localement se trouvent dans le terminal qui exécute agents serve.

Argument ou option	Fonction
`NAME`	L'agent déployé. Obligatoire.
`--follow`, `-f`	Affiche les nouvelles lignes au fur et à mesure de leur écriture.
`--lines N`, `-n N`	Le nombre de dernières lignes à afficher au départ, de 1 à 1000. Par défaut : 100.
`--timestamps`, `-t`	Ajoute l'horodatage au début de chaque ligne.
`--level LEVEL`, `-l LEVEL`	Affiche uniquement les lignes de ce niveau ou d'un niveau supérieur : `debug`, `info`, `warning` ou `error`. Les lignes indentées sous une ligne conservée, comme une trace d'erreur, sont également conservées.
`--json`	Affiche un objet JSON par ligne, avec `time`, `stream`, `level`, `logger`, `message` et `fields`.

Pour en savoir plus, consultez Cycle de vie d'un agent.

agents chat

agents chat [OPTIONS] [NAME]

agents chat [OPTIONS] [NAME]

Permet de parler à un agent depuis le terminal. Avec NAME, la commande contacte l'agent de ce nom, qu'il soit auto-hébergé ou géré par Mistral. Sans cet argument, elle exécute l'agent du projet dans ce processus, sans rien enregistrer.

Argument ou option	Fonction
`NAME`	L'agent auquel parler, auto-hébergé ou géré par Mistral. Omettez cet argument pour exécuter l'agent du projet dans ce processus.
`--path PATH`	La racine du projet, lorsque vous omettez `NAME`. Par défaut : `.`.
`--message TEXT`, `-m TEXT`	Envoie ce seul message, affiche la réponse, puis se termine. Le code de sortie est 1 si le tour de conversation n'est pas allé à son terme.

Pendant un tour de conversation, Ctrl+C l'interrompt et laisse la conversation ouverte. À l'invite de commande, Ctrl+C, Ctrl+D, /exit ou /quit met fin à la conversation. Avec permission_mode="ask", la conversation demande une autorisation avant chaque appel d'outil : y l'autorise une fois, a l'autorise pour le reste de la session, n le refuse. L'approbation d'un hook propose uniquement y et n. agents chat refuse immédiatement tout appel d'outil côté client, et le tour de conversation se poursuit. Pour en savoir plus, consultez Cycle de vie d'un agent.

agents shutdown

agents shutdown [OPTIONS] NAME

agents shutdown [OPTIONS] NAME

Arrête définitivement un agent. NAME est le nom sous lequel l'agent est déployé, éventuellement modifié par --name.

Argument ou option	Fonction
`NAME`	L'agent à arrêter. Obligatoire.
`--yes`, `-y`	Ignore la demande de confirmation.

Pour en savoir plus, consultez Cycle de vie d'un agent.

agents skills add

agents skills add NAME

agents skills add NAME

Installe un skill livré par le SDK dans .agents/skills/ du dossier courant, pour votre agent de codage : exécutez la commande à la racine de votre projet. migrate-1.1 migre un projet d'une version candidate 1.1 vers 1.1. Une nouvelle exécution remplace les fichiers installés par ceux du SDK installé. migrate-1.1 migre également un projet depuis Agents SDK 1.0.7.

Argument	Fonction
`NAME`	Le skill à installer : `migrate-1.1`.

uvx --python 3.12 --from mistralai-agents agents skills add migrate-1.1

uvx --python 3.12 --from mistralai-agents agents skills add migrate-1.1

--python 3.12 empêche uvx d'utiliser Python 3.14t sans GIL, avec lequel l'installation échoue.

Codes de sortie

Code	Signification
0	Réussite, ou Ctrl+C pendant `agents serve` ou `agents logs --follow`.
1	La commande a échoué et en a affiché la raison. `agents chat` se termine aussi avec le code 1 en cas de perte de connexion à la session.
2	Une erreur d'utilisation : option inconnue, argument manquant ou valeur hors limites.
130	`agents deploy` a cessé d'attendre après Ctrl+C ; le déploiement se poursuit en arrière-plan.

Environnement

Variable	Lue par	Ce qu'elle définit
`MISTRAL_API_KEY`	chaque commande qui appelle l'API	Votre clé API.
`MISTRAL_API_URL`	chaque commande qui appelle l'API	La racine de l'API, sans `/v1`.
`AGENTS_SDK_SERVE_SEND_CONFIG`	`agents serve`	La valeur par défaut de `--send-config`.
`AGENTS_SDK_CODE_VERSION`	`agents serve`	La version du code : un redémarrage avec la même valeur conserve l'agent. Par défaut : une empreinte du projet. Consultez Cycle de vie d'un agent.
`AGENTS_SDK_DEBUG`	chaque commande et tout programme qui importe le SDK	`1` affiche les logs complets.

Exportez les variables dans votre shell ou chargez .env avec uv run --env-file .env agents ... ; une variable exportée par votre shell est prioritaire sur celle du fichier.

Et après

L'API complète : tous les appels Python, classés selon ce que vous souhaitez faire.