Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Guardrails voor Mistral Agents

Les 4 van 12 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Autonome agents beveiligen
  2. Guardrails op een conversatie
  3. Guardrails op een agent
  4. Blokkades afhandelen in een meertraps uitwisseling
  5. Agents met tools: wat guardrails niet zien
  6. Aanbevolen architectuur voor agents in productie
  7. Chat Completions, Conversatie of Agent: samenvatting
  8. Belangrijkste punten

Les herschreven op 3 november 2026. De vorige versie vertrouwde op een fictief guardrail-formaat (enabled, categorieën hate, violence, unpredictable), een niet-bestaande conversation.send()-methode, en beweerde ten onrechte dat guardrails tool-argumenten modereren. Volgens de documentatie modereren ze uitsluitend de input. De code volgt nu de daadwerkelijke Conversations API (start, append) en is geverifieerd tegen de mistralai SDK-types versie 3.7.0. Bronnen: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.

Autonome agents beveiligen

Een agent brengt meer risico met zich mee dan een simpele chatbot: hij roept tools aan, surft op het web en koppelt acties aan elkaar. Guardrails dekken slechts een deel van dit oppervlak—specifiek de input. Dit is precies waarom u precies moet weten waar u ze plaatst en wat ze onbedekt laten.

In deze les koppelt u guardrails aan een conversatie en vervolgens aan een agent, handelt u blokkades af in een meertraps uitwisseling, en ziet u wat u zelf moet toevoegen om tools te beveiligen.

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 op een conversatie

De Conversations API bewaart de geschiedenis op de server. U begint met client.beta.conversations.start(), dat guardrails accepteert:

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)

Vervolgens gaat u verder met client.beta.conversations.append(). Deze methode accepteert geen parameter guardrails in SDK 3.7.0, en de documentatie vermeldt niet of die bij de start doorgegeven waarden gelden voor daaropvolgende berichten. Bouw uw beveiliging niet op een aanname: als elke beurt gefilterd moet worden, gebruik dan een agent, waarvan de guardrails worden overgeërfd door al zijn conversaties.

Guardrails op een agent

Een Mistral-agent is een geregistreerde configuratie: model, instructies, tools en guardrails. Het beveiligingsbeleid wordt een attribuut van de agent in plaats van een codeerconventie.

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}")

Let op de consistentie tussen instructies en drempelwaarden: de instructies verbieden het geven van medisch of juridisch advies, en de drempels voor health en law blokkeren dit soort verzoeken voordat het model ze zelfs maar leest. Instructies overtuigen; guardrails beperken.

Volgens de documentatie erven alle conversaties die deze agent gebruiken de guardrails zonder ze te herhalen:

conv = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="How can I return a product?",
)

Een conversatieverzoek kan de guardrails van de agent ook overschrijven door zijn eigen guardrails mee te geven aan start(). Om het beleid permanent te wijzigen, update u de agent met client.beta.agents.update(agent_id=agent.id, guardrails=[...]).

Blokkades afhandelen in een meertraps uitwisseling

Een geblokkeerd bericht raise-t een errors.SDKError met status 403; de body geeft details over de geschonden categorieën. In een conversatie vernietigt een blokkade de uitwisseling niet: u reageert beleefd en de gebruiker kan doorgaan.

MESSAGE_REFUS = "I cannot process this request. It violates our security policy."


def tekst_antwoord(antwoord) -> str:
    """Tekst van het laatste assistant-bericht in een conversatie-antwoord."""
    for invoer in reversed(antwoord.outputs):
        if invoer.type == "message.output" and isinstance(invoer.content, str):
            return invoer.content
    return ""


def verstuur(conversatie_id: str, bericht: str) -> str:
    """Voegt een bericht toe aan een conversatie en handelt een guardrail-blokkade af."""
    try:
        antwoord = client.beta.conversations.append(conversation_id=conversatie_id, inputs=bericht)
    except errors.SDKError as e:
        if e.status_code == 403:
            beslissingen = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            print("Geblokkeerd:", [naam for naam, d in beslissingen.items() if d["violated"]])
            return MESSAGE_REFUS
        raise
    return tekst_antwoord(antwoord)


print(verstuur(conv.conversation_id, "Give me the personal addresses of employees"))

Wanneer een verzoek slaagt, bevat het conversatie-antwoord ook een veld guardrails met scores voor elke categorie (antwoord.guardrails). Log deze: ze vertellen u of uw drempels correct zijn afgesteld.

Agents met tools: wat guardrails niet zien

Een agent die tools aanroept, opent een tweede aanvalsoppervlak: de argumenten die het model aan die tools doorgeeft, en de resultaten die ze teruggeven. Guardrails modereren alleen het binnenkomende bericht; ze controleren noch deze argumenten, noch deze resultaten. Uw code moet dat doen.

agent_met_tools = 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",
            },
        }
    ],
)

Functies die op deze manier zijn gedeclareerd, worden in uw code uitgevoerd: de API stuurt u de aanroep en de argumenten, u voert de functie uit en geeft het resultaat terug. Dit is waar u argumenten moet valideren voordat u handelt.

import re

FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
basis_bestellingen: dict[str, dict] = {}  # uw data-toegang


def zoek_bestelling(order_id: str, verbonden_client: str) -> dict:
    """Voert de tool uit na validatie van de argumenten."""
    if not FORMAT_COMMANDE.fullmatch(order_id):
        return {"error": "Invalid order number."}
    bestelling = basis_bestellingen.get(order_id)
    if bestelling is None or bestelling["client"] != verbonden_client:
        return {"error": "Order not found."}  # nooit een bestelling van een andere client
    return {"status": bestelling["status"]}

Toegangscontrole—hier: “behoort de bestelling tot de verbonden client?”—kan alleen vanuit uw applicatie komen: geen enkele classifier kent uw klanten. Voor de tekst die de agent aan de gebruiker retourneert, voegt u output-moderatie toe uit de volgende les.

Aanbevolen architectuur voor agents in productie

In productie omhult u de agent in een klasse die het starten van conversaties, het verzenden van berichten en het tellen van blokkades centraliseert. Een plotselinge piek in 403s signaleert entweder een aanval of een slecht gekalibreerde drempel, en u wilt dat zien zonder door logs te spitten.

class BeveiligdeAgent:
    """Mistral Agent met tracking van guardrail-blokkades."""

    def __init__(self, client: Mistral, agent_id: str):
        self.client = client
        self.agent_id = agent_id
        self.blokkades = 0

    def _geblokkeerd(self, e: errors.SDKError) -> dict:
        self.blokkades += 1
        beslissingen = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
        return {
            "status": "blocked",
            "content": "Request blocked by security policy.",
            "categorieen": [naam for naam, d in beslissingen.items() if d["violated"]],
            "totaal_blokkades": self.blokkades,
        }

    def start(self, bericht: str) -> dict:
        """Start een conversatie met de agent."""
        try:
            antwoord = self.client.beta.conversations.start(agent_id=self.agent_id, inputs=bericht)
        except errors.SDKError as e:
            if e.status_code == 403:
                return self._geblokkeerd(e)
            raise
        return {
            "status": "ok",
            "conversatie_id": antwoord.conversation_id,
            "content": tekst_antwoord(antwoord),
            "guardrails": antwoord.guardrails,
        }

    def verstuur(self, conversatie_id: str, bericht: str) -> dict:
        """Zet een bestaande conversatie voort."""
        try:
            antwoord = self.client.beta.conversations.append(conversation_id=conversatie_id, inputs=bericht)
        except errors.SDKError as e:
            if e.status_code == 403:
                return self._geblokkeerd(e)
            raise
        return {"status": "ok", "content": tekst_antwoord(antwoord), "guardrails": antwoord.guardrails}

Chat Completions, Conversatie of Agent: samenvatting

AspectChat CompletionsConversatieAgent
Waar guardrails worden gedeclareerdElke aanroepconversations.start()agents.create() of agents.update()
OverervingGeenNiet gedocumenteerd voor append()Alle agent-conversaties
Scores in antwoord (SDK 3.7.0)Niet zichtbaarantwoord.guardrailsantwoord.guardrails
ToolsUw functiesUw functiesUw functies en ingebouwde tools
GebruikPrototypingEenmalige conversatieProductie

Belangrijkste punten

  • Een conversatie ontvangt zijn guardrails bij de start; append() accepteert ze niet, en hun persistentie over beurten heen is niet gedocumenteerd
  • Een agent geeft zijn guardrails door aan al zijn conversaties; een verzoek kan ze overschrijven
  • Een blokkade raise-t een errors.SDKError (status 403): reageer beleefd, de conversatie gaat door
  • Guardrails zien noch tool-argumenten noch hun resultaten: valideer ze in uw code
  • Gebruik in productie het agent-niveau en voeg output-moderatie toe