Guardrail per gli Agenti Mistral
In questa pagina
- Mettere in sicurezza gli agenti autonomi
- Guardrail su una conversazione
- Guardrail su un agente
- Gestione dei blocchi in uno scambio multi-turno
- Agenti con strumenti: cosa i guardrail non vedono
- Architettura consigliata per gli agenti in produzione
- Chat Completions, Conversation o Agent: riepilogo
- Punti chiave
Lezione riscritta il 3 novembre 2026. La versione precedente si basava su un formato di guardrail fittizio (
enabled, categoriehate,violence,unpredictable), su un metodoconversation.send()inesistente e affermava erroneamente che i guardrail moderassero gli argomenti degli strumenti. Secondo la documentazione, essi moderano solo l’input. Il codice ora segue fedelmente le API Conversations reali (start,append) ed è stato verificato rispetto ai tipi SDKmistralaiversione 3.7.0. Fonti: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Mettere in sicurezza gli agenti autonomi
Un agente comporta rischi maggiori rispetto a un semplice chatbot: chiama strumenti, naviga sul web e concatena azioni. I guardrail coprono solo una parte di questa superficie d’attacco, nello specifico l’input. È proprio per questo che devi sapere esattamente dove posizionarli e cosa lasciano scoperto.
In questa lezione, imparerai ad associare i guardrail a una conversazione e poi a un agente, a gestire i loro blocchi in uno scambio multi-turno e a vedere cosa devi aggiungere per mettere in sicurezza gli strumenti.
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"])
Guardrail su una conversazione
Le API Conversations mantengono la cronologia sul server. Inizi con client.beta.conversations.start(), che accetta il parametro 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)
Prosegui poi con client.beta.conversations.append(). Questo metodo non accetta un parametro guardrails nell’SDK 3.7.0 e la documentazione non specifica se quelli passati all’avvio si applichino ai messaggi successivi. Non basare la tua sicurezza su un’ipotesi: se ogni turno deve essere filtrato, usa un agente, i cui guardrail vengono ereditati da tutte le sue conversazioni.
Guardrail su un agente
Un agente Mistral è una configurazione registrata: modello, istruzioni, strumenti e guardrail. La politica di sicurezza diventa un attributo dell’agente piuttosto che una convenzione di codifica.
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}")
Nota la coerenza tra istruzioni e soglie: le istruzioni vietano di fornire consigli medici o legali, mentre le soglie health e law bloccano le richieste di questo tipo prima ancora che il modello le legga. Le istruzioni persuadono; i guardrail vincolano.
Secondo la documentazione, tutte le conversazioni che utilizzano questo agente ereditano i suoi guardrail senza bisogno di ripeterli:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Una richiesta di conversazione può anche sovrascrivere i guardrail dell’agente passando i propri guardrails a start(). Per modificare la politica in modo permanente, aggiorna l’agente con client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Gestione dei blocchi in uno scambio multi-turno
Un messaggio bloccato solleva un errors.SDKError con stato 403 e il corpo della risposta dettaglia le categorie violate. In una conversazione, un blocco non distrugge lo scambio: rispondi educatamente e l’utente può continuare.
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"))
Quando una richiesta passa, la risposta della conversazione include anche un campo guardrails con i punteggi per ogni categoria (reponse.guardrails). Registra questi dati: ti dicono se le tue soglie sono calibrate correttamente.
Agenti con strumenti: cosa i guardrail non vedono
Un agente che chiama strumenti apre una seconda superficie d’attacco: gli argomenti che il modello passa a tali strumenti e i risultati che questi restituiscono. I guardrail moderano solo il messaggio in arrivo; non controllano né questi argomenti né questi risultati. Deve farlo il tuo codice.
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",
},
}
],
)
Le funzioni dichiarate in questo modo vengono eseguite nel tuo codice: l’API ti invia la chiamata e i suoi argomenti, tu esegui la funzione e restituisci il risultato. È qui che devi convalidare gli argomenti prima di agire.
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"]}
Il controllo degli accessi — qui, «l’ordine appartiene al cliente connesso?» — può provenire solo dalla tua applicazione: nessun classificatore conosce i tuoi clienti. Per il testo che l’agente restituisce all’utente, aggiungi la moderazione dell’output trattata nella prossima lezione.
Architettura consigliata per gli agenti in produzione
In produzione, incapsula l’agente in una classe che centralizzi l’avvio delle conversazioni, l’invio dei messaggi e il conteggio dei blocchi. Un picco improvviso di errori 403 segnala o un attacco o una soglia mal calibrata, e vuoi poterlo rilevare senza dover scavare nei log.
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 o Agent: riepilogo
| Aspetto | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Dove si dichiarano i guardrail | Ogni chiamata | conversations.start() | agents.create() o agents.update() |
| Ereditarietà | Nessuna | Non documentata per append() | Tutte le conversazioni dell’agente |
| Punteggi nella risposta (SDK 3.7.0) | Non esposti | reponse.guardrails | reponse.guardrails |
| Strumenti | Le tue funzioni | Le tue funzioni | Le tue funzioni e strumenti integrati |
| Utilizzo | Prototipazione | Conversazione una tantum | Produzione |
Punti chiave
- Una conversazione riceve i suoi guardrail all’avvio;
append()non li accetta e la loro persistenza tra i turni non è documentata - Un agente trasmette i suoi guardrail a tutte le sue conversazioni; una richiesta può sovrascriverli
- Un blocco solleva
errors.SDKError(stato403): rispondi educatamente, la conversazione continua - I guardrail non vedono né gli argomenti degli strumenti né i loro risultati: convalidali nel tuo codice
- Usa il livello agente in produzione e aggiungi la moderazione dell’output