Guardrails za agente Mistral
Na tej strani
Lekcija je bila ponovno napisana 3. novembra 2026. Prejšnja različica se je zanašala na izmišljeno obliko guardrails (
enabled, kategorijehate,violence,unpredictable), neobstoječo metodoconversation.send()in napačno trdila, da guardrails moderirajo argumente orodij. Glede na dokumentacijo moderirajo samo vhodne podatke. Koda zdaj sledi dejanskemu API-ju za pogovore (start,append) in je bila preverjena glede na tipe SDKmistralairazličice 3.7.0. Viri: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Zavarovanje avtonomnih agentov
Agent nosi večje tveganje kot preprost klepetalni bot: kliče orodja, brska po spletu in povezuje dejanja v verige. Guardrails pokrivajo le del tega površja – specifično vhodne podatke. Prav zato moraš natančno vedeti, kam jih postaviti in kaj pustijo nepokrito.
V tej lekciji boš pripel guardrails pogovoru in nato agentu, obravnaval njihove blokade v večkorakni izmenjavi ter videl, kaj moraš dodati za zavarovanje orodij.
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 pogovoru
API za pogovore hrani zgodovino na strežniku. Začneš z client.beta.conversations.start(), ki sprejme 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)
Nato nadaljuješ z client.beta.conversations.append(). Ta metoda v SDK 3.7.0 ne sprejme parametra guardrails, dokumentacija pa ne navaja, ali se tisti, podani ob zagonu, uporabljajo tudi za naslednja sporočila. Ne gradi svoje varnosti na predpostavkah: če mora biti vsak korak filtriran, uporabi agenta, katerega guardrails podedujejo vsi njegovi pogovori.
Guardrails na agentu
Agent Mistral je registrirana konfiguracija: model, navodila, orodja in guardrails. Varnostna politika postane atribut agenta in ne le programska konvencija.
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}")
Opazi skladnost med navodili in pragovi: navodila prepovedujejo dajanje zdravstvenih ali pravnih nasvetov, pragova health in law pa blokirata zahteve te vrste, preden jih model sploh prebere. Navodila prepričujejo; guardrails omejujejo.
Glede na dokumentacijo vsi pogovori, ki uporabljajo tega agenta, podedujejo njegove guardrails brez potrebe po ponavljanju:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Zahteva za pogovor lahko tudi prepiše guardraise agenta tako, da metodi start() poda svoje lastne guardrails. Če želiš politiko trajno spremeniti, posodobi agenta z client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Obravnava blokad v večkorakni izmenjavi
Blokirano sporočilo sproži napako errors.SDKError s statusom 403, telo odgovora pa podrobno opiše kršene kategorije. V pogovoru blokada ne uniči izmenjave: vljudno odgovoriš in uporabnik lahko nadaljuje.
MESSAGE_REFUS = "I cannot process this request. It violates our security policy."
def texte_reponse(reponse) -> str:
"""Besedilo zadnjega sporočila asistenta v odgovoru pogovora."""
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:
"""Doda sporočilo v pogovor in obravnava blokado 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"))
Ko zahteva uspe, odgovor pogovora vsebuje tudi polje guardrails z rezultati za vsako kategorijo (reponse.guardrails). Te beleži: povedo ti, ali so tvoji pragovi pravilno nastavljeni.
Agenti z orodji: česar guardrails ne vidijo
Agent, ki kliče orodja, odpira drugo napadalno površino: argumente, ki jih model posreduje tem orodjem, in rezultate, ki jih ta vrnejo. Guardrails moderirajo samo vhodno sporočilo; ne preverjajo niti teh argumentov niti rezultatov. To mora storiti tvoja koda.
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",
},
}
],
)
Funkcije, deklarirane na ta način, se izvajajo v tvoji kodi: API ti pošlje klic in njegove argumente, ti izvršiš funkcijo in vrneš rezultat. Prav tu moraš pred dejanjem validirati argumente.
import re
FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {} # tvoj dostop do podatkov
def rechercher_commande(order_id: str, client_connecte: str) -> dict:
"""Izvrši orodje po validaciji njegovih 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."} # nikoli naročilo drugega klienta
return {"status": commande["status"]}
Nadzor dostopa – tukaj „ali naročilo pripada povezanemu klientu?” – lahko izvira samo iz tvoje aplikacije: noben klasifikator ne pozna tvojih strank. Za besedilo, ki ga agent vrne uporabniku, dodaj izhodno moderacijo iz naslednje lekcije.
Priporočena arhitektura za agente v produkciji
V produkciji ovij agenta v razred, ki centralizira zagon pogovora, pošiljanje sporočil in štetje blokad. Nenaden skok napak 403 signalizira bodisi napad bodisi slabo umerjen prag, to pa želiš videti brez brskanja po dnevnikih.
class AgentSecurise:
"""Agent Mistral s sledenjem blokad 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:
"""Začne pogovor z 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:
"""Nadaljuje obstoječi pogovor."""
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 ali Agent: Povzetek
| Vidik | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Kje so deklarirani guardrails | Vsak klic | conversations.start() | agents.create() ali agents.update() |
| Dedovanje | Brez | Ni dokumentirano za append() | Vsi pogovori agenta |
| Rezultati v odgovoru (SDK 3.7.0) | Niso izpostavljeni | reponse.guardrails | reponse.guardrails |
| Orodja | Tvoje funkcije | Tvoje funkcije | Tvoje funkcije in vgrajena orodja |
| Uporaba | Prototipiranje | Enkraten pogovor | Produkcija |
Ključne ugotovitve
- Pogovor prejme svoje guardrails ob zagonu;
append()jih ne sprejme, njihova obstojnost med koraki pa ni dokumentirana. - Agent posreduje svoje guardrails vsem svojim pogovorom; zahteva jih lahko prepiše.
- Blokada sproži
errors.SDKError(status403): odgovori vljudno, pogovor se nadaljuje. - Guardrails ne vidijo niti argumentov orodij niti njihovih rezultatov: validiraj jih v svoji kodi.
- V produkciji uporabi raven agenta in dodaj izhodno moderacijo.