Sikre agenter med guardrails
På denne side
Opdateret 3. november 2026. Begge eksempler brugte tidligere
guardrails={"enabled": True}, et format der ikke eksisterer: den officielle parameter er en liste afmoderation_llm_v2-konfigurationer med en tærskel per kategori. Teksten præciserer også, hvad dokumentationen siger om deres omfang: de modererer kun den indgående besked. Kilder: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Agentsikkerhed er ikke valgfri
En autonom agent, der bruger værktøjer, tilgår internettet og udfører kode, udgør en risiko, hvis dens handlinger ikke er begrænset. Forskellen fra et simpelt opkald til fuldførelse er fundamental, ikke blot et spørgsmål om grad: en model, der producerer tekst, kan korrigeres efter gennemgang, men en agent, der handler, har allerede handlet. Guardrails er sættet af mekanismer, der definerer grænserne for, hvad en agent kan og ikke kan gøre. Ingen af dem er tilstrækkelig alene; det er lagdelingen, der giver beskyttelse.
Guardrails-parameteren
Det første niveau deklareres, når agenten oprettes.
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",
},
}
],
)
Hver listede kategori får en tærskel fra 0 til 1: overskrides dette punkt, afvises brugerens besked med en 403-fejl, før den når modellen, og block_on_error afviser også anmodningen, hvis selve evalueringen fejler. Ifølge dokumentationen arver alle samtaler for agenten disse guardrails. De modererer kun inputtet: hverken websearch-resultater eller agentens svar tjekkes af dem.
Den samme parameter accepteres på samtaleniveau, hvor den overskriver agentens konfiguration. Dette giver dig mulighed for midlertidigt at stramme adfærden for en delt agent uden at skulle oprette en anden version af denne agent til et enkelt use case.
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",
},
}
],
)
Instrukser: dit første forsvarsværk
Systemprompten forbliver den mest effektive løftestang, fordi den virker før enhver modelbeslutning. En velkonstrueret sikkerhedsprompt adskiller klart rolle, omfang, forbud og forventet format.
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"""
Bemærk, hvad afsnittet „Scope” gør: det siger ikke blot, hvad agenten håndterer; det navngiver eksplicit de tilstødende domæner, den skal afvise. Uden denne opregning kan et skattespørgsmål relateret til en afskedigelse snige sig igennem, fordi det ligner arbejdsmarkedslovgivning nok til, at modellen engagerer sig. Afsnittet „Strict Prohibitions” følger samme logik: det formulerer afvisninger, ikke anbefalinger. En agent, der får besked på at være „forsigtig”, kalibrerer sin egen forsigtighed; en agent, der er forbudt at udkaste uden en ansvarsfraskrivelse, anvender en regel.
Princippet om mindste privilegium
Hvert erklæret værktøj er en kapacitet, som agenten kan mobilisere på det forkerte tidspunkt. Sammenlign disse to konfigurationer.
# 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]}]
)
Den anden agent kan ikke gå online for at hente information, der mangler i dine dokumenter, og heller ikke udføre kode på indhold, du ikke har gennemgået. Dette er ikke en begrænsning, du lider under; det er garantien for, at dens svar kommer fra din vidensbase og ingen andre steder. Spørg dig selv værktøj for værktøj – hvis du ikke kan finde et scenarie, hvor agenten har brug for det, så fjern det.
Filtrér overdragelser (handoffs)
I et multi-agent-system giver klienttilstanden dig vetoret over hver eneste overdragelse. En whitelist er nok til at forhindre, at én agent når en anden via en sti, du ikke havde forudset.
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
Whitelisten lever i din kode, ikke i agentkonfigurationen: den forbliver gyldig, selvom nogen tilføjer et overdragelsesmål til routeren uden at underrette dig.
Gem ikke det, der ikke behøver at blive gemt
For følsomme data er den bedste beskyttelse at gemme ingenting.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Denne indstilling besluttes per samtale, hvilket giver dig mulighed for at beholde historikken for almindelige udvekslinger, mens du behandler fortroligt indhold i en ephemeral tilstand.
Moderér upstream
En elegant variant er at placere en modereringsagent i spidsen af kæden: den undersøger anmodningen og overfører den kun til specialisten, hvis den er acceptabel.
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]
)
Værdien af dette mønster ligger i rolleadskillelsen: moderatoren har ingen værktøjer og gør kun én ting, så en ondsindet anmodning, den afviser, når aldrig frem til agenten, der ved, hvordan man handler.
Justér generering
Parametre for fuldførelse bidrager også til sikkerhed af en simpel årsag: et hallucineret svar er en risiko, og kreativitet er dets ynglested.
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
}
)
En temperatur på 0,1 parret med en top_p på 0,85 efterlader modellen meget lidt spillerum: for et spørgsmål, hvis svar findes i dine dokumenter, henter den det i stedet for at brodere en variant. Loftet på 1024 tokens spiller en lignende rolle, fordi et svar, der bliver for langt, til sidst viger fra det dokumenterede omfang og producerer fyld. Disse indstillinger passer naturligvis ikke til en kreativ agent, men de er standardkonfigurationen for enhver agent, der forventes at fremlægge fakta – juridisk assistent, teknisk support, produktekspert.
Før du går i produktion
Disse mekanismer er kun gyldige, når de er lagdelte, og den endelige kontrol boils ned til nogle få verifikationer. Instrukser skal eksplicit definere omfang og forbud, og agenten må kun have de værktøjer, der er strengt nødvendige for dens opgave. Verificér, at guardrails er aktiveret, og at kritiske workflows kører i klienttilstand, så ingen overdragelse udføres uden din godkendelse. Sørg for, at store=False ledsager enhver samtale, der involverer følsomme data, og at temperaturen forbliver lav, hvor agenten forventes at være faktuel. Placér endelig en modereringsagent foran kæden, så uacceptable anmodninger aldrig når de agenter, der ved, hvordan man handler.
Vigtige pointer
- Guardrails konfigureres på agent- og/eller samtaleniveau
- Instrukser er dit første forsvarsværk – vær eksplicit omkring forbud
- Anvend princippet om mindste privilegium: giv kun de nødvendige værktøjer
- Klienttilstand giver dig mulighed for at validere og blokere uautoriserede overdragelser
- I produktion: upstream-moderering, logning, agent-whitelist, store=False for følsomme data