Säkra agenter med skyddsräcken
På denna sida
Uppdaterad 3 november 2026. Båda exemplen använde tidigare
guardrails={"enabled": True}, ett format som inte existerar: den officiella parametern är en lista medmoderation_llm_v2-konfigurationer, med ett tröskelvärde per kategori. Texten förtydligar också vad dokumentationen säger om deras omfattning: de modererar endast det inkommande meddelandet. Källor: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Agentsäkerhet är inte valfritt
En autonom agent som använder verktyg, får tillgång till internet och exekverar kod utgör en risk om dess handlingar inte begränsas. Skillnaden från ett enkelt anrop för textgenerering är fundamental, inte bara en gradfråga: en modell som producerar text kan korrigeras vid granskning, men en agent som agerar har redan agerat. Skyddsräcken (guardrails) är de mekanismer som definierar gränserna för vad en agent får och inte får göra. Ingen av dem räcker ensam; det är lagringen av dem som skapar skyddet.
Parametern guardrails
Den första nivån deklareras när agenten skapas.
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",
},
}
],
)
Varje listad kategori får ett tröskelvärde mellan 0 och 1: överskrids detta värde avvisas användarens meddelande med ett 403-fel innan det når modellen, och block_on_error avvisar även begäran om själva utvärderingen misslyckas. Enligt dokumentationen ärver alla konversationer för agenten dessa skyddsräcken. De modererar endast inmatningen: varken sökresultat från webben eller agentens svar kontrolleras av dem.
Samma parameter accepteras på konversationsnivå, där den åsidosätter agentens konfiguration. Detta låter dig tillfälligt skärpa beteendet hos en delad agent utan att skapa en andra version av den agenten för ett enskilt användningsfall.
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",
},
}
],
)
Instruktioner: din första försvarslinje
Systemprompten förblir den mest effektiva hävstången eftersom den verkar innan något modellbeslut fattas. En välkonstruerad säkerhetsprompt separerar tydligt roll, omfattning, förbud och förväntat 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"""
Lägg märke till vad avsnittet “Scope” gör: det säger inte bara vad agenten hanterar; det namnger explicit de angränsande domänerna den måste vägra. Utan denna uppräkning kan en skattefråga relaterad till en uppsägning smita igenom eftersom den liknar arbetsrätt tillräckligt mycket för att modellen ska engagera sig. Avsnittet “Strict Prohibitions” följer samma logik: det formulerar vägran, inte rekommendationer. En agent som tillsägs vara “försiktig” kalibrerar sin egen försiktighet; en agent som förbjuds att utkast utan ansvarsfriskrivning tillämpar en regel.
Principen om minsta privilegium
Varje deklarerat verktyg är en kapacitet som agenten kan mobilisera vid fel tillfälle. Jämför dessa två 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 andra agenten kan inte gå online för att hämta information som saknas i dina dokument, inte heller exekvera kod på innehåll du inte har granskat. Detta är inte en begränsning du lider av; det är garantin för att dess svar kommer från din kunskapsbas och ingen annanstans. Fråga dig själv verktyg för verktyg – om du inte kan hitta ett scenario där agenten behöver det, ta bort det.
Filtrera överlämningar
I ett system med flera agenter ger klientläget dig vetorätt över varje överlämning. En vitlista räcker för att förhindra att en agent når en annan via en väg du inte förutsett.
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
Vitlistan finns i din kod, inte i agentkonfigurationen: den förblir giltig även om någon lägger till ett överlämningsmål i routern utan att meddela dig.
Lagra inte det som inte behöver lagras
För känsliga data är det bästa skyddet att inte lagra något alls.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Denna inställning beslutas per konversation, vilket låter dig behålla historiken för vanliga utbyten samtidigt som du bearbetar konfidentiellt innehåll i ett flyktigt läge.
Moderera uppströms
En elegant variant är att placera en modereringsagent längst fram i kedjan: den undersöker begäran och överför den endast till specialisten om den är 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ärdet i detta mönster ligger i rollsepareringen: moderatorn har inga verktyg och gör bara en sak, så en skadlig begäran som den avvisar når aldrig agenten som vet hur man agerar.
Justera genereringen
Parametrar för textgenerering bidrar också till säkerheten av en enkel anledning: ett hallucinerat svar är en risk, och kreativitet är dess grogrund.
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 kombinerat med ett top_p på 0,85 lämnar modellen mycket lite utrymme: för en fråga vars svar finns i dina dokument hämtar den det istället för att brodera en variant. Taket på 1024 token spelar en liknande roll, eftersom ett svar som blir för långt så småningom hamnar utanför det dokumenterade omfånget och producerar fyllnad. Dessa inställningar passar uppenbarligen inte en kreativ agent, men de är standardkonfigurationen för varje agent som förväntas redogöra för fakta – juridisk assistent, teknisk support, produktexpert.
Innan du går till produktion
Dessa mekanismer är bara giltiga när de lagras, och den slutliga kontrollen kokar ner till några få verifieringar. Instruktioner måste explicit definiera omfattning och förbud, och agenten måste endast ha de verktyg som är strikt nödvändiga för dess uppgift. Verifiera att skyddsräcken är aktiverade och att kritiska arbetsflöden körs i klientläge så att ingen överlämning exekveras utan ditt godkännande. Se till att store=False åtföljer varje konversation som involverar känsliga data, och att temperaturen hålls låg överallt där agenten förväntas hålla sig faktabaserad. Placera slutligen en modereringsagent längst fram i kedjan så att oacceptabla begäranden aldrig når de agenter som vet hur man agerar.
Viktiga punkter
- Skyddsräcken konfigureras på agent- och/eller konversationsnivå
- Instruktioner är din första försvarslinje – var explicit med förbud
- Tillämpa principen om minsta privilegium: ge endast nödvändiga verktyg
- Klientläge låter dig validera och blockera obehöriga överlämningar
- I produktion: uppströms-moderering, loggning, agentvitlista, store=False för känsliga data