Home
Studio

Déployer sur votre propre infrastructure : agents serve

agents serve déploie votre agent avec Studio, sur une infrastructure que vous hébergez. Cette commande démarre un processus de longue durée, le worker, sur votre machine ou dans votre cluster, qui exécute les sessions de l'agent. Mistral conserve chaque session pour que le travail ne soit pas perdu en cas de plantage. Votre application ouvre les sessions à partir du nom de l'agent. Les outils de l'agent s'exécutent sur une infrastructure que vous contrôlez. Utilisez cette commande pour exécuter l'agent en production sur votre propre infrastructure, ou pour tester le fonctionnement d'un déploiement.

Fonctionnement

Fonctionnement

  1. Votre application, ou agents chat, démarre une session à partir du nom de l'agent. Mistral conserve la session et place son tour dans la file d'attente.
  2. Votre worker interroge cette file d'attente et prend en charge le tour.
  3. Le worker exécute la boucle de l'agent et les outils sur votre machine, appelle le modèle et enregistre chaque étape terminée auprès de Mistral. Si un worker s'arrête, aucune étape terminée n'est perdue.

Vous devez disposer d'un projet contenant un Agent qui définit name=, ainsi que d'une clé MISTRAL_API_KEY dont l'utilisateur possède un rôle dans l'espace de travail donnant accès à Workflows, comme Développeur ou Contributeur de l'espace de travail ; un administrateur de l'espace de travail attribue ce rôle dans la console d'administration : Organisation > espaces de travail > votre espace de travail > Membres, comme l'explique agents deploy.

Ce que charge la CLI

Ce que charge la CLI

agents info, agents serve et agents deploy ont tous besoin du même élément : l'objet Agent que vous avez créé en Python. Par défaut, ces commandes recherchent agent dans main.py. Un projet constitué d'un seul fichier main.py s'exécute donc tel quel :

from mistralai import agents


@agents.tool
async def get_weather(city: str) -> str:
    """Get the current weather in a city."""
    return f"It is 18°C and sunny in {city}."


agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Greet the user in one sentence.",
    tools=[get_weather],
)

La CLI importe main.py : le code placé au niveau supérieur de ce fichier s'exécute donc au chargement. Placez le code qui exécute l'agent depuis un script, comme asyncio.run(main()), sous if __name__ == "__main__":.

Pour placer l'agent ailleurs, déclarez-le dans pyproject.toml sous la forme module:attr : le module qui le définit, puis la variable qui le contient :

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

Lors de l'import du module, la racine du projet figure dans le chemin de recherche des imports. Un module placé à la racine fonctionne donc sans que le projet soit un package installable. Chaque commande accepte une racine de projet comme argument : agents serve ./hello-agent exécute ainsi un projet même si vous n'êtes pas dans son répertoire.

L'agent doit avoir un nom

L'agent doit avoir un nom

Agent(...) doit définir explicitement name=. C'est le nom que agents serve enregistre et que agents deploy utilise pour le routage. La CLI refuse donc de le déduire :

main:agent must set an explicit name: `agents.Agent(model=..., name=...)`. The name is the deployed workflow name. Set it in code even when you pass `--name`.

Le nom est unique par espace de travail, et non globalement : exécuter à nouveau agents serve ou agents deploy pour hello-agent depuis le même espace de travail met à jour ce même agent. En revanche, hello-agent dans un autre espace de travail est un agent distinct. Si deux personnes exécutent agents serve pour hello-agent dans un même espace de travail, elles partagent donc un agent : chaque session est confiée à l'un ou l'autre processus et exécute le code de la personne qui l'a lancé. Pendant le développement, attribuez un nom distinct à chaque personne, par exemple agents serve --name hello-agent-ada.

Un nom contenant un point, comme acme.bot, est réservé aux agents de la plateforme : Agent(...) lève alors une exception agents.SdkError.

Démarrer le worker de l'agent

Démarrer le worker de l'agent

Depuis le dossier du projet :

export MISTRAL_API_KEY="<your-key>"
agents serve                              # the project in the current directory
agents serve ./hello-agent --name hello-agent

agents serve exécute un worker, enregistre l'agent sous son nom et indique où le tester :

✓ Agent hello-agent is serving on agents-sdk-hello-agent

  Try the agent:
  • in Vibe Code Web:          https://chat.mistral.ai/code?agent=hello-agent
  • programmatically, using the Session API: /studio/agents/learn/sessions/sessions

  Debug:  https://console.mistral.ai/build/workflows?workflowSearch=hello-agent

Press Ctrl+C to stop.

--name remplace la valeur name= de l'agent, qui sert aussi au routage des sessions. Dans votre application, ouvrez les sessions de l'agent à partir de ce nom :

from mistralai import agents

agent = agents.Agent.load_from(agent_name="hello-agent")

Si vous arrêtez agents serve, l'agent cesse de répondre, mais Mistral conserve les sessions. Un tour en cours reprend généralement à partir de sa dernière étape terminée lorsque agents serve redémarre. Le SDK ne relance pas un appel d'outil qui était en cours, mais le modèle peut appeler à nouveau cet outil. Assurez-vous donc que les outils sont idempotents : voir Durabilité.

:::warning Les outils s'exécutent sur la machine qui exécute agents serve Chaque session de cet agent, qu'elle provienne de Vibe Code Web ou de l'API Session, exécute ses outils sur cette machine. Pour isoler ce que l'agent exécute, attribuez-lui une sandbox. :::

Testez l'agent à partir de son nom, depuis un autre terminal :

agents chat hello-agent
Talking to hello-agent (session 01a1a89e-c09f-7043-85a7-af2170ff112d). Ctrl+D or /exit to quit.
> What is the weather in Paris?
→ get_weather {"city": "Paris"}
← get_weather done
It's currently **18°C and sunny** in Paris! ☀️
Vérifier les éléments chargés

Vérifier les éléments chargés

agents info affiche ce que la CLI a chargé et indique le premier élément qu'elle n'a pas pu charger. Pour le fichier main.py ci-dessus :

hello-agent  mistral-large-4

  instructions     You are a friendly agent. Greet the user in one sentence.
  sandbox          none

  tools
    client.get_weather

  connectors       (none)
  mcps             (none)
  skills           (none)
  guardrails       (none)
  hooks            (none)
  subagents        (none)
  subagent policy  (none)
  permissions      auto · no policy

Exécutez cette commande après avoir modifié les outils, les connecteurs ou les hooks de l'agent. Un outil qui n'apparaît pas ici n'est pas non plus visible pour le modèle. Consultez agents info pour connaître ses options.

Configurer l'environnement

Configurer l'environnement

Pour utiliser le service de production, agents serve n'a besoin que de MISTRAL_API_KEY. Pour cibler un autre déploiement, définissez à la fois MISTRAL_API_URL et AGENTS_SDK_DEPLOY_CONTROL_PLANE_URL : voir Environnement.

Par défaut, une session auto-hébergée se termine après 4 heures d'inactivité ou après 24 heures au total. Modifiez ces limites avec AGENTS_SDK_IDLE_TIMEOUT_SECONDS et AGENTS_SDK_LIFETIME_LIMIT_SECONDS, en secondes, jusqu'à un an pour chacune : voir Limites des sessions.

Par défaut, agents serve envoie les traces de ses tours à Mistral Studio : voir Consulter vos sessions et vos traces, ainsi que Masquage personnalisé pour choisir ce que les traces masquent.

Code réexécuté

Code réexécuté

Après le déploiement, la boucle de l'agent est réexécutée chaque fois qu'un worker reprend un tour, par exemple après un redémarrage. Pour lire l'heure, attendre ou générer des identifiants et des nombres aléatoires, utilisez agents.now(), agents.sleep(), agents.uuid4() et agents.random() : ces fonctions renvoient le même résultat lors de la réexécution. Les outils et les hooks= de l'agent s'exécutent hors de la boucle, sous forme d'étapes enregistrées. Ces quatre fonctions y fonctionnent aussi. Un hook de sandbox et une politique de masquage s'exécutent dans la boucle : utilisez-y ces quatre fonctions.

Problèmes courants

Problèmes courants

agents serve n'affiche que les avertissements et la bannière. Définissez AGENTS_SDK_DEBUG=1 pour obtenir le log complet, qui indique l'API Workflows résolue. LOG_LEVEL n'a aucun effet ici.

  • Cannot serve agent: MISTRAL_API_KEY was refused (HTTP 401). La ligne suivante indique agents serve needs a credential allowed to run agent workers in this workspace; check MISTRAL_API_KEY. La clé est incorrecte, expirée ou révoquée : vérifiez-la ou créez-en une nouvelle.
  • Cannot serve agent: registration failed at https://api.mistral.ai/v2/agents: <detail>. Aucune session n'atteint l'agent tant que son nom ne pointe pas vers votre processus agents serve. <detail> indique la cause :
    • the name hello-agent is already bound to another workflow or deployment. Voir Libérer un nom.
    • Autres causes : une API d'agents non activée pour le compte, ou une URL de console de pilotage qui ne se termine pas par /v2/agents, ce qui provoque une erreur 404 Not Found.
  • The user associated with this worker credential does not have permission to use Workflows in this workspace. Demandez à un administrateur de l'espace de travail d'attribuer à l'utilisateur associé à la clé un rôle donnant accès à Workflows, comme Développeur ou Contributeur de l'espace de travail, dans la console d'administration : Organisation > espaces de travail > votre espace de travail > Membres. Relancez ensuite le worker.
  • MISTRAL_API_KEY is not set. Exportez cette variable dans votre shell, ou placez-la dans .env et exécutez uv run --env-file .env agents serve : la CLI ne lit pas elle-même .env.
Et après

Et après