Biztonságos ügynökök korlátokkal (guardrails)
Ezen az oldalon
Frissítve: 2026. november 3. Mindkét korábbi példa hibásan a
guardrails={"enabled": True}formátumot használta, amely nem létezik: a hivatalos paraméter egymoderation_llm_v2konfigurációkból álló lista, kategóriánkénti küszöbértékkel. A szöveg tisztázza azt is, amit a dokumentáció a hatókörükről állít: kizárólag a bejövő üzenetet moderálják. Források: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Az ügynökbiztonság nem választható
Egy olyan autonóm ügynök, amely eszközöket használ, hozzáfér az internethez és kódot hajt végre, kockázatot jelent, ha a tevékenységét nem korlátozzuk. A különbség egy egyszerű szövegkiegészítő híváshoz képest alapvető, nem csupán mértékbeli: egy modellt, amely szöveget generál, ellenőrzés után ki lehet javítani, de egy ügynök, amely cselekszik, már végrehajtotta a cselekvést. A korlátok (guardrails) azoknak a mechanizmusoknak az összessége, amelyek meghatározzák, mit tehet és mit nem tehet egy ügynök. Egyik sem elegendő önmagában; a védelmet a rétegezésük biztosítja.
A guardrails paraméter
Az első szintet az ügynök létrehozásakor deklarálod.
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",
},
}
],
)
Minden felsorolt kategória kap egy 0 és 1 közötti küszöbértéket: ezen a ponton túl a felhasználó üzenetét a modell elérése előtt 403-as hibával utasítják el, a block_on_error pedig akkor is elutasítja a kérést, ha maga az értékelés meghiúsul. A dokumentáció szerint az ügynök összes beszélgetése örökli ezeket a korlátokat. Kizárólag a bemenetet moderálják: sem a webes keresés eredményeit, sem az ügynök válaszát nem ellenőrzik vele.
Ugyanez a paraméter elfogadott beszélgetési szinten is, ahol felülírja az ügynök konfigurációját. Ez lehetővé teszi, hogy ideiglenesen szigorúbbá tedd egy megosztott ügynök viselkedését anélkül, hogy egyetlen használati eset miatt létrehoznád az ügynök egy második verzióját.
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",
},
}
],
)
Utasítások: az első védelmi vonalad
A rendszerprompt marad a leghatékonyabb eszköz, mivel a modell bármilyen döntése előtt hat. Egy jól felépített biztonsági prompt egyértelműen elválasztja a szerepet, a hatókört, a tiltásokat és az elvárt formátumot.
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"""
Figyeld meg, mit tesz a „Scope“ (Hatókör) szakasz: nem csupán azt mondja meg, mivel foglalkozik az ügynök, hanem kifejezetten megnevezi azokat a szomszédos területeket, amelyeket el kell utasítania. E felsorolás nélkül egy elbocsátáshoz kapcsolódó adózási kérdés átcsúszhat, mert elég hasonlóságot mutat a munkajoggal ahhoz, hogy a modell belevágjon. A „Strict Prohibitions“ (Szigorú tiltások) szakasz ugyanerre a logikára épül: elutasításokat fogalmaz meg, nem ajánlásokat. Egy ügynök, amelynek azt mondják, legyen „óvatos“, saját maga kalibrálja az óvatosságát; egy ügynök, amelynek tiltják, hogy nyilatkozat nélkül jogi dokumentumot készítsen, egy szabályt alkalmaz.
A legkisebb jogosultság elve
Minden deklarált eszköz egy olyan képesség, amelyet az ügynök rossz időpontban is mozgósíthat. Hasonlítsd össze ezt a két konfigurációt.
# 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]}]
)
A második ügynök nem tud online menni, hogy olyan információkat szerezzen, amelyek hiányoznak a dokumentumaidból, és nem tud kódot futtatni olyan tartalmakon, amelyeket nem ellenőriztél. Ez nem egy korlátozás, amit elszenvedsz; ez a garancia arra, hogy a válaszai a te tudásbázisodból származnak, és sehonnan máshonnan. Kérdezd meg magadtól eszközről eszközre – ha nem találsz olyan forgatókönyvet, ahol az ügynöknek szüksége lenne rá, távolítsd el.
A kézbesítések (handoffs) szűrése
Többügynökös rendszerben a kliens mód lehetővé teszi, hogy minden kézbesítésnél érvényesítsd a vétójogodat. Egy engedélyezési lista (whitelist) elegendő ahhoz, megakadályozd, hogy egy ügynök elérjen egy másikat egy olyan útvonalon, amire nem számítottál.
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
Az engedélyezési lista a kódodban él, nem az ügynök konfigurációjában: érvényes marad akkor is, ha valaki hozzáad egy kézbesítési célpontot az útválasztóhoz anélkül, hogy értesítene téged.
Ne tárolj olyat, amit nem kell
Érzékeny adatok esetén a legjobb védelem, ha semmit sem tárolsz.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Ezt a beállítást beszélgetésenként döntöd el, ami lehetővé teszi, hogy megőrizd a hétköznapi beszélgetések előzményeit, miközben a bizalmas tartalmakat ephemeralis (nem maradandó) módban dolgozod fel.
Moderálj a lánc elején
Egy elegáns variáció, ha egy moderáló ügynököt helyezel a lánc élére: ez megvizsgálja a kérést, és csak akkor továbbítja a szakemberhez, ha az elfogadható.
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]
)
Ennek a mintának az értéke a szerepek szétválasztásában rejlik: a moderátornak nincsenek eszközei, és csak egy dolgot csinál, így egy rosszindulatú kérés, amelyet elutasít, soha nem éri el azt az ügynököt, amely tud cselekedni.
A generálás hangolása
A kiegészítési paraméterek is hozzájárulnak a biztonsághoz egy egyszerű okból: a hallucinált válasz kockázatot jelent, és a kreativitás ennek a táptalaja.
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
}
)
A 0,1-es hőmérséklet párosítva a 0,85-ös top_p értékkel nagyon kevés mozgásteret hagy a modellnek: egy olyan kérdésnél, amelyre a válasz benne van a dokumentumaidban, lekéri azt ahelyett, hogy variációkat szőne köré. A 1024 tokenes korlát hasonló szerepet játszik, mert egy túl hosszúra nyúló válasz végül eltér a dokumentált hatókörtől, és kitöltő szöveget (filler) produkál. Ezek a beállítások nyilvánvalóan nem illenek egy kreatív ügynökhöz, de ezek az alapértelmezett konfigurációk minden olyan ügynök számára, amelytől tények közlését várjuk – jogi asszisztens, műszaki támogatás, termékexpert.
Mielőtt élesítenéd
Ezek a mechanizmusok csak rétegezve érvényesek, és a végső ellenőrzés néhány verifikációra redukálódik. Az utasításoknak kifejezetten meg kell határozniuk a hatókört és a tiltásokat, és az ügynöknek csak a feladatához szigorúan szükséges eszközökkel kell rendelkeznie. Ellenőrizd, hogy a korlátok (guardrails) engedélyezve vannak-e, és hogy a kritikus munkafolyamatok kliens módban futnak-e, így egyetlen kézbesítés sem hajtódik végre a jóváhagyásod nélkül. Biztosítsd, hogy a store=False kísérjen minden bizalmas adatot érintő beszélgetést, és hogy a hőmérséklet alacsony maradjon ott, ahol az ügynöknek tényhűnek kell maradnia. Végül helyezz egy moderáló ügynököt a lánc elé, hogy az elfogadhatatlan kérések soha ne érjék el azokat az ügynököket, amelyek tudnak cselekedni.
Főbb megállapítások
- A korlátok (guardrails) ügynök és/vagy beszélgetés szinten konfigurálhatók
- Az utasítások az első védelmi vonalad – légy explicit a tiltásokkal kapcsolatban
- Alkalmazd a legkisebb jogosultság elvét: csak a szükséges eszközöket add meg
- A kliens mód lehetővé teszi a jogosulatlan kézbesítések jóváhagyását és blokkolását
- Éles környezetben: upstream moderálás, naplózás, ügynök engedélyezési lista,
store=Falseaz érzékeny adatoknál