Home
Studio

Confier l'hébergement de l'agent à Mistral : agents deploy

agents deploy déploie votre agent avec Studio, et Mistral l'héberge : les sessions persistent après les redémarrages et les longues attentes, sans que vous ayez à maintenir quoi que ce soit en cours d'exécution. Mistral construit votre projet à partir de git, l'exécute et le maintient en fonctionnement.

Vous avez besoin de :

  • un agent que agents serve peut charger, avec un name= explicite ;
  • un dépôt GitHub contenant le projet, et du connecteur GitHub connecté à votre compte dans Mistral Studio : la plateforme clone le projet via ce connecteur ;
  • une MISTRAL_API_KEY dont l'utilisateur dispose d'un rôle dans l'espace de travail donnant accès à Workflows : Developer, Developer Contributor, Workspace Contributor, Observability Viewer ou Admin. Si votre utilisateur n'a aucun de ces rôles, demandez à un administrateur de l'espace de travail de lui en attribuer un dans la console d'administration : Organisation > espaces de travail > votre espace de travail > Membres. Un agent utilisant MistralSandbox a aussi besoin du rôle cloud_user : consultez Sandbox Mistral.
Déployer l'agent

Déployer l'agent

agents deploy construit le commit que vous avez poussé, pas votre copie de travail, et utilise le Dockerfile de votre projet. Vous n'avez pas à l'écrire : le premier déploiement vous propose de le faire.

  1. Créez un commit du projet et poussez-le.

  2. Exécutez agents deploy dans le projet. Dans un projet uv sans Dockerfile, la commande propose d'en écrire un à la racine du projet, ainsi qu'un fichier .python-version défini sur 3.12 si le projet n'en contient pas. Aucun fichier n'est écrit sans votre accord, puis le déploiement s'arrête :

    /home/ada/my_agent has no Dockerfile and no .python-version. Write Dockerfile and .python-version? [Y/n]: y
Wrote Dockerfile and .python-version in /home/ada/my_agent.
Commit and push them with pyproject.toml and uv.lock, then run `agents deploy` again.

  3. Créez un commit des nouveaux fichiers et poussez-le, puis relancez le déploiement :

    git add Dockerfile .python-version pyproject.toml uv.lock && git commit -m "Add the Dockerfile"
git push
agents deploy

    Le déploiement affiche d'abord les éléments utilisés pour la construction : le dépôt, le commit, le répertoire du projet dans le dépôt, le Dockerfile et la version de mistralai-agents. Il attend ensuite que l'agent soit en cours d'exécution, puis indique le temps écoulé et où essayer l'agent :

                           Git configuration
┌───────────────────┬──────────────────────────────────────────┐
│ Repository        │ https://github.com/ada/my_agent          │
│ Revision          │ 7253dcd591793d4baaa9338970984320cd51d5c6 │
│ Working directory │ (root)                                   │
│ Dockerfile        │ Dockerfile                               │
│ Agents SDK        │ 1.1.0                                    │
└───────────────────┴──────────────────────────────────────────┘
Deploying hello-agent to managed platform...
Created agent 01a1a2bc-d73c-706d-a14e-11ba3b7235da (managed deployment: 01a1a2bc-d6a6-763c-9fdf-cbba1250ed5a).
Agent hello-agent is live after 1m24s.
  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

  4. Essayez l'agent en utilisant son nom :

    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! ☀️

Dans votre application, ouvrez des sessions avec agents.Agent.load_from(agent_name="hello-agent"), comme pour un agent lancé avec agents serve. --name remplace le name= de votre Agent et sert d'identifiant au déploiement.

Le Dockerfile généré
# Written by `agents deploy`. It is yours to edit: deploys build it as it is.
FROM ghcr.io/astral-sh/uv:0.11-debian-slim

# The worker's Temporal client reads the system CA certificates, which the base image does not ship.
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# uv installs the Python version the project asks for, so the image needs none of its own. It goes
# outside /root so that the worker's user can run it.
ENV UV_COMPILE_BYTECODE=1 \
    UV_PYTHON_INSTALL_DIR=/opt/python \
    PATH="/app/.venv/bin:$PATH"

WORKDIR /app
COPY . .
RUN uv sync --frozen --no-dev \
 && useradd --create-home --shell /usr/sbin/nologin agent \
 && chown -R agent:agent /app

# The worker does not need root.
USER agent

CMD ["agents", "run-worker"]

L'image utilise la version de Python définie dans .python-version.

Sans terminal, par exemple en CI, le déploiement n'écrit rien et s'arrête. Passez --yes pour écrire les fichiers sans demander de confirmation.

Le déploiement s'arrête si le Dockerfile ne figure pas dans le commit que vous avez poussé, car c'est ce commit que la plateforme construit. Avec le Dockerfile généré, pyproject.toml, uv.lock et .python-version doivent également y figurer.

Déploiements renforcés

Déploiements renforcés

Un agent qui agit au nom de l'utilisateur qui démarre une session, par exemple via ses connecteurs, est déployé en mode renforcé par défaut : le déploiement accepte uniquement un worker dont les identifiants sont autorisés pour ce déploiement. Aucun autre worker ne peut ainsi prendre en charge des sessions qui agissent avec l'identité d'un utilisateur. Ne passez pas --no-hardened pour un tel agent : son worker ne peut pas s'enregistrer, et le déploiement ne démarre pas. Le mode renforcé reste inchangé pendant toute la durée du déploiement : pour le modifier, exécutez agents shutdown <name> et relancez le déploiement. Consultez agents deploy.

Quand l'agent ne démarre pas

Quand l'agent ne démarre pas

Si l'agent déployé ne démarre pas, agents deploy se termine avec l'erreur de déploiement et affiche sa dernière sortie, par exemple une trace d'exception ou une dépendance manquante :

Deploy failed. Rollout failed: Service is unhealthy.

Last output from the worker:
  Traceback (most recent call last):
    ...
  ModuleNotFoundError: No module named 'my_tools'

Pour lire l'intégralité des logs, passez le nom de l'agent à agents logs. Ajoutez --follow pour continuer à afficher les nouvelles lignes :

agents logs hello-agent --follow

Consultez Cycle de vie de l'agent.

Utiliser votre propre Dockerfile

Utiliser votre propre Dockerfile

Cette option s'adresse aux projets dont les besoins dépassent le fichier généré. Le Dockerfile généré vous appartient : les déploiements suivants l'utilisent tel quel et ne le réécrivent jamais. Modifiez-le pour ajouter des paquets système ou des étapes de construction.

Pour utiliser un autre fichier pour la construction, passez son chemin relatif au projet :

agents deploy --dockerfile deploy/worker.Dockerfile

Si ce fichier n'existe pas, le déploiement s'arrête avant de créer quoi que ce soit. Le déploiement écrit un Dockerfile uniquement au chemin par défaut.

Aucun fichier n'est généré pour un projet sans pyproject.toml ou uv.lock. Écrivez votre propre Dockerfile, ou créez le projet avec uv init et uv lock.

COPY . . copie tout le contenu du contexte de construction. Ajoutez donc un .dockerignore à côté du Dockerfile :

.env
.venv/
.git/
__pycache__/
*.py[oc]
build/
dist/

La première ligne est la plus importante. Une couche d'image conserve tout ce qu'elle a copié : un fichier .env présent dans l'image est donc lisible par toute personne qui peut récupérer cette image.

Avec le Dockerfile généré, l'agent déployé utilise la version de mistralai-agents installée par le fichier uv.lock inclus dans le commit, pas la version de la CLI qui exécute agents deploy. Le déploiement affiche cette version dans la ligne Les agents SDK de son tableau et vous avertit si les deux versions diffèrent. Pour déployer avec la version verrouillée, exécutez uv run agents deploy dans le projet. Avec votre propre Dockerfile, le déploiement ne peut pas déterminer la version et l'affiche comme inconnue.

La commande du conteneur

La commande du conteneur

Le conteneur doit exécuter uniquement le worker, car agents deploy a déjà enregistré l'agent. agents run-worker remplit ce rôle :

CMD ["agents", "run-worker"]
Transmettre des secrets à l'agent déployé

Transmettre des secrets à l'agent déployé

Pour déployer un agent qui déclare des secrets, créez d'abord chaque secret dans l'espace de travail du déploiement, dans console.mistral.ai → Secrets. --secret-binding pointe vers un secret existant.

Associez ensuite chaque MistralSecret() qui ne précise pas de nom de secret :

agents deploy . --name hello-agent \
  --secret-binding EXAMPLE_TOKEN=secret:workspace:example-token

--secret-binding accepte une référence, secret:workspace:<NAME>, jamais la valeur du secret. Mistral lit le secret dans le conteneur de l'agent déployé au démarrage. La valeur n'est donc jamais saisie sur la ligne de commande, envoyée avec la requête de déploiement ou stockée avec le déploiement. Le déploiement rejette toute valeur passée à la place d'une référence.

--secret-binding accepte aussi un nom que Agent(secrets=...) ne déclare pas, par exemple une variable lue par une bibliothèque plutôt que par vos outils. L'agent déployé la récupère de la même manière depuis le secret de l'espace de travail, mais rien ne vérifie que l'agent en a besoin. Par exemple, le SDK Sentry lit SENTRY_DSN :

agents deploy . --name hello-agent \
  --secret-binding EXAMPLE_TOKEN=secret:workspace:example-token \
  --secret-binding SENTRY_DSN=secret:workspace:sentry-dsn

Chaque déploiement remplace les associations du précédent. Passez les mêmes options --secret-binding à chaque déploiement : un déploiement sans l'association d'un MistralSecret() échoue. Conservez-les dans le script ou le job CI qui exécute le déploiement.

Chaque --secret-binding est aussi transmis à la construction de l'image comme argument de construction. Un Dockerfile le lit avec un ARG correspondant.

:::warning Les arguments de construction ne sont pas un canal sécurisé Une valeur transmise à la construction reste dans l'historique et les couches de l'image. Toute personne qui peut récupérer l'image peut la retrouver. Lisez plutôt la variable à l'exécution, où elle n'est jamais écrite dans une couche. N'associez un secret lors de la construction que si vous acceptez de le renouveler. :::

Limites des sessions

Limites des sessions

Par défaut, une session déployée se termine automatiquement après 4 heures d'inactivité ou 24 heures au total. Définissez d'autres limites avec ENV dans le Dockerfile, jusqu'à 24 heures d'inactivité et une semaine au total :

ENV AGENTS_SDK_IDLE_TIMEOUT_SECONDS=3600
ENV AGENTS_SDK_LIFETIME_LIMIT_SECONDS=28800

Une limite totale d'une semaine nécessite aussi d'augmenter AGENTS_SDK_EXECUTION_TIMEOUT_SECONDS, par exemple à 608400 (une semaine et une heure) : consultez Limites des sessions.

Pour terminer une session plus tôt, annulez-la : consultez Cycle de vie des sessions.

Consulter vos sessions et vos traces

Consulter vos sessions et vos traces

Les sessions d'un agent déployé se trouvent dans Agents gérés › Sessions des agents dans Mistral Studio. Un agent déployé envoie aussi à Mistral Studio des données de télémétrie sur les tours de l'agent, les appels aux modèles et les appels aux outils, sous forme de spans OpenTelemetry. Cette télémétrie est activée par défaut, avec le contenu des prompts et des réponses, et ne nécessite aucun paquet ni paramètre supplémentaire. Cela s'applique aussi à un agent que vous exécutez avec agents serve.

Le contenu est expurgé avant de quitter le processus de l'agent, afin de masquer les secrets et les données personnelles. Ce traitement repose sur des motifs connus et peut donc manquer un secret ou des données personnelles présentés dans un autre format.

Pour enregistrer les spans sans leur contenu, ou ne pas enregistrer de spans du tout, définissez ENV dans le Dockerfile. Un déploiement géré ne lit pas l'environnement du shell qui lance la commande :

# Record spans without prompt and completion content.
ENV AGENTS_SDK_STUDIO_TRACING_INCLUDE_CONTENT=0
# Turn Studio tracing off entirely.
ENV AGENTS_SDK_STUDIO_TRACING_ENABLED=0

Une organisation qui a désactivé l'observabilité dans Mistral Studio ne reçoit aucune trace, quels que soient les paramètres de l'agent.

L'agent déployé indique aussi à Mistral le nombre de tokens utilisés par chaque appel à un modèle, sans transmettre le contenu. ENV AGENTS_SDK_TELEMETRY_ENABLED=0 désactive cet envoi.

Expurgation personnalisée

Expurgation personnalisée

Pour choisir ce que votre agent expurge, passez redaction= à l'Agent : une politique de mistralai.agents.redaction, ou une liste de politiques appliquées dans l'ordre. Elle remplace la politique par défaut :

import re

from mistralai import agents
from mistralai.agents import redaction

TICKET_ID = re.compile(r"\bACME-\d+\b")

agent = agents.Agent(
    model="mistral-large-4",
    name="support",
    redaction=redaction.RegexRedactionPolicy(
        # The default patterns, without card numbers, plus your own.
        [*redaction.DEFAULT_TOKEN_PATTERNS, redaction.EMAIL_PATTERN, redaction.IPV4_PATTERN, TICKET_ID]
    ),
)

redaction=[] désactive l'expurgation. Les politiques, ainsi que l'utilisation d'une fonction (key, value) comme politique, sont décrites dans les Références de l'Agent.

Aller plus loin

Aller plus loin