Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Guardrail per gli Agenti Mistral

Lezione 4 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Mettere in sicurezza gli agenti autonomi
  2. Guardrail su una conversazione
  3. Guardrail su un agente
  4. Gestione dei blocchi in uno scambio multi-turno
  5. Agenti con strumenti: cosa i guardrail non vedono
  6. Architettura consigliata per gli agenti in produzione
  7. Chat Completions, Conversation o Agent: riepilogo
  8. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente si basava su un formato di guardrail fittizio (enabled, categorie hate, violence, unpredictable), su un metodo conversation.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 SDK mistralai versione 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}
AspettoChat CompletionsConversationAgent
Dove si dichiarano i guardrailOgni chiamataconversations.start()agents.create() o agents.update()
EreditarietàNessunaNon documentata per append()Tutte le conversazioni dell’agente
Punteggi nella risposta (SDK 3.7.0)Non espostireponse.guardrailsreponse.guardrails
StrumentiLe tue funzioniLe tue funzioniLe tue funzioni e strumenti integrati
UtilizzoPrototipazioneConversazione una tantumProduzione

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