Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Guardrails pre agentov Mistral

Lekcia 4 z 12 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Zabezpečenie autonómnych agentov
  2. Guardrails v konverzácii
  3. Guardrails v agentovi
  4. Vybavenie blokovania vo viac-krokovej výmene
  5. Agenti s nástrojmi: Čo guardrails nevidia
  6. Odporúčaná architektúra pre agentov v produkcii
  7. Chat Completions, Conversation alebo Agent: Zhrnutie
  8. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia sa spoliehala na fiktívny formát guardrails (enabled, kategórie hate, violence, unpredictable), neexistujúcu metódu conversation.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 SDK mistralai verzie 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

AspektChat CompletionsConversationAgent
Kde sa deklarujú guardrailsKaždé volanieconversations.start()agents.create() alebo agents.update()
DedenieŽiadneNie je zdokumentované pre append()Všetky konverzácie agenta
Skóre v odpovedi (SDK 3.7.0)Nie sú dostupnéreponse.guardrailsreponse.guardrails
NástrojeTvoje funkcieTvoje funkcieTvoje funkcie a vstavané nástroje
VyužitiePrototypovanieJednorazová konverzáciaProdukcia

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 (stav 403): 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