Guardrails for Mistral Agents
Tällä sivulla
- Sécuriser les agents autonomes
- Guardrails sur une conversation
- Guardrails sur un agent
- Gérer les blocages dans un échange en plusieurs tours
- Agents avec outils : ce que les guardrails ne voient pas
- Architecture recommandée pour les agents en production
- Chat Completions, Conversation ou Agent : résumé
- Keskeiset asiat
Leçon réécrite le 3 novembre 2026. La version précédente s’appuyait sur un format de guardrail fictif (
enabled, catégorieshate,violence,unpredictable), une méthodeconversation.send()inexistante et affirmait à tort que les guardrails modèrent les arguments des outils. Selon la documentation, ils modèrent uniquement l’entrée. Le code suit désormais la véritable API Conversations (start,append) et a été vérifié avec les types du SDKmistralaiversion 3.7.0. Sources : Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Sécuriser les agents autonomes
Un agent présente plus de risques qu’un simple chatbot : il appelle des outils, navigue sur le web et enchaîne les actions. Les guardrails ne couvrent qu’une partie de cette surface d’attaque, spécifiquement l’entrée. C’est exactement pour cela que tu dois savoir précisément où les placer et ce qu’ils laissent sans protection.
Dans cette leçon, tu vas attacher des guardrails à une conversation, puis à un agent, gérer leurs blocages lors d’un échange en plusieurs tours et voir ce que tu dois ajouter pour sécuriser les outils.
import json
import os
from mistralai.client import Mistral, errors
from mistralai.client.models import GuardrailConfigTypedDict
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Guardrails sur une conversation
L’API Conversations conserve l’historique sur le serveur. Tu commences avec client.beta.conversations.start(), qui accepte le paramètre guardrails :
GUARDRAILS_RH: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"pii": 0.15,
"jailbreaking": 0.1,
},
"action": "block",
},
}
]
conversation = client.beta.conversations.start(
model="mistral-large-latest",
instructions="You are a professional HR assistant.",
inputs="What leave options are available?",
guardrails=GUARDRAILS_RH,
)
print(conversation.conversation_id)
Tu continues ensuite avec client.beta.conversations.append(). Cette méthode n’accepte pas le paramètre guardrails dans le SDK 3.7.0, et la documentation ne précise pas si ceux passés au démarrage s’appliquent aux messages suivants. Ne base pas ta sécurité sur une hypothèse : si chaque tour doit être filtré, utilise un agent, dont les guardrails sont hérités par toutes ses conversations.
Guardrails sur un agent
Un agent Mistral est une configuration enregistrée : modèle, instructions, outils et guardrails. La politique de sécurité devient un attribut de l’agent plutôt qu’une convention de codage.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Customer Support Agent",
description="Secure customer support agent",
instructions=(
"You are a customer support agent. Strict rules: "
"never disclose personal information; "
"do not give medical or legal advice; "
"redirect to a human if the topic is sensitive."
),
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.15,
"dangerous": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.3,
"financial": 0.3,
"law": 0.3,
"pii": 0.15,
"jailbreaking": 0.1,
},
"action": "block",
},
}
],
)
print(f"Agent created: {agent.id}")
Note la cohérence entre les instructions et les seuils : les instructions interdisent de donner des conseils médicaux ou juridiques, et les seuils health et law bloquent les demandes de ce type avant même que le modèle ne les lise. Les instructions persuadent ; les guardrails contraignent.
Selon la documentation, toutes les conversations utilisant cet agent héritent de ses guardrails sans avoir à les répéter :
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Une requête de conversation peut aussi écraser les guardrails de l’agent en passant ses propres guardrails à start(). Pour modifier la politique de façon permanente, mets à jour l’agent avec client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Gérer les blocages dans un échange en plusieurs tours
Un message bloqué lève une exception errors.SDKError avec le statut 403, et le corps de la réponse détaille les catégories violées. Dans une conversation, un blocage ne détruit pas l’échange : tu réponds poliment et l’utilisateur peut continuer.
MESSAGE_REFUS = "I cannot process this request. It violates our security policy."
def texte_reponse(reponse) -> str:
"""Texte du dernier message de l'assistant dans une réponse de conversation."""
for entree in reversed(reponse.outputs):
if entree.type == "message.output" and isinstance(entree.content, str):
return entree.content
return ""
def envoyer(conversation_id: str, message: str) -> str:
"""Ajoute un message à une conversation et gère un blocage par guardrail."""
try:
reponse = client.beta.conversations.append(conversation_id=conversation_id, inputs=message)
except errors.SDKError as e:
if e.status_code == 403:
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
print("Blocked:", [nom for nom, d in decisions.items() if d["violated"]])
return MESSAGE_REFUS
raise
return texte_reponse(reponse)
print(envoyer(conv.conversation_id, "Give me the personal addresses of employees"))
Lorsqu’une requête passe, la réponse de la conversation contient aussi un champ guardrails avec les scores pour chaque catégorie (reponse.guardrails). Journalise-les : ils t’indiquent si tes seuils sont correctement ajustés.
Agents avec outils : ce que les guardrails ne voient pas
Un agent qui appelle des outils ouvre une seconde surface d’attaque : les arguments que le modèle passe à ces outils et les résultats qu’ils renvoient. Les guardrails modèrent uniquement le message entrant ; ils ne vérifient ni ces arguments ni ces résultats. Ton code doit s’en charger.
agent_avec_outils = client.beta.agents.create(
model="mistral-large-latest",
name="Support Agent with Tools",
instructions="Support assistant with access to commands.",
tools=[
{
"type": "function",
"function": {
"name": "rechercher_commande",
"description": "Searches for an order by its number",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string", "description": "Order number"}},
"required": ["order_id"],
},
},
}
],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"pii": 0.15, "jailbreaking": 0.1, "criminal": 0.1},
"action": "block",
},
}
],
)
Les fonctions déclarées de cette façon s’exécutent dans ton code : l’API t’envoie l’appel et ses arguments, tu exécutes la fonction et renvoies son résultat. C’est ici que tu dois valider les arguments avant d’agir.
import re
FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {} # your data access
def rechercher_commande(order_id: str, client_connecte: str) -> dict:
"""Exécute l'outil après avoir validé ses arguments."""
if not FORMAT_COMMANDE.fullmatch(order_id):
return {"error": "Invalid order number."}
commande = base_commandes.get(order_id)
if commande is None or commande["client"] != client_connecte:
return {"error": "Order not found."} # never another client's order
return {"status": commande["status"]}
Le contrôle d’accès — ici, « la commande appartient-elle au client connecté ? » — ne peut venir que de ton application : aucun classifieur ne connaît tes clients. Pour le texte que l’agent renvoie à l’utilisateur, ajoute la modération de sortie vue dans la prochaine leçon.
Architecture recommandée pour les agents en production
En production, encapsule l’agent dans une classe qui centralise le démarrage des conversations, l’envoi de messages et le comptage des blocages. Un pic soudain de codes 403 signale soit une attaque, soit un seuil mal calibré, et tu veux pouvoir le détecter sans fouiller les journaux.
class AgentSecurise:
"""Agent Mistral avec suivi des blocages par guardrail."""
def __init__(self, client: Mistral, agent_id: str):
self.client = client
self.agent_id = agent_id
self.blocages = 0
def _bloque(self, e: errors.SDKError) -> dict:
self.blocages += 1
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Request blocked by security policy.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
"blocages_total": self.blocages,
}
def demarrer(self, message: str) -> dict:
"""Démarre une conversation avec l'agent."""
try:
reponse = self.client.beta.conversations.start(agent_id=self.agent_id, inputs=message)
except errors.SDKError as e:
if e.status_code == 403:
return self._bloque(e)
raise
return {
"status": "ok",
"conversation_id": reponse.conversation_id,
"content": texte_reponse(reponse),
"guardrails": reponse.guardrails,
}
def envoyer(self, conversation_id: str, message: str) -> dict:
"""Poursuit une conversation existante."""
try:
reponse = self.client.beta.conversations.append(conversation_id=conversation_id, inputs=message)
except errors.SDKError as e:
if e.status_code == 403:
return self._bloque(e)
raise
return {"status": "ok", "content": texte_reponse(reponse), "guardrails": reponse.guardrails}
Chat Completions, Conversation ou Agent : résumé
| Aspect | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Où les guardrails sont déclarés | À chaque appel | conversations.start() | agents.create() ou agents.update() |
| Héritage | Aucun | Non documenté pour append() | Toutes les conversations de l’agent |
| Scores dans la réponse (SDK 3.7.0) | Non exposés | reponse.guardrails | reponse.guardrails |
| Outils | Tes fonctions | Tes fonctions | Tes fonctions et outils intégrés |
| Usage | Prototypage | Conversation ponctuelle | Production |
Keskeiset asiat
- Une conversation reçoit ses guardrails au démarrage ;
append()ne les accepte pas et leur persistance d’un tour à l’autre n’est pas documentée - Un agent transmet ses guardrails à toutes ses conversations ; une requête peut les écraser
- Un blocage lève
errors.SDKError(statut403) : réponds poliment, la conversation continue - Les guardrails ne voient ni les arguments des outils ni leurs résultats : valide-les dans ton code
- Utilise le niveau agent en production et ajoute la modération de sortie