Beveilig agents met guardrails
Op deze pagina
Bijgewerkt op 3 november 2026. Beide voorbeelden gaven eerder
guardrails={"enabled": True}door, een formaat dat niet bestaat: de officiële parameter is een lijst metmoderation_llm_v2-configuraties, met een drempelwaarde per categorie. De tekst verduidelijkt ook wat de documentatie stelt over hun reikwijdte: ze modereren alleen het binnenkomende bericht. Bronnen: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Agentbeveiliging is geen optie
Een autonome agent die tools gebruikt, toegang heeft tot internet en code uitvoert, vormt een risico als zijn acties niet worden beperkt. Het verschil met een eenvoudige completion-aanroep is fundamenteel, niet slechts een kwestie van graad: een model dat tekst produceert, kan na review worden gecorrigeerd, maar een agent die handelt, heeft al gehandeld. Guardrails zijn de set mechanismen die de grenzen definiëren van wat een agent wel en niet mag doen. Geen enkel mechanisme is op zichzelf voldoende; het is de gelaagdheid ervan die bescherming biedt.
De guardrails-parameter
Het eerste niveau wordt gedeclareerd bij het aanmaken van de agent.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Secure Agent",
description="Agent with guardrails enabled.",
instructions="""You are a professional assistant.
- Never share personal information
- Never generate inappropriate content
- Refuse out-of-scope requests
- If in doubt, ask for clarification""",
tools=[{"type": "web_search"}],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"pii": 0.2,
"jailbreaking": 0.2,
},
"action": "block",
},
}
],
)
Elke vermelde categorie krijgt een drempelwaarde van 0 tot 1: wordt deze overschreden, dan wordt het bericht van de gebruiker geweigerd met een 403-fout voordat het het model bereikt. De optie block_on_error weigert het verzoek ook als de evaluatie zelf mislukt. Volgens de documentatie erven alle conversaties voor de agent deze guardrails. Ze modereren alleen de input: noch de resultaten van webzoekopdrachten, noch het antwoord van de agent worden hierdoor gecontroleerd.
Dezelfde parameter wordt geaccepteerd op conversatieniveau, waar deze de configuratie van de agent overschrijft. Hiermee kunt u het gedrag van een gedeelde agent tijdelijk strenger maken zonder een tweede versie van die agent voor een specifiek gebruiksscenario te hoeven maken.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze this confidential document.",
guardrails=[ # replaces the agent's guardrails for this conversation
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"pii": 0.05, "jailbreaking": 0.1},
"action": "block",
},
}
],
)
Instructies: uw eerste verdedigingslinie
De systeemprompt blijft de meest effectieve hefboom omdat deze werkt voordat het model enige beslissing neemt. Een goed opgebouwde beveiligingsprompt scheidt duidelijk de rol, de reikwijdte, de verboden en het verwachte formaat.
instructions = """## Role
You are a legal assistant specializing in French labor law.
## Scope
- ONLY French labor law
- Refuse any out-of-scope questions (tax, real estate, criminal law, etc.)
## Strict Prohibitions
- NEVER give definitive legal advice
- NEVER draft legal documents without a disclaimer
- NEVER share information about other clients
- ALWAYS mention that a lawyer must validate
## Format
- Cite relevant legal articles
- Clearly state the limits of your response
- Always propose consulting a professional"""
Let op wat de sectie “Scope” doet: deze zegt niet alleen wat de agent behandelt, maar noemt expliciet de aangrenzende domeinen die hij moet weigeren. Zonder deze opsomming zou een belastingvraag gerelateerd aan een ontslag kunnen binnensluipen, omdat deze genoeg op arbeidsrecht lijkt voor het model om erop in te gaan. De sectie “Strict Prohibitions” volgt dezelfde logica: deze formuleert weigeringen, geen aanbevelingen. Een agent die de opdracht krijgt “voorzichtig” te zijn, kalibreert zijn eigen voorzichtigheid; een agent die verboden wordt documenten op te stellen zonder disclaimer, past een regel toe.
Het principe van de minste bevoegdheid
Elk gedeclareerd hulpmiddel is een mogelijkheid die de agent op het verkeerde moment kan inzetten. Vergelijk deze twee configuraties.
# Too many tools — large attack surface
dangerous_agent = client.beta.agents.create(
model="mistral-large-latest",
name="do-it-all-agent",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"},
{"type": "image_generation"},
{"type": "document_library", "library_ids": [lib.id]}
]
)
# Principle of least privilege — only what is necessary
secure_agent = client.beta.agents.create(
model="mistral-large-latest",
name="documentation-agent",
tools=[{"type": "document_library", "library_ids": [lib.id]}]
)
De tweede agent kan niet online gaan om informatie op te halen die ontbreekt in uw documenten, noch code uitvoeren op inhoud die u niet hebt gecontroleerd. Dit is geen beperking waar u onder lijdt; het is de garantie dat zijn antwoorden uit uw kennisbank komen en nergens anders. Vraag uzelf per tool af: als u geen scenario kunt bedenken waarin de agent deze nodig heeft, verwijder deze dan.
Filter handoffs
In een multi-agent-systeem geeft de client-modus u vetorecht over elke handoff. Een whitelist volstaat om te voorkomen dat de ene agent de andere bereikt via een pad dat u niet had voorzien.
response = client.beta.conversations.start(
agent_id=router.id,
inputs=user_query,
handoff_execution="client"
)
ALLOWED_AGENTS = {research.id, analyst.id} # Whitelist
for entry in response.outputs:
if entry.type == "agent.handoff":
if entry.next_agent_id not in ALLOWED_AGENTS:
print(f"BLOCKED: unauthorized handoff to {entry.next_agent_id}")
continue
# Continue with the authorized agent
De whitelist leeft in uw code, niet in de agentconfiguratie: deze blijft geldig, zelfs als iemand een handoff-doel aan de router toevoegt zonder u op de hoogte te stellen.
Sla niet op wat niet hoeft te worden opgeslagen
Voor gevoelige gegevens is de beste bescherming om niets op te slaan.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Deze instelling wordt per conversatie bepaald, waardoor u de geschiedenis van gewone uitwisselingen kunt behouden terwijl vertrouwelijke inhoud in een ephemere modus wordt verwerkt.
Moderatie stroomopwaarts
Een elegante variant is het plaatsen van een moderatie-agent aan het hoofd van de keten: deze onderzoekt het verzoek en draagt het alleen over aan de specialist als het acceptabel is.
moderator = client.beta.agents.create(
model="mistral-large-latest",
name="moderator",
description="Checks that requests are appropriate.",
instructions="""Analyze the user request:
- If appropriate: transfer to the specialist
- If inappropriate: politely reply that the request is not supported
- If ambiguous: ask for clarification"""
)
specialist = client.beta.agents.create(
model="mistral-large-latest",
name="specialist",
description="Handles validated requests.",
tools=[{"type": "web_search"}]
)
moderator = client.beta.agents.update(
agent_id=moderator.id,
handoffs=[specialist.id]
)
De waarde van dit patroon ligt in de scheiding van rollen: de moderator heeft geen tools en doet slechts één ding, zodat een kwaadaardig verzoek dat hij weigert, nooit de agent bereikt die weet hoe te handelen.
Generatie afstemmen
Completion-parameters dragen ook bij aan de beveiliging om een eenvoudige reden: een gehallucineerd antwoord is een risico, en creativiteit is de broedplaats daarvan.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Factual Agent",
description="Factual and conservative agent.",
completion_args={
"temperature": 0.1, # Very low creativity
"top_p": 0.85, # Restricted nucleus
"max_tokens": 1024 # Short responses
}
)
Een temperatuur van 0,1 in combinatie met een top_p van 0,85 laat het model zeer weinig speelruimte: voor een vraag waarvan het antwoord in uw documenten staat, haalt het dit op in plaats van een variant te bedenken. De limiet van 1024 tokens speelt een vergelijkbare rol, omdat een antwoord dat te lang wordt, uiteindelijk afwijkt van het gedocumenteerde domein en vulsel produceert. Deze instellingen zijn uiteraard niet geschikt voor een creatieve agent, maar ze zijn de standaardconfiguratie voor elke agent die feiten moet stellen – juridisch assistent, technische ondersteuning, productexpert.
Voordat u naar productie gaat
Deze mechanismen zijn alleen geldig wanneer ze gelaagd zijn, en de laatste controle komt neer op een paar verificaties. Instructies moeten expliciet de reikwijdte en verboden definiëren, en de agent mag alleen de tools hebben die strikt noodzakelijk zijn voor zijn taak. Verifieer dat guardrails zijn ingeschakeld en dat kritieke workflows in client-modus draaien, zodat geen enkele handoff wordt uitgevoerd zonder uw goedkeuring. Zorg ervoor dat store=False elke conversatie met gevoelige gegevens begeleidt en dat de temperatuur laag blijft waar van de agent wordt verwacht dat hij feitelijk blijft. Plaats tot slot een moderatie-agent vooraan in de keten, zodat onaanvaardbare verzoeken nooit de agents bereiken die weten hoe te handelen.
Belangrijkste punten
- Guardrails worden geconfigureerd op agent- en/of conversatieniveau
- Instructies zijn uw eerste verdedigingslinie – wees expliciet over verboden
- Pas het principe van de minste bevoegdheid toe: geef alleen de noodzakelijke tools
- Client-modus stelt u in staat ongeautoriseerde handoffs te valideren en te blokkeren
- In productie: stroomopwaartse moderatie, logging, agent-whitelist, store=False voor gevoelige gegevens