Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Guardrails za agente Mistral

Lekcija 4 od 12 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Zavarovanje avtonomnih agentov
  2. Guardrails v pogovoru
  3. Guardrails na agentu
  4. Obravnava blokad v večkorakni izmenjavi
  5. Agenti z orodji: česar guardrails ne vidijo
  6. Priporočena arhitektura za agente v produkciji
  7. Chat Completions, Conversation ali Agent: Povzetek
  8. Ključne ugotovitve

Lekcija je bila ponovno napisana 3. novembra 2026. Prejšnja različica se je zanašala na izmišljeno obliko guardrails (enabled, kategorije hate, violence, unpredictable), neobstoječo metodo conversation.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 SDK mistralai različ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

VidikChat CompletionsConversationAgent
Kje so deklarirani guardrailsVsak klicconversations.start()agents.create() ali agents.update()
DedovanjeBrezNi dokumentirano za append()Vsi pogovori agenta
Rezultati v odgovoru (SDK 3.7.0)Niso izpostavljenireponse.guardrailsreponse.guardrails
OrodjaTvoje funkcijeTvoje funkcijeTvoje funkcije in vgrajena orodja
UporabaPrototipiranjeEnkraten pogovorProdukcija

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