Garde-fous pour les agents Mistral
Na ovoj stranici
- Sécuriser les agents autonomes
- Garde-fous sur une conversation
- Garde-fous sur un agent
- Gérer les blocages dans un échange en plusieurs tours
- Agents avec outils : ce que les garde-fous ne voient pas
- Architecture recommandée pour les agents en production
- Chat Completions, Conversation ou Agent : résumé
- Ključne točke
Leçon réécrite le 3 novembre 2026. La version précédente s’appuyait sur un format de garde-fou fictif (
enabled, catégorieshate,violence,unpredictable), une méthodeconversation.send()inexistante et affirmait à tort que les garde-fous 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 : Modération et Garde-fous · Agents et Conversations · SDK Python mistralai.
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 garde-fous 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 garde-fous à 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"])
Garde-fous 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 supposition : si chaque tour doit être filtré, utilise un agent, dont les garde-fous sont hérités par toutes ses conversations.
Garde-fous sur un agent
Un agent Mistral est une configuration enregistrée : modèle, instructions, outils et garde-fous. 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 garde-fous contraignent.
Selon la documentation, toutes les conversations utilisant cet agent héritent de ses garde-fous sans avoir à les répéter :
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Une demande de conversation peut aussi écraser les garde-fous 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 garde-fou."""
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("Bloqué :", [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 demande 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 garde-fous 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 garde-fous 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] = {} # ton accès aux données
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."} # jamais la commande d'un autre client
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 garde-fou."""
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 garde-fous 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 |
Ključne točke
- Une conversation reçoit ses garde-fous 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 garde-fous à toutes ses conversations ; une demande peut les écraser
- Un blocage lève
errors.SDKError(statut403) : réponds poliment, la conversation continue - Les garde-fous 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