Zabezpečenie agentov pomocou ochranných mechanizmov
Na tejto strane
Aktualizované 3. novembra 2026. Oba predchádzajúce príklady používali formát
guardrails={"enabled": True}, ktorý neexistuje: oficiálnym parametrom je zoznam konfiguráciímoderation_llm_v2s prahovou hodnotou pre každú kategóriu. Text tiež objasňuje, čo dokumentácia uvádza o ich rozsahu: moderujú iba prichádzajúcu správu. Zdroje: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Bezpečnosť agentov nie je voliteľná
Autonómny agent, ktorý používa nástroje, pristupuje na internet a vykonáva kód, predstavuje riziko, ak jeho činnosti nie sú obmedzené. Rozdiel oproti jednoduchému volaniu dokončovania je fundamentálny, nie len otázka miery: model, ktorý produkuje text, možno po kontrole opraviť, ale agent, ktorý koná, už konal. Ochranné mechanizmy (guardrails) sú súborom nástrojov, ktoré definujú hranice toho, čo agent môže a nemôže robiť. Žiadny z nich sám o sebe nestačí; ochranu poskytuje až ich vrstvenie.
Parameter guardrails
Prvá úroveň sa deklaruje pri vytváraní agenta.
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",
},
}
],
)
Každá uvedená kategória dostane prahovú hodnotu od 0 do 1: po jej prekročení sa používateľova správa zamietne s chybou 403 ešte predtým, než sa dostane k modelu, a parameter block_on_error zamietne požiadavku aj v prípade, že samotné vyhodnotenie zlyhá. Podľa dokumentácie všetky konverzácie pre daného agenta dedia tieto ochranné mechanizmy. Moderujú iba vstup: výsledky webového vyhľadávania ani odpoveď agenta nimi nie sú kontrolované.
Ten istý parameter je akceptovaný aj na úrovni konverzácie, kde prepíše konfiguráciu agenta. To ti umožňuje dočasne sprísniť správanie zdieľaného agenta bez toho, aby si musel vytvárať jeho druhú verziu pre jediný prípad použitia.
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",
},
}
],
)
Inštrukcie: tvoja prvá línia obrany
Systémový prompt zostáva najúčinnejšou pákou, pretože pôsobí pred akýmkoľvek rozhodnutím modelu. Dobre zostavený bezpečnostný prompt jasne oddeľuje rolu, rozsah, zákazy a očakávaný formát.
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"""
Všimni si, čo robí sekcia „Scope“: nielenže hovorí, čím sa agent zaoberá, ale explicitne vymenúva susedné domény, ktoré musí odmietnuť. Bez tohto vymenovania by mohla preklúznúť daňová otázka týkajúca sa prepustenia, pretože sa dosť podobá pracovnému právu na to, aby sa model zapojil. Sekcia „Strict Prohibitions“ nasleduje rovnakú logiku: formuluje zákazy, nie odporúčania. Agentovi, ktorému sa povie, aby bol „opatrný“, si svoju opatrnosť kalibruje sám; agentovi, ktorému je zakázané vytvárať dokumenty bez upozornenia, sa aplikuje pravidlo.
Princíp najmenších privilégií
Každý deklarovaný nástroj je schopnosť, ktorú môže agent mobilizovať v nevhodný čas. Porovnaj tieto dve konfigurácie.
# 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]}]
)
Druhý agent nemôže ísť online a získať informácie chýbajúce v tvojich dokumentoch, ani vykonávať kód na obsahu, ktorý si neskontoval. Nie je to obmedzenie, ktoré trpíš; je to záruka, že jeho odpovede pochádzajú z tvojej znalostnej bázy a z nikde iniaľ. Pýtaj sa pri každom nástroji zvlášť – ak nenájdeš scenár, kde by ho agent potreboval, odstráň ho.
Filtrovanie odovzdávaní (handoffs)
V systéme s viacerými agentmi ti režim klienta (client mode) dáva právo veta nad každým odovzdaním. Biely zoznam stačí na to, aby sa zabránilo tomu, že sa jeden agent dostane k inému cestou, ktorú si neočakával.
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
Biely zoznam žije v tvojom kóde, nie v konfigurácii agenta: zostáva platný aj vtedy, ak niekto pridá cieľ odovzdania do smerovača bez toho, aby ťa informoval.
Neukladaj to, čo nemusí byť uložené
Pre citlivé údaje je najlepšou ochranou neukladať nič.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Toto nastavenie sa rozhoduje pre každú konverzáciu zvlášť, čo ti umožňuje zachovávať históriu bežných výmen a zároveň spracovávať dôverný obsah v ephemérnom režime.
Moderuj vopred
Elegantnou variantou je umiestniť moderujúceho agenta na začiatok reťazca: preskúma požiadavku a prevedie ju na špecialistu iba vtedy, ak je prijateľná.
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]
)
Hodnota tohto vzoru spočíva v oddelení rolí: moderátor nemá žiadne nástroje a robí iba jednu vec, takže škodlivá požiadavka, ktorú zamietne, sa nikdy nedostane k agentovi, ktorý vie konať.
Ladenie generovania
Parametre dokončovania tiež prispievajú k bezpečnosti z jednoduchého dôvodu: halucinujúca odpoveď je rizikom a kreativita je jej živnou pôdou.
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
}
)
Teplota 0,1 v kombinácii s top_p 0,85 ponecháva modelu veľmi malý priestor: pri otázke, ktorej odpoveď sa nachádza v tvojich dokumentoch, ju retrievuje namiesto toho, aby vymýšľal variantu. Obmedzenie na 1024 tokenov hrá podobnú úlohu, pretože odpoveď, ktorá príliš narastie, sa nakoniec vzdiali od zdokumentovaného rozsahu a produkuje výplňový obsah. Tieto nastavenia zrejme nie sú vhodné pre kreatívneho agenta, ale sú predvolenou konfiguráciou pre akéhokoľvek agenta, od ktorého sa očakáva, že bude uvádzať fakty – právny asistent, technická podpora, produktový expert.
Pred nasadením do produkcie
Tieto mechanizmy sú platné iba vo vrstvách a finálna kontrola sa redukuje na niekoľko overení. Inštrukcie musia explicitne definovať rozsah a zákazy a agent musí mať iba nástroje striktne potrebné pre jeho úlohu. Over, či sú povolené ochranné mechanizmy a či kritické pracovné postupy bežia v režime klienta, aby sa žiadne odovzdanie nevykonalo bez tvojho súhlasu. Uisti sa, že store=False sprevádza každú konverzáciu zahŕňajúcu citlivé údaje a že teplota zostáva nízka všade tam, kde sa od agenta očakáva faktickosť. Nakoniec umiestni pred reťazec moderujúceho agenta, aby sa neprijateľné požiadavky nikdy nedostali k agentom, ktorí vedia konať.
Kľúčové poznatky
- Ochranné mechanizmy sa konfigurujú na úrovni agenta a/alebo konverzácie
- Inštrukcie sú tvoja prvá línia obrany – buď explicitný v zákazoch
- Aplikuj princíp najmenších privilégií: dávaj iba potrebné nástroje
- Režim klienta ti umožňuje validovať a blokovať neoprávnené odovzdania
- V produkcii: upstream moderácia, logovanie, biely zoznam agentov, store=False pre citlivé údaje