Turvaa agentit suojakaiteilla
Tällä sivulla
Päivitetty 3. marraskuuta 2026. Molemmissa aiemmissa esimerkeissä käytettiin muotoa
guardrails={"enabled": True}, jota ei ole olemassa: virallinen parametri on listamoderation_llm_v2-määrityksiä, joissa on kynnysarvo jokaiselle kategorialle. Tekstissä selvennetään myös dokumentaation mukaista soveltamisalaa: ne valvovat vain saapuvaa viestiä. Lähteet: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Agentin turvallisuus ei ole valinnaista
Autonominen agentti, joka käyttää työkaluja, pääsee internetiin ja suorittaa koodia, muodostaa riskin, jos sen toimintaa ei rajoiteta. Ero yksinkertaiseen täydennyspyyntöön on perustavanlaatuinen, ei vain asteellinen: malli, joka tuottaa tekstiä, voidaan korjata tarkistuksen jälkeen, mutta agentti, joka toimii, on jo toiminut. Suojakaiteet ovat mekanismien kokonaisuus, jotka määrittelevät rajat sille, mitä agentti saa ja ei saa tehdä. Mikään niistä ei yksinään riitä; suoja syntyy niiden kerrostamisesta.
guardrails-parametri
Ensimmäinen taso määritetään agenttia luotaessa.
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",
},
}
],
)
Jokaiselle listatulle kategorialle annetaan kynnysarvo väliltä 0–1: tämän ylittyessä käyttäjän viesti hylätään 403-virheellä ennen kuin se tavoittaa mallin, ja block_on_error hylkää pyynnön myös, jos itse arviointi epäonnistuu. Dokumentaation mukaan kaikki agentin keskustelut perivät nämä suojakaiteet. Ne valvovat vain syötettä: verkkohakutuloksia eikä agentin vastausta tarkisteta.
Sama parametri hyväksytään keskustelutasolla, jossa se ohittaa agentin määritykset. Tämä mahdollistaa jaetun agentin käytön väliaikaisen tiukentamisen ilman, että sinun tarvitsee luoda toista versiota agentista yhtä käyttötapausta varten.
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",
},
}
],
)
Ohjeet: ensimmäinen puolustuslinjasi
Järjestelmäkehotteet ovat tehokkain vipu, koska ne vaikuttavat ennen kuin malli tekee mitään päätöksiä. Hyvin rakennettu turvallisuuskehote erottaa selkeästi roolin, soveltamisalan, kiellot ja odotetun muodon.
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"""
Huomaa, mitä “Scope”-osio tekee: se ei vain kerro, mitä agentti käsittelee, vaan nimeää eksplisiittisesti ne lähialueet, jotka sen on hylättävä. Ilman tätä luetteloa verokysymys, joka liittyy irtisanomiseen, saattaa lipsahtaa läpi, koska se muistuttaa työoikeutta tarpeeksi, jotta malli ryhtyisi siihen. “Strict Prohibitions” -osio noudattaa samaa logiikkaa: se muotoilee kiellot, ei suosituksia. Agentti, jota kehotetaan olemaan “varovainen”, säätää omaa varovaisuuttaan; agentti, jolta kielletään luonnostelu ilman vastuuvapauslauseketta, noudattaa sääntöä.
Vähäisimpien oikeuksien periaate
Jokainen määritelty työkalu on kyky, jonka agentti voi mobilisoida väärään aikaan. Vertaa näitä kahta määritystä.
# 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]}]
)
Toinen agentti ei voi mennä verkkoon hakemaan tietoa, joka puuttuu dokumenteistasi, eikä suorittaa koodia sisällölle, jota et ole tarkistanut. Tämä ei ole rajoitus, jota kärsit, vaan takuu siitä, että sen vastaukset tulevat tietokannastasi eivätkä mistään muualta. Kysy itseltäsi työkalu kerrallaan: jos et löydä skenaariota, jossa agentti tarvitsee sitä, poista se.
Suodata siirtymät (handoffs)
Moniagenttijärjestelmässä client-tila antaa sinulle veto-oikeuden jokaiseen siirtymään. Valkoinen lista riittää estämään yhden agentin pääsyn toiseen reittiä pitkin, jota et ole ennakoinut.
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
Valkoinen lista elää koodissasi, ei agentin määrityksissä: se pysyy voimassa vaikka joku lisäisi siirtymäkohteen reitittimeen ilmoittamatta sinulle.
Älä tallenna sitä, mitä ei tarvitse tallentaa
Arkaluonteisen datan paras suoja on olla tallentamatta mitään.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Tämä asetus tehdään keskustelukohtaisesti, mikä mahdollistaa tavallisten vaihtojen historian säilyttämisen samalla kun luottamuksellista sisältöä käsitellään efemeerissä tilassa.
Valvo ylävirrassa
Elegantti muunnelma on sijoittaa valvova agentti ketjun kärkeen: se tutkii pyynnön ja siirtää sen asiantuntijalle vain, jos se on hyväksyttävä.
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]
)
Tämän mallin arvo piilee roolien erottelussa: valvojalla ei ole työkaluja ja se tekee vain yhtä asiaa, joten haitallinen pyyntö, jonka se hylkää, ei koskaan reachaa agenttia, joka osaa toimia.
Säädä generointia
Täydennysparametrit vaikuttavat myös turvallisuuteen yksinkertaisesta syystä: hallusinoiva vastaus on riski, ja luovuus on sen kasvualusta.
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
}
)
Lämpötila 0.1 yhdistettynä top_p:hen 0.85 jättää mallille hyvin vähän liikkumavaraa: kysymykselle, jonka vastaus löytyy dokumenteistasi, se hakee vastauksen sen sijaan, että se keksisi variaation. 1024 tokenin katto täyttää saman roolin, koska liian pitkäksi kasvava vastua eksyy lopulta dokumentoidun kehyksen ulkopuolelle ja tuottaa täytesisältö. Nämä asetukset eivät luonnollisesti sovi luovalle agentille, mutta ne ovat oletusmääritys kaikille agenteille, joiden odotetaan esittävän faktoja – lakiasiantuntija, tekninen tuki, tuoteasiantuntija.
Ennen tuotantoon siirtymistä
Nämä mekanismit ovat voimassa vain kerrostettuina, ja lopullinen tarkistus tiivistyy muutamaan varmistukseen. Ohjeiden on määriteltävä eksplisiittisesti soveltamisala ja kiellot, ja agentilla on oltava käytössään vain tehtävään ehdottomasti tarvittavat työkalut. Varmista, että suojakaiteet ovat käytössä ja että kriittiset työnkulut suoritetaan client-tilassa, jotta mikään siirtymä ei toteudu ilman hyväksyntääsi. Varmista, että store=False liittyy kaikkiin arkaluonteista dataa sisältäviin keskusteluihin ja että lämpötila pidetään matalana aina, kun agentin odotetaan pysyvän faktapohjaisena. Lopuksi sijoita valvova agentti ketjun eteen, jotta hyväksymättömät pyynnöt eivät koskaan reachaa agenteja, jotka osaavat toimia.
Keskeiset asiat
- Suojakaiteet määritetään agentti- ja/tai keskustelutasolla
- Ohjeet ovat ensimmäinen puolustuslinjasi – ole eksplisiittinen kielloissa
- Sovella vähäisimpien oikeuksien periaatetta: anna vain tarvittavat työkalut
- Client-tila mahdollistaa luvattomien siirtymien validoinnin ja estämisen
- Tuotannossa: ylävirran valvonta, lokitus, agenttien valkoinen lista, store=False arkaluonteiselle datalle