Guardrails dla agentów Mistral
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opierała się na fikcyjnym formacie guardrails (
enabled, kategoriehate,violence,unpredictable), nieistniejącej metodzieconversation.send()i błędnie twierdziła, że guardrails moderują argumenty narzędzi. Zgodnie z dokumentacją moderują one wyłącznie dane wejściowe. Kod został dostosowany do rzeczywistego API Conversations (start,append) i zweryfikowany względem typów SDKmistralaiw wersji 3.7.0. Źródła: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Zabezpieczanie autonomicznych agentów
Agent niesie ze sobą większe ryzyko niż prosty chatbot: wywołuje narzędzia, przegląda sieć i łączy działania w łańcuchy. Guardrails pokrywają tylko część tego obszaru – konkretnie dane wejściowe. Właśnie dlatego musisz dokładnie wiedzieć, gdzie je umieścić i co pozostawiają bez ochrony.
W tej lekcji podłączysz guardrails do konwersacji, a następnie do agenta, obsłużysz ich blokady w wymianie wieloturowej i zobaczysz, co musisz dodać, aby zabezpieczyć narzędzia.
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 w konwersacji
API Conversations przechowuje historię po stronie serwera. Rozpoczynasz od client.beta.conversations.start(), które akceptuje parametr 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="Jesteś profesjonalnym asystentem HR.",
inputs="Jakie opcje urlopowe są dostępne?",
guardrails=GUARDRAILS_RH,
)
print(conversation.conversation_id)
Następnie kontynuujesz za pomocą client.beta.conversations.append(). Metoda ta nie akceptuje parametru guardrails w SDK 3.7.0, a dokumentacja nie precyzuje, czy te przekazane przy starcie obowiązują dla kolejnych wiadomości. Nie buduj swojego bezpieczeństwa na założeniach: jeśli każda tura musi być filtrowana, użyj agenta, którego guardrails są dziedziczone przez wszystkie jego konwersacje.
Guardrails w agencie
Agent Mistral to zarejestrowana konfiguracja: model, instrukcje, narzędzia i guardrails. Polityka bezpieczeństwa staje się atrybutem agenta, a nie tylko konwencją kodowania.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Agent Obsługi Klienta",
description="Bezpieczny agent obsługi klienta",
instructions=(
"Jesteś agentem obsługi klienta. Surowe zasady: "
"nigdy nie ujawniaj danych osobowych; "
"nie udzielaj porad medycznych ani prawnych; "
"przekieruj do człowieka, jeśli temat jest delikatny."
),
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"Utworzono agenta: {agent.id}")
Zwróć uwagę na spójność między instrukcjami a progami: instrukcje zabraniają udzielania porad medycznych lub prawnych, a progi health i law blokują tego typu żądania, zanim model je w ogóle przeczyta. Instrukcje przekonują; guardrails ograniczają.
Zgodnie z dokumentacją, wszystkie konwersacje korzystające z tego agenta dziedziczą jego guardrails bez konieczności ich powtarzania:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="Jak mogę zwrócić produkt?",
)
Żądanie konwersacji może również nadpisać guardrails agenta, przekazując własne guardrails do metody start(). Aby trwale zmienić politykę, zaktualizuj agenta za pomocą client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Obsługa blokad w wymianie wieloturowej
Zablokowana wiadomość zgłasza błąd errors.SDKError ze statusem 403, a treść odpowiedzi szczegółowo opisuje naruszone kategorie. W konwersacji blokada nie niszczy wymiany: odpowiadasz uprzejmie, a użytkownik może kontynuować.
MESSAGE_REFUS = "Nie mogę przetworzyć tego żądania. Narusza ono naszą politykę bezpieczeństwa."
def tekst_odpowiedzi(odpowiedz) -> str:
"""Tekst ostatniej wiadomości asystenta w odpowiedzi konwersacji."""
for wpis in reversed(odpowiedz.outputs):
if wpis.type == "message.output" and isinstance(wpis.content, str):
return wpis.content
return ""
def wyslij(id_konwersacji: str, wiadomosc: str) -> str:
"""Dodaje wiadomość do konwersacji i obsługuje blokadę guardrails."""
try:
odpowiedz = client.beta.conversations.append(conversation_id=id_konwersacji, inputs=wiadomosc)
except errors.SDKError as e:
if e.status_code == 403:
decyzje = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
print("Zablokowano:", [nazwa for nazwa, d in decyzje.items() if d["violated"]])
return MESSAGE_REFUS
raise
return tekst_odpowiedzi(odpowiedz)
print(wyslij(conv.conversation_id, "Podaj mi osobiste adresy pracowników"))
Gdy żądanie przejdzie, odpowiedź konwersacji również zawiera pole guardrails z wynikami dla każdej kategorii (odpowiedz.guardrails). Loguj je: powiedzą ci, czy twoje progi są dobrze dostrojone.
Agenci z narzędziami: czego guardrails nie widzą
Agent wywołujący narzędzia otwiera drugą powierzchnię ataku: argumenty, które model przekazuje tym narzędziom, oraz wyniki, które one zwracają. Guardrails moderują tylko przychodzącą wiadomość; nie sprawdzają ani tych argumentów, ani tych wyników. Twój kod musi to zrobić.
agent_z_narzedziami = client.beta.agents.create(
model="mistral-large-latest",
name="Agent wsparcia z narzędziami",
instructions="Asystent wsparcia z dostępem do poleceń.",
tools=[
{
"type": "function",
"function": {
"name": "szukaj_zamowienia",
"description": "Wyszukuje zamówienie po jego numerze",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string", "description": "Numer zamówienia"}},
"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",
},
}
],
)
Funkcje zadeklarowane w ten sposób wykonują się w twoim kodzie: API wysyła ci wywołanie i jego argumenty, ty wykonujesz funkcję i zwracasz jej wynik. To właśnie tutaj musisz zwalidować argumenty przed podjęciem działania.
import re
FORMAT_ZAMOWIENIA = re.compile(r"CMD-\d{6}")
baza_zamowien: dict[str, dict] = {} # twój dostęp do danych
def szukaj_zamowienia(order_id: str, klient_polaczony: str) -> dict:
"""Wykonuje narzędzie po zwalidowaniu jego argumentów."""
if not FORMAT_ZAMOWIENIA.fullmatch(order_id):
return {"error": "Nieprawidłowy numer zamówienia."}
zamowienie = baza_zamowien.get(order_id)
if zamowienie is None or zamowienie["klient"] != klient_polaczony:
return {"error": "Nie znaleziono zamówienia."} # nigdy zamówienia innego klienta
return {"status": zamowienie["status"]}
Kontrola dostępu – w tym przypadku „czy zamówienie należy do połączonego klienta?“ – może pochodzić tylko z twojej aplikacji: żaden klasyfikator nie zna twoich klientów. Do tekstu, który agent zwraca użytkownikowi, dodaj moderację wyjścia z następnej lekcji.
Zalecana architektura dla agentów w produkcji
W środowisku produkcyjnym opakuj agenta w klasę, która centralizuje uruchamianie konwersacji, wysyłanie wiadomości i liczenie blokad. Nagły wzrost liczby błędów 403 sygnalizuje albo atak, albo źle skalibrowany próg, a chcesz to zobaczyć bez grzebania w logach.
class BezpiecznyAgent:
"""Agent Mistral ze śledzeniem blokad guardrails."""
def __init__(self, client: Mistral, agent_id: str):
self.client = client
self.agent_id = agent_id
self.blokady = 0
def _zablokowany(self, e: errors.SDKError) -> dict:
self.blokady += 1
decyzje = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Żądanie zablokowane przez politykę bezpieczeństwa.",
"kategorie": [nazwa for nazwa, d in decyzje.items() if d["violated"]],
"laczna_liczba_blokad": self.blokady,
}
def start(self, wiadomosc: str) -> dict:
"""Rozpoczyna konwersację z agentem."""
try:
odpowiedz = self.client.beta.conversations.start(agent_id=self.agent_id, inputs=wiadomosc)
except errors.SDKError as e:
if e.status_code == 403:
return self._zablokowany(e)
raise
return {
"status": "ok",
"conversation_id": odpowiedz.conversation_id,
"content": tekst_odpowiedzi(odpowiedz),
"guardrails": odpowiedz.guardrails,
}
def wyslij(self, id_konwersacji: str, wiadomosc: str) -> dict:
"""Kontynuuje istniejącą konwersację."""
try:
odpowiedz = self.client.beta.conversations.append(conversation_id=id_konwersacji, inputs=wiadomosc)
except errors.SDKError as e:
if e.status_code == 403:
return self._zablokowany(e)
raise
return {"status": "ok", "content": tekst_odpowiedzi(odpowiedz), "guardrails": odpowiedz.guardrails}
Chat Completions, Conversation czy Agent: podsumowanie
| Aspekt | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Gdzie deklarowane są guardrails | Każde wywołanie | conversations.start() | agents.create() lub agents.update() |
| Dziedziczenie | Brak | Nieudokumentowane dla append() | Wszystkie konwersacje agenta |
| Wyniki w odpowiedzi (SDK 3.7.0) | Nieudostępnione | odpowiedz.guardrails | odpowiedz.guardrails |
| Narzędzia | Twoje funkcje | Twoje funkcje | Twoje funkcje i wbudowane narzędzia |
| Zastosowanie | Prototypowanie | Pojedyncza konwersacja | Produkcja |
Kluczowe wnioski
- Konwersacja otrzymuje swoje guardrails przy starcie;
append()ich nie akceptuje, a ich trwałość między turami nie jest udokumentowana - Agent przekazuje swoje guardrails wszystkim swoim konwersacjom; żądanie może je nadpisać
- Blokada zgłasza
errors.SDKError(status403): odpowiedz uprzejmie, konwersacja trwa dalej - Guardrails nie widzą ani argumentów narzędzi, ani ich wyników: waliduj je w swoim kodzie
- W produkcji używaj poziomu agenta i dodaj moderację wyjścia