Guardrails pro agenty Mistral
Na této stránce
Lekce přepsána 3. listopadu 2026. Předchozí verze spoléhala na fiktivní formát guardrail (
enabled, kategoriehate,violence,unpredictable), neexistující metoduconversation.send()a mylně tvrdila, že guardrails moderují argumenty nástrojů. Podle dokumentace moderují pouze vstup. Kód nyní odpovídá skutečnému Conversations API (start,append) a byl ověřen proti typům SDKmistralaiverze 3.7.0. Zdroje: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Zabezpečení autonomních agentů
Agent nese větší riziko než jednoduchý chatbot: volá nástroje, prochází web a řetězí akce za sebou. Guardrails pokrývají pouze část tohoto povrchu – konkrétně vstup. Přesně proto musíš vědět, kam je umístit a co zůstává neodhalené.
V této lekci připojíš guardrails ke konverzaci a poté k agentovi, zpracuješ jejich blokování ve vícekolové výměně a uvidíš, co musíš přidat pro zabezpečení nástrojů.
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 na konverzaci
Conversations API uchovává historii na serveru. Začneš pomocí client.beta.conversations.start(), která přijímá parametr 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)
Poté pokračuješ pomocí client.beta.conversations.append(). Tato metoda v SDK 3.7.0 nepřijímá parametr guardrails a dokumentace neuvádí, zda se ty předané při startu aplikují na následující zprávy. Nestav své zabezpečení na předpokladech: pokud musí být filtrováno každé kolo, použij agenta, jehož guardrails dědí všechny jeho konverzace.
Guardrails na agentovi
Agent Mistral je registrovaná konfigurace: model, instrukce, nástroje a guardrails. Bezpečnostní politika se stává atributem agenta, nikoliv jen konvencí v kódu.
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 souladu mezi instrukcemi a prahovými hodnotami: instrukce zakazují poskytování lékařských nebo právních rad a prahy health a law blokují žádosti tohoto typu ještě předtím, než si je model přečte. Instrukce přesvědčují; guardrails omezují.
Podle dokumentace všechny konverzace využívající tohoto agenta dědí jeho guardrails bez nutnosti je opakovat:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Žádost o konverzaci může také přepsat guardrails agenta předáním vlastních guardrails do metody start(). Chcete-li politiku změnit trvale, aktualizuj agenta pomocí client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Zpracování blokování ve vícekolové výměně
Blokovaná zpráva vyvolá errors.SDKError se stavem 403 a tělo odpovědi podrobně popisuje porušené kategorie. V konverzaci blok nezničí výměnu: odpovíš zdvořile a uživatel může pokračovat.
MESSAGE_REFUS = "I cannot process this request. It violates our security policy."
def texte_reponse(reponse) -> str:
"""Text of the last assistant message in a conversation response."""
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:
"""Adds a message to a conversation and handles a guardrail block."""
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"))
Když žádost projde, odpověď konverzace také obsahuje pole guardrails se skóre pro každou kategorii (reponse.guardrails). Loguj je: řeknou ti, zda jsou tvé prahové hodnoty správně naladěny.
Agenti s nástroji: Co guardrails nevidí
Agent, který volá nástroje, otevírá druhý útočný povrch: argumenty, které model předává těmto nástrojům, a výsledky, které vracejí. Guardrails moderují pouze příchozí zprávu; nekontrolují ani tyto argumenty, ani tyto výsledky. To musí udělat tvůj 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",
},
}
],
)
Funkce deklarované tímto způsobem se vykonávají ve tvém kódu: API ti pošle volání a jeho argumenty, ty funkci provedeš a vrátíš její výsledek. Zde musíš před provedením akce validovat argumenty.
import re
FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {} # your data access
def rechercher_commande(order_id: str, client_connecte: str) -> dict:
"""Executes the tool after validating its arguments."""
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."} # never another client's order
return {"status": commande["status"]}
Řízení přístupu – zde „patří objednávka připojenému klientovi?“ – může pocházet pouze z tvé aplikace: žádný klasifikátor nezná tvé zákazníky. Pro text, který agent vrací uživateli, přidej moderaci výstupu z další lekce.
Doporučená architektura pro agenty v produkci
V produkci obal agenta do třídy, která centralizuje spouštění konverzací, odesílání zpráv a počítání blokování. Náhlý nárůst chyb 403 signalizuje buď útok, nebo špatně nastavený práh, a ty to chceš vidět bez prohrabávání se logy.
class AgentSecurise:
"""Mistral Agent with guardrail block tracking."""
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:
"""Starts a conversation with the agent."""
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:
"""Continues an existing conversation."""
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 nebo Agent: Shrnutí
| Aspekt | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Kde se deklarují guardrails | Každé volání | conversations.start() | agents.create() nebo agents.update() |
| Dědičnost | Žádná | Není zdokumentováno pro append() | Všechny konverzace agenta |
| Skóre v odpovědi (SDK 3.7.0) | Nepřístupná | reponse.guardrails | reponse.guardrails |
| Nástroje | Tvé funkce | Tvé funkce | Tvé funkce a vestavěné nástroje |
| Využití | Prototypování | Jednorázová konverzace | Produkce |
Klíčové poznatky
- Konverzace získá své guardrails při startu;
append()je nepřijímá a jejich přetrvávání napříč koly není zdokumentováno - Agent předává své guardrails všem svým konverzacím; žádost je může přepsat
- Blokování vyvolá
errors.SDKError(stav403): odpověz zdvořile, konverzace pokračuje - Guardrails nevidí ani argumenty nástrojů, ani jejich výsledky: validuj je ve svém kódu
- V produkci používej úroveň agenta a přidej moderaci výstupu