Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Guardrails għall-Aġenti ta' Mistral

Lezzjoni 4 / 12 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Sigurtà ta’ Aġenti Awtonomi
  2. Guardrails fuq Konversazzjoni
  3. Guardrails fuq Aġent
  4. Immaniġġjar tal-Imblukkar f’Skambju b’Diversi Dawriet
  5. Aġenti b’Għodod: X’Ma Jarawx il-Guardrails
  6. Arkitettura Rakkomandata għal Aġenti fil-Produzzjoni
  7. Chat Completions, Konversazzjoni, jew Aġent: Sommarju
  8. Punti Ewlenin

Lezzjon miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddependi fuq format fittizju ta’ guardrail (enabled, kategoriji hate, violence, unpredictable), metodu conversation.send() li ma jeżistix, u ddikjarat b’mod żbaljat li l-guardrails jimmoderaw l-argumenti tal-għodod. Skont id-dokumentazzjoni, huma jimmoderaw biss l-input. Il-kodiċi issa jsegwi l-API reali tal-Conversations (start, append) u ġie vverifikat kontra t-tipi tal-SDK mistralai verżjoni 3.7.0. Sorsi: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.

Sigurtà ta’ Aġenti Awtonomi

Aġent iġorr riskju akbar minn chatbot sempliċi: jsejjaħ għodod, jibbrawżja l-web, u jgħaqqad azzjonijiet flimkien. Il-guardrails jkopru biss parti minn din iż-żona ta’ riskju—speċifikament, l-input. Dan huwa eżattament għaliex għandek bżonn tkun taf preċiżament fejn tpoġġihom u x’ihallu mhux kopert.

F’din il-lezzjoni, se twaħħal guardrails ma’ konversazzjoni u mbagħad ma’ aġent, timmaniġġja l-imblukkar tagħhom f’skambju b’diversi dawriet, u tara x’għandek iżżid biex tissikura l-għodod.

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 fuq Konversazzjoni

L-API tal-Conversations iżżomm l-istorja fuq is-server. Tibda b’client.beta.conversations.start(), li jaċċetta 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="Int assistent tal-HR professjonali.",
    inputs="X'għażliet ta' leave huma disponibbli?",
    guardrails=GUARDRAILS_RH,
)
print(conversation.conversation_id)

Imbagħad tkompli b’client.beta.conversations.append(). Dan il-metodu ma jaċċettax parametru guardrails fl-SDK 3.7.0, u d-dokumentazzjoni ma tgħidx jekk dawk mgħoddija fil-bidu japplikawx għal messaġġi sussegwenti. Tibnix is-sigurtà tiegħek fuq suppożizzjoni: jekk kull dawra trid tiġi ffiltrata, uża aġent, li l-guardrails tiegħu jiġu wirteti mill-konversazzjonijiet kollha tiegħu.

Guardrails fuq Aġent

Aġent ta’ Mistral huwa konfigurazzjoni rreġistrata: mudell, istruzzjonijiet, għodod, u guardrails. Il-politika ta’ sigurtà ssir attribut tal-aġent minflok konvenzjoni tal-ikkodjar.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Customer Support Agent",
    description="Aġent ta' appoġġ għall-klijenti sikur",
    instructions=(
        "Int aġent ta' appoġġ għall-klijenti. Regoli stretti: "
        "qatt ma tikxef informazzjoni personali; "
        "tagħtix pariri mediċi jew legali; "
        "idderieġi lejn bniedem jekk is-suġġett huwa sensittiv."
    ),
    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}")

Innota l-konsistenza bejn l-istruzzjonijiet u l-limiti (thresholds): l-istruzzjonijiet jipprojbixxu li tingħata pariri mediċi jew legali, u l-limiti ta’ health u law jimblukkaw talbiet ta’ dan it-tip qabel ma l-mudell anki jaqrahom. L-istruzzjonijiet jipperswadu; il-guardrails jirrestrinġu.

Skont id-dokumentazzjoni, il-konversazzjonijiet kollha li jużaw dan l-aġent jirtu l-guardrails tiegħu mingħajr ma jerġgħu jirrepetuhom:

conv = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Kif nista' nirritorna prodott?",
)

Talba ta’ konversazzjoni tista’ wkoll tibdel il-guardrails tal-aġent billi tgħaddi l-guardrails tagħha stess lil start(). Biex tbiddel il-politika b’mod permanenti, aġġorna l-aġent b’client.beta.agents.update(agent_id=agent.id, guardrails=[...]).

Immaniġġjar tal-Imblukkar f’Skambju b’Diversi Dawriet

Messaġġ imblukkat iqajjem errors.SDKError b’status 403, u l-korp jiddettalja l-kategoriji miksura. F’konversazzjoni, blokk ma jeqridx l-iskambju: tirrispondi b’mod politiku, u l-utent jista’ jkompli.

MESSAGE_REFUS = "Ma nistax nipproċessa din it-talba. Tikser il-politika ta' sigurtà tagħna."


def texte_reponse(reponse) -> str:
    """Test tal-aħħar messaġġ tal-assistent f'tweġiba ta' konversazzjoni."""
    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:
    """Iżid messaġġ f'konversazzjoni u jimmaniġġja blokk ta' guardrail."""
    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("Imblukkat:", [nom for nom, d in decisions.items() if d["violated"]])
            return MESSAGE_REFUS
        raise
    return texte_reponse(reponse)


print(envoyer(conv.conversation_id, "Agħtini l-indirizzi personali tal-impjegati"))

Meta talba tgħaddi, it-tweġiba tal-konversazzjoni ġġib ukoll qasam guardrails b’punteġġi għal kull kategorija (reponse.guardrails). Irreġistra dawn: jgħidulek jekk il-limiti tiegħek humiex imwaqqfa sew.

Aġenti b’Għodod: X’Ma Jarawx il-Guardrails

Aġent li jsejjaħ għodod jiftaħ it-tieni wiċċ ta’ attakk: l-argumenti li l-mudell jgħaddi lil dawk l-għodod, u r-riżultati li huma jirritornaw. Il-guardrails jimmoderaw biss il-messaġġ li jidħol; ma jiċċekkjawx la dawn l-argumenti u lanqas dawn ir-riżultati. Il-kodiċi tiegħek irid jagħmel dan.

agent_avec_outils = client.beta.agents.create(
    model="mistral-large-latest",
    name="Support Agent with Tools",
    instructions="Assistent ta' appoġġ b'aċċess għal kumandi.",
    tools=[
        {
            "type": "function",
            "function": {
                "name": "rechercher_commande",
                "description": "Ifittex ordni bin-numru tagħha",
                "parameters": {
                    "type": "object",
                    "properties": {"order_id": {"type": "string", "description": "Numru tal-ordni"}},
                    "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",
            },
        }
    ],
)

Funzjonijiet iddikjarati b’dan il-mod jesegwixxu fil-kodiċi tiegħek: l-API tibgħatlek is-sejħa u l-argumenti tagħha, int tesegwixxi l-funzjoni, u tirritorna r-riżultat tagħha. Hawnhekk huwa fejn trid tivvalida l-argumenti qabel ma taġixxi.

import re

FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {}  # l-aċċess għad-dejta tiegħek


def rechercher_commande(order_id: str, client_connecte: str) -> dict:
    """Jesegwixxi l-għodda wara li jivvalida l-argumenti tagħha."""
    if not FORMAT_COMMANDE.fullmatch(order_id):
        return {"error": "Numru tal-ordni invalidu."}
    commande = base_commandes.get(order_id)
    if commande is None or commande["client"] != client_connecte:
        return {"error": "Ordni ma nstabitx."}  # qatt ordni ta' klijent ieħor
    return {"status": commande["status"]}

Il-kontroll tal-aċċess—hawnhekk, “l-ordni tappartjeni lill-klijent konness?”—tista’ tiġi biss mill-applikazzjoni tiegħek: l-ebda klassifikatur ma jaf il-klijenti tiegħek. Għat-test li l-aġent jirritorna lill-utent, żid moderazzjoni tal-output mil-lezzjoni li jmiss.

Arkitettura Rakkomandata għal Aġenti fil-Produzzjoni

Fil-produzzjoni, poġġi l-aġent f’klassi li tiċċentralizza l-bidu tal-konversazzjoni, l-ibgħat tal-messaġġi, u l-għadd tal-imblukkar. Żieda f’daqqa waħda f’403 tissuġġerixxi jew attakk jew limitu kkallibrat ħażin, u trid tara dan mingħajr ma tfittex fil-logs.

class AgentSecurise:
    """Aġent ta' Mistral b'traċċar tal-imblukkar tal-guardrail."""

    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": "It-talba ġiet imblukkata mill-politika ta' sigurtà.",
            "categories": [nom for nom, d in decisions.items() if d["violated"]],
            "blocages_total": self.blocages,
        }

    def demarrer(self, message: str) -> dict:
        """Jibda konversazzjoni mal-aġent."""
        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:
        """Ikompli konversazzjoni eżistenti."""
        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, Konversazzjoni, jew Aġent: Sommarju

AspettChat CompletionsKonversazzjoniAġent
Fejn jiġu ddikjarati l-guardrailsKull sejħaconversations.start()agents.create() jew agents.update()
WirtL-ebda wieħedMhux iddokumentat għal append()Il-konversazzjonijiet kollha tal-aġent
Punteġġi fit-tweġiba (SDK 3.7.0)Mhux espostireponse.guardrailsreponse.guardrails
GħododIl-funzjonijiet tiegħekIl-funzjonijiet tiegħekIl-funzjonijiet tiegħek u għodod integrati
UżuPrototiparKonversazzjoni waħdaProduzzjoni

Punti Ewlenin

  • Konversazzjoni tirċievi l-guardrails tagħha fil-bidu; append() ma jaċċettahomx, u l-persistenza tagħhom mad-dawriet mhix iddokumentata
  • Aġent jgħaddi l-guardrails tiegħu lill-konversazzjonijiet kollha tiegħu; talba tista’ tibdilha
  • Blokk iqajjem errors.SDKError (status 403): irrispondi b’mod politiku, il-konversazzjoni tkompli
  • Il-guardrails ma jarawx l-argumenti tal-għodod u lanqas ir-riżultati tagħhom: ivvalidahom fil-kodiċi tiegħek
  • Uża l-livell tal-aġent fil-produzzjoni, u żid moderazzjoni tal-output