Guardrails pre agentov Mistral
Na tejto strane
Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia sa spoliehala na fiktívny formát guardrails (
enabled, kategóriehate,violence,unpredictable), neexistujúcu metóduconversation.send()a nesprávne tvrdila, že guardrails moderujú argumenty nástrojov. Podľa dokumentácie moderujú výlučne vstup. Kód teraz nasleduje skutočné Conversations API (start,append) a bol overený proti typom SDKmistralaiverzie 3.7.0. Zdroje: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Zabezpečenie autonómnych agentov
Agent so sebou nesie väčšie riziko než jednoduchý chatbot: volá nástroje, prehľadáva web a spája akcie do reťazcov. Guardrails pokrývajú len časť tohto povrchu – konkrétne vstup. Presne preto musíš vedieť, kam ich umiestniť a čo zostáva neodhalené.
V tejto lekcii pripojíš guardrails ku konverzácii a následne k agentovi, vybavíš ich blokovanie vo viac-krokovej výmene a zistíš, čo musíš pridať na zabezpečenie nástrojov.
import json
import os
from mistralai.client import Mistral, errors
from mistralai.client.models import GuardrailConfigTypedDict
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Guardrails v konverzácii
Conversations API uchováva históriu na serveri. Začneš metódou client.beta.conversations.start(), ktorá akceptuje parameter guardrails:
GUARDRAILS_RH: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"pii": 0.15,
"jailbreaking": 0.1,
},
"action": "block",
},
}
]
conversation = client.beta.conversations.start(
model="mistral-large-latest",
instructions="You are a professional HR assistant.",
inputs="What leave options are available?",
guardrails=GUARDRAILS_RH,
)
print(conversation.conversation_id)
Pokračuješ metódou client.beta.conversations.append(). Táto metóda v SDK 3.7.0 neakceptuje parameter guardrails a dokumentácia nešpecifikuje, či sa nastavenia z úvodu aplikujú aj na nasledujúce správy. Nezakladaj svoju bezpečnosť na predpokladoch: ak musíš filtrovať každý krok, použij agenta, ktorého guardrails dedia všetky jeho konverzácie.
Guardrails v agentovi
Agent Mistral je registrovaná konfigurácia: model, inštrukcie, nástroje a guardrails. Bezpečnostná politika sa stáva atribútom agenta, nie len konvenciou v kóde.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Customer Support Agent",
description="Secure customer support agent",
instructions=(
"You are a customer support agent. Strict rules: "
"never disclose personal information; "
"do not give medical or legal advice; "
"redirect to a human if the topic is sensitive."
),
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.15,
"dangerous": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.3,
"financial": 0.3,
"law": 0.3,
"pii": 0.15,
"jailbreaking": 0.1,
},
"action": "block",
},
}
],
)
print(f"Agent created: {agent.id}")
Všimni si konzistenciu medzi inštrukciami a prahovými hodnotami: inštrukcie zakazujú poskytovať lekárske alebo právne rady a prahy pre health a law blokujú požiadavky tohto typu skôr, než si ich model prečíta. Inštrukcie presviedčajú; guardrails obmedzujú.
Podľa dokumentácie všetky konverzácie využívajúce tohto agenta dedia jeho guardrails bez potreby ich opakovať:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Požiadavka na konverzáciu môže tiež prepísať guardrails agenta tým, že do start() odovzdá vlastné guardrails. Ak chceš politiku zmeniť natrvalo, aktualizuj agenta pomocou client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Vybavenie blokovania vo viac-krokovej výmene
Blokovaná správa vyvolá výnimku errors.SDKError so stavom 403 a telo odpovede obsahuje podrobnosti o porušených kategóriách. V konverzácii blok nezničí celú výmenu: odpovieš zdvorilo a používateľ môže pokračovať.
MESSAGE_REFUS = "I cannot process this request. It violates our security policy."
def texte_reponse(reponse) -> str:
"""Text poslednej správy asistenta v odpovedi konverzácie."""
for entree in reversed(reponse.outputs):
if entree.type == "message.output" and isinstance(entree.content, str):
return entree.content
return ""
def envoyer(conversation_id: str, message: str) -> str:
"""Pridá správu do konverzácie a vybaví blokovanie guardrails."""
try:
reponse = client.beta.conversations.append(conversation_id=conversation_id, inputs=message)
except errors.SDKError as e:
if e.status_code == 403:
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
print("Blocked:", [nom for nom, d in decisions.items() if d["violated"]])
return MESSAGE_REFUS
raise
return texte_reponse(reponse)
print(envoyer(conv.conversation_id, "Give me the personal addresses of employees"))
Keď požiadavka prejde, odpoveď konverzácie obsahuje aj pole guardrails so skóre pre každú kategóriu (reponse.guardrails). Loguj ich: povedia ti, či sú tvoje prahy správne naladené.
Agenti s nástrojmi: Čo guardrails nevidia
Agent, ktorý volá nástroje, otvára druhý útočný povrch: argumenty, ktoré model odovzdáva týmto nástrojom, a výsledky, ktoré nástroje vracajú. Guardrails moderujú iba prichádzajúcu správu; nekontrolujú ani tieto argumenty, ani výsledky. Musí to urobiť tvoj kód.
agent_avec_outils = client.beta.agents.create(
model="mistral-large-latest",
name="Support Agent with Tools",
instructions="Support assistant with access to commands.",
tools=[
{
"type": "function",
"function": {
"name": "rechercher_commande",
"description": "Searches for an order by its number",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string", "description": "Order number"}},
"required": ["order_id"],
},
},
}
],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"pii": 0.15, "jailbreaking": 0.1, "criminal": 0.1},
"action": "block",
},
}
],
)
Funkcie deklarované týmto spôsobom sa vykonávajú vo tvojom kóde: API ti pošle volanie a jeho argumenty, ty funkciu vykonáš a vrátiš výsledok. Práve tu musíš pred konaním validovať argumenty.
import re
FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {} # tvoj prístup k dátam
def rechercher_commande(order_id: str, client_connecte: str) -> dict:
"""Vykoná nástroj po validácii jeho argumentov."""
if not FORMAT_COMMANDE.fullmatch(order_id):
return {"error": "Invalid order number."}
commande = base_commandes.get(order_id)
if commande is None or commande["client"] != client_connecte:
return {"error": "Order not found."} # nikdy objednávka iného klienta
return {"status": commande["status"]}
Kontrola prístupu – v tomto prípade „patrí objednávka pripojenému klientovi?“ – môže pochádzať len z tvojej aplikácie: žiadny klasifikátor nepozná tvojich zákazníkov. Pre text, ktorý agent vráti používateľovi, pridaj výstupnú moderáciu z nasledujúcej lekcie.
Odporúčaná architektúra pre agentov v produkcii
V produkcii obal agenta do triedy, ktorá centralizuje spúšťanie konverzácií, odosielanie správ a počítanie blokov. Náhly nárast stavov 403 signalizuje buď útok, alebo zle nastavený prah, a ty to chceš vidieť bez prehrabávania sa v logoch.
class AgentSecurise:
"""Agent Mistral so sledovaním blokovania guardrails."""
def __init__(self, client: Mistral, agent_id: str):
self.client = client
self.agent_id = agent_id
self.blocages = 0
def _bloque(self, e: errors.SDKError) -> dict:
self.blocages += 1
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Request blocked by security policy.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
"blocages_total": self.blocages,
}
def demarrer(self, message: str) -> dict:
"""Spustí konverzáciu s agentom."""
try:
reponse = self.client.beta.conversations.start(agent_id=self.agent_id, inputs=message)
except errors.SDKError as e:
if e.status_code == 403:
return self._bloque(e)
raise
return {
"status": "ok",
"conversation_id": reponse.conversation_id,
"content": texte_reponse(reponse),
"guardrails": reponse.guardrails,
}
def envoyer(self, conversation_id: str, message: str) -> dict:
"""Pokračuje v existujúcej konverzácii."""
try:
reponse = self.client.beta.conversations.append(conversation_id=conversation_id, inputs=message)
except errors.SDKError as e:
if e.status_code == 403:
return self._bloque(e)
raise
return {"status": "ok", "content": texte_reponse(reponse), "guardrails": reponse.guardrails}
Chat Completions, Conversation alebo Agent: Zhrnutie
| Aspekt | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Kde sa deklarujú guardrails | Každé volanie | conversations.start() | agents.create() alebo agents.update() |
| Dedenie | Žiadne | Nie je zdokumentované pre append() | Všetky konverzácie agenta |
| Skóre v odpovedi (SDK 3.7.0) | Nie sú dostupné | reponse.guardrails | reponse.guardrails |
| Nástroje | Tvoje funkcie | Tvoje funkcie | Tvoje funkcie a vstavané nástroje |
| Využitie | Prototypovanie | Jednorazová konverzácia | Produkcia |
Kľúčové poznatky
- Konverzácia dostáva guardrails pri štarte;
append()ich neakceptuje a ich pretrvávanie medzi krokmi nie je zdokumentované - Agent odovzdáva svoje guardrails všetkým svojim konverzáciám; požiadavka ich môže prepísať
- Blokovanie vyvolá
errors.SDKError(stav403): odpovedz zdvorilo, konverzácia pokračuje - Guardrails nevidia ani argumenty nástrojov, ani ich výsledky: validuj ich vo svojom kóde
- V produkcii používaj úroveň agenta a pridaj výstupnú moderáciu