Salt la conținutul principal
Română— Alege o limbă
Meniu

Gardes-fous pour les agents Mistral

Lecția 4 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Sécuriser les agents autonomes
  2. Garde-fous sur une conversation
  3. Garde-fous sur un agent
  4. Gérer les blocages dans un échange en plusieurs tours
  5. Agents avec outils : ce que les garde-fous ne voient pas
  6. Architecture recommandée pour les agents en production
  7. Chat Completions, Conversation ou Agent : résumé
  8. Puncte cheie

Leçon réécrite le 3 novembre 2026. La version précédente s’appuyait sur un format de garde-fou fictif (enabled, catégories hate, violence, unpredictable), une méthode conversation.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 l’API Conversations réelle (start, append) et a été vérifié par rapport aux types du SDK mistralai version 3.7.0. Sources : Modération et Gardes-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 pourquoi vous devez savoir précisément où les placer et ce qu’ils laissent sans protection.

Dans cette leçon, vous attacherez des garde-fous à une conversation, puis à un agent, gérerez leurs blocages lors d’un échange en plusieurs tours et verrez ce que vous devez 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. Vous commencez 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)

Vous poursuivez 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 transmis au démarrage s’appliquent aux messages suivants. Ne basez pas votre sécurité sur une supposition : si chaque tour doit être filtré, utilisez 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}")

Notez 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 également remplacer les garde-fous de l’agent en transmettant ses propres guardrails à start(). Pour modifier la politique de façon permanente, mettez à 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 : vous répondez 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 également un champ guardrails avec les scores pour chaque catégorie (reponse.guardrails). Journalisez-les : ils vous indiquent si vos 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 transmet à 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. Votre 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 manière s’exécutent dans votre code : l’API vous envoie l’appel et ses arguments, vous exécutez la fonction et renvoyez son résultat. C’est ici que vous devez valider les arguments avant d’agir.

import re

FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {}  # votre 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 provenir que de votre application : aucun classificateur ne connaît vos clients. Pour le texte que l’agent renvoie à l’utilisateur, ajoutez la modération de sortie vue dans la prochaine leçon.

Architecture recommandée pour les agents en production

En production, encapsulez l’agent dans une classe qui centralise le démarrage des conversations, l’envoi de messages et le comptage des blocages. Une augmentation soudaine des erreurs 403 signale soit une attaque, soit un seuil mal calibré, et vous voulez 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é

AspectChat CompletionsConversationAgent
Où les garde-fous sont déclarésÀ chaque appelconversations.start()agents.create() ou agents.update()
HéritageAucunNon documenté pour append()Toutes les conversations de l’agent
Scores dans la réponse (SDK 3.7.0)Non exposésreponse.guardrailsreponse.guardrails
OutilsVos fonctionsVos fonctionsVos fonctions et outils intégrés
UsagePrototypageConversation ponctuelleProduction

Puncte cheie

  • 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 remplacer
  • Un blocage lève errors.SDKError (statut 403) : répondez poliment, la conversation continue
  • Les garde-fous ne voient ni les arguments des outils ni leurs résultats : validez-les dans votre code
  • Utilisez le niveau agent en production et ajoutez la modération de sortie