Guardrails voor Mistral Agents
Op deze pagina
Les herschreven op 3 november 2026. De vorige versie vertrouwde op een fictief guardrail-formaat (
enabled, categorieënhate,violence,unpredictable), een niet-bestaandeconversation.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 demistralaiSDK-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
| Aspect | Chat Completions | Conversatie | Agent |
|---|---|---|---|
| Waar guardrails worden gedeclareerd | Elke aanroep | conversations.start() | agents.create() of agents.update() |
| Overerving | Geen | Niet gedocumenteerd voor append() | Alle agent-conversaties |
| Scores in antwoord (SDK 3.7.0) | Niet zichtbaar | antwoord.guardrails | antwoord.guardrails |
| Tools | Uw functies | Uw functies | Uw functies en ingebouwde tools |
| Gebruik | Prototyping | Eenmalige conversatie | Productie |
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(status403): 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