Guardrails għall-Aġenti ta' Mistral
F'din il-paġna
Lezzjon miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddependi fuq format fittizju ta’ guardrail (
enabled, kategorijihate,violence,unpredictable), metoduconversation.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-SDKmistralaiverż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
| Aspett | Chat Completions | Konversazzjoni | Aġent |
|---|---|---|---|
| Fejn jiġu ddikjarati l-guardrails | Kull sejħa | conversations.start() | agents.create() jew agents.update() |
| Wirt | L-ebda wieħed | Mhux iddokumentat għal append() | Il-konversazzjonijiet kollha tal-aġent |
| Punteġġi fit-tweġiba (SDK 3.7.0) | Mhux esposti | reponse.guardrails | reponse.guardrails |
| Għodod | Il-funzjonijiet tiegħek | Il-funzjonijiet tiegħek | Il-funzjonijiet tiegħek u għodod integrati |
| Użu | Prototipar | Konversazzjoni waħda | Produzzjoni |
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(status403): 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