Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Guardrails pro agenty Mistral

Lekce 4 z 12 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Zabezpečení autonomních agentů
  2. Guardrails na konverzaci
  3. Guardrails na agentovi
  4. Zpracování blokování ve vícekolové výměně
  5. Agenti s nástroji: Co guardrails nevidí
  6. Doporučená architektura pro agenty v produkci
  7. Chat Completions, Conversation nebo Agent: Shrnutí
  8. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze spoléhala na fiktivní formát guardrail (enabled, kategorie hate, violence, unpredictable), neexistující metodu conversation.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 SDK mistralai verze 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í

AspektChat CompletionsConversationAgent
Kde se deklarují guardrailsKaž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.guardrailsreponse.guardrails
NástrojeTvé funkceTvé funkceTvé funkce a vestavěné nástroje
VyužitíPrototypováníJednorázová konverzaceProdukce

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