Φράγματα ασφαλείας για πράκτορες Mistral
Σε αυτήν τη σελίδα
- Ασφάλιση αυτόνομων πρακτόρων
- Φράγματα ασφαλείας σε μια Συνομιλία
- Φράγματα ασφαλείας σε έναν Πράκτορα
- Διαχείριση αποκλεισμών σε ανταλλαγή πολλαπλών γύρων
- Πράκτορες με εργαλεία: Τι δεν βλέπουν τα φράγματα ασφαλείας
- Προτεινόμενη αρχιτεκτονική για πράκτορες σε παραγωγή
- Chat Completions, Συνομιλία ή Πράκτορας: Σύνοψη
- Βασικά σημεία
Μάθημα αναθεωρημένο στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση βασιζόταν σε μια πλασματική μορφή φράγματος ασφαλείας (
enabled, κατηγορίεςhate,violence,unpredictable), σε μια ανύπαρκτη μέθοδοconversation.send()και ισχυριζόταν λανθασμένα ότι τα φράγματα ασφαλείας moderάρουν τα ορίσματα των εργαλείων. Σύμφωνα με την τεκμηρίωση, αυτά moderάρουν μόνο την είσοδο. Ο κώδικας ακολουθεί πλέον το πραγματικό API Συνομιλιών (start,append) και έχει επαληθευτεί έναντι των τύπων SDKmistralaiέκδοσης 3.7.0. Πηγές: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Ασφάλιση αυτόνομων πρακτόρων
Ένας πράκτορας ενέχει μεγαλύτερο ρίσκο από ένα απλό chatbot: καλεί εργαλεία, περιηγείται στον ιστό και αλυσιδώνει ενέργειες. Τα φράγματα ασφαλείας καλύπτουν μόνο μέρος αυτής της επιφάνειας—συγκεκριμένα, την είσοδο. Αυτός είναι ακριβώς ο λόγος για τον οποίο πρέπει να γνωρίζετε με ακρίβεια πού να τα τοποθετήσετε και τι αφήνουν ακάλυπτο.
Σε αυτό το μάθημα, θα συνδέσετε φράγματα ασφαλείας σε μια συνομιλία και στη συνέχεια σε έναν πράκτορα, θα διαχειριστείτε τους αποκλεισμούς τους σε μια ανταλλαγή πολλαπλών γύρων και θα δείτε τι πρέπει να προσθέσετε για να ασφαλίσετε τα εργαλεία.
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"])
Φράγματα ασφαλείας σε μια Συνομιλία
Το API Συνομιλιών διατηρεί το ιστορικό στον διακομιστή. Ξεκινάτε με το client.beta.conversations.start(), το οποίο δέχεται το 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)
Στη συνέχεια συνεχίζετε με το client.beta.conversations.append(). Αυτή η μέθοδος δεν δέχεται την παράμετρο guardrails στο SDK 3.7.0 και η τεκμηρίωση δεν αναφέρει εάν αυτές που περνούνται κατά την εκκίνηση ισχύουν για τα επόμενα μηνύματα. Μην χτίζετε την ασφάλειά σας σε μια υπόθεση: αν κάθε γύρος πρέπει να φιλτράρεται, χρησιμοποιήστε έναν πράκτορα, του οποίου τα φράγματα ασφαλείας κληρονομούνται από όλες τις συνομιλίες του.
Φράγματα ασφαλείας σε έναν Πράκτορα
Ένας πράκτορας Mistral είναι μια καταχωρημένη διαμόρφωση: μοντέλο, οδηγίες, εργαλεία και φράγματα ασφαλείας. Η πολιτική ασφαλείας γίνεται ένα χαρακτηριστικό του πράκτορα και όχι μια σύμβαση κωδικοποίησης.
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}")
Σημειώστε τη συνοχή μεταξύ οδηγιών και κατωφλίων: οι οδηγίες απαγορεύουν την παροχή ιατρικών ή νομικών συμβουλών, και τα κατώφλια health και law μπλοκάρουν αιτήματα αυτού του τύπου πριν καν τα διαβάσει το μοντέλο. Οι οδηγίες πείθουν· τα φράγματα ασφαλείας περιορίζουν.
Σύμφωνα με την τεκμηρίωση, όλες οι συνομιλίες που χρησιμοποιούν αυτόν τον πράκτορα κληρονομούν τα φράγματα ασφαλείας του χωρίς να χρειάζεται να τα επαναλάβετε:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="How can I return a product?",
)
Ένα αίτημα συνομιλίας μπορεί επίσης να παρακάμψει τα φράγματα ασφαλείας του πράκτορα περνώντας τα δικά του guardrails στο start(). Για να αλλάξετε μόνιμα την πολιτική, ενημερώστε τον πράκτορα με client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Διαχείριση αποκλεισμών σε ανταλλαγή πολλαπλών γύρων
Ένα μπλοκαρισμένο μήνυμα προκαλεί errors.SDKError με κωδικό κατάστασης 403, και το σώμα λεπτομερεί τις παραβιασμένες κατηγορίες. Σε μια συνομιλία, ένας αποκλεισμός δεν καταστρέφει την ανταλλαγή: απαντάτε ευγενικά και ο χρήστης μπορεί να συνεχίσει.
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"))
Όταν ένα αίτημα περάσει, η απάντηση της συνομιλίας μεταφέρει επίσης ένα πεδίο guardrails με βαθμολογίες για κάθε κατηγορία (reponse.guardrails). Καταγράψτε τες: σας λένε εάν τα κατώφλιά σας είναι σωστά ρυθμισμένα.
Πράκτορες με εργαλεία: Τι δεν βλέπουν τα φράγματα ασφαλείας
Ένας πράκτορας που καλεί εργαλεία ανοίγει μια δεύτερη επιφάνεια επίθεσης: τα ορίσματα που περνά το μοντέλο σε αυτά τα εργαλεία και τα αποτελέσματα που επιστρέφουν. Τα φράγματα ασφαλείας moderάρουν μόνο το εισερχόμενο μήνυμα· δεν ελέγχουν ούτε αυτά τα ορίσματα ούτε αυτά τα αποτελέσματα. Ο κώδικάς σας πρέπει να το κάνει αυτό.
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",
},
}
],
)
Οι συναρτήσεις που δηλώνονται με αυτόν τον τρόπο εκτελούνται στον κώδικά σας: το API σας στέλνει την κλήση και τα ορίσματά της, εσείς εκτελείτε τη συνάρτηση και επιστρέφετε το αποτέλεσμά της. Εδώ είναι που πρέπει να επικυρώσετε τα ορίσματα πριν ενεργήσετε.
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"]}
Ο έλεγχος πρόσβασης—εδώ, «ανήκει η παραγγελία στον συνδεδεμένο πελάτη;»—μπορεί να προέλθει μόνο από την εφαρμογή σας: κανένας ταξινομητής δεν γνωρίζει τους πελάτες σας. Για το κείμενο που επιστρέφει ο πράκτορας στον χρήστη, προσθέστε moderation εξόδου από το επόμενο μάθημα.
Προτεινόμενη αρχιτεκτονική για πράκτορες σε παραγωγή
Σε παραγωγή, τυλίξτε τον πράκτορα σε μια κλάση που κεντροποιεί την εκκίνηση της συνομιλίας, την αποστολή μηνυμάτων και την καταμέτρηση αποκλεισμών. Μια ξαφνική αύξηση στα 403 σηματοδοτεί είτε μια επίθεση είτε ένα κακώς βαθμονομημένο κατώφλι, και θέλετε να το δείτε αυτό χωρίς να ψάχνετε στα αρχεία καταγραφής.
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, Συνομιλία ή Πράκτορας: Σύνοψη
| Πτυχή | Chat Completions | Συνομιλία | Πράκτορας |
|---|---|---|---|
| Πού δηλώνονται τα φράγματα ασφαλείας | Σε κάθε κλήση | conversations.start() | agents.create() ή agents.update() |
| Κληρονομικότητα | Καμία | Δεν τεκμηριώνεται για το append() | Όλες οι συνομιλίες του πράκτορα |
| Βαθμολογίες στην απάντηση (SDK 3.7.0) | Δεν εκτίθενται | reponse.guardrails | reponse.guardrails |
| Εργαλεία | Οι συναρτήσεις σας | Οι συναρτήσεις σας | Οι συναρτήσεις σας και ενσωματωμένα εργαλεία |
| Χρήση | Πρωτοτυποποίηση | Εφάπαξ συνομιλία | Παραγωγή |
Βασικά σημεία
- Μια συνομιλία λαμβάνει τα φράγματα ασφαλείας της κατά την εκκίνηση· το
append()δεν τα δέχεται και η επιμονή τους across turns δεν είναι τεκμηριωμένη - Ένας πράκτορας περνά τα φράγματα ασφαλείας του σε όλες τις συνομιλίες του· ένα αίτημα μπορεί να τα παρακάμψει
- Ένας αποκλεισμός προκαλεί
errors.SDKError(κατάσταση403): απαντήστε ευγενικά, η συνομιλία συνεχίζεται - Τα φράγματα ασφαλείας δεν βλέπουν ούτε τα ορίσματα των εργαλείων ούτε τα αποτελέσματά τους: επικυρώστε τα στον κώδικά σας
- Χρησιμοποιήστε το επίπεδο πράκτορα σε παραγωγή και προσθέστε moderation εξόδου