Zabezpieczanie agentów za pomocą guardrails
Na tej stronie
Zaktualizowano 3 listopada 2026 r. Oba wcześniejsze przykłady przekazywały
guardrails={"enabled": True}, co jest nieistniejącym formatem: oficjalny parametr to lista konfiguracjimoderation_llm_v2z progiem dla każdej kategorii. Tekst wyjaśnia również, co dokumentacja mówi o ich zakresie: moderują one wyłącznie przychodzącą wiadomość. Źródła: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
Bezpieczeństwo agenta nie jest opcjonalne
Autonomiczny agent, który korzysta z narzędzi, ma dostęp do internetu i wykonuje kod, stanowi zagrożenie, jeśli jego działania nie są ograniczone. Różnica względem zwykłego wywołania uzupełnienia (completion) jest fundamentalna, a nie tylko kwestią stopnia: model generujący tekst można skorygować podczas przeglądu, ale agent, który działa, już dokonał działania. Guardrails to zestaw mechanizmów definiujących granice tego, co agent może, a czego nie może robić. Żaden z nich nie jest wystarczający samodzielnie; to ich warstwowanie zapewnia ochronę.
Parametr guardrails
Pierwszy poziom deklarujesz podczas tworzenia agenta.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Secure Agent",
description="Agent with guardrails enabled.",
instructions="""You are a professional assistant.
- Never share personal information
- Never generate inappropriate content
- Refuse out-of-scope requests
- If in doubt, ask for clarification""",
tools=[{"type": "web_search"}],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"pii": 0.2,
"jailbreaking": 0.2,
},
"action": "block",
},
}
],
)
Każda wymieniona kategoria otrzymuje próg od 0 do 1: po jego przekroczeniu wiadomość użytkownika jest odrzucana z błędem 403, zanim dotrze do modelu, a parametr block_on_error odrzuca żądanie również wtedy, gdy sama ewaluacja nie powiedzie się. Zgodnie z dokumentacją, wszystkie konwersacje dla danego agenta dziedziczą te guardrails. Moderują one wyłącznie dane wejściowe: ani wyniki wyszukiwania w sieci, ani odpowiedzi agenta nie są przez nie sprawdzane.
Ten sam parametr jest akceptowany na poziomie konwersacji, gdzie nadpisuje konfigurację agenta. Pozwala to tymczasowo zaostrzyć zachowanie współdzielonego agenta bez konieczności tworzenia jego drugiej wersji dla pojedynczego przypadku użycia.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze this confidential document.",
guardrails=[ # replaces the agent's guardrails for this conversation
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"pii": 0.05, "jailbreaking": 0.1},
"action": "block",
},
}
],
)
Instrukcje: twoja pierwsza linia obrony
Monit systemowy (system prompt) pozostaje najskuteczniejszym dźwignią, ponieważ działa przed każdą decyzją modelu. Dobrze skonstruowany monit bezpieczeństwa wyraźnie oddziela rolę, zakres, zakazy i oczekiwany format.
instructions = """## Role
You are a legal assistant specializing in French labor law.
## Scope
- ONLY French labor law
- Refuse any out-of-scope questions (tax, real estate, criminal law, etc.)
## Strict Prohibitions
- NEVER give definitive legal advice
- NEVER draft legal documents without a disclaimer
- NEVER share information about other clients
- ALWAYS mention that a lawyer must validate
## Format
- Cite relevant legal articles
- Clearly state the limits of your response
- Always propose consulting a professional"""
Zwróć uwagę, co robi sekcja „Scope“: nie mówi tylko, czym agent się zajmuje, ale wyraźnie wymienia sąsiednie domeny, których musi odmówić. Bez tej enumeracji pytanie podatkowe związane z wypowiedzeniem mogłoby się prześlizgnąć, ponieważ wystarczająco przypomina prawo pracy, by model zaangażował się w odpowiedź. Sekcja „Strict Prohibitions“ podąża tą samą logiką: formułuje zakazy, a nie rekomendacje. Agentowi kazano być „ostrożnym“, sam kalibruje swoją ostrożność; agentowi zabroniono tworzenia dokumentów bez zastrzeżenia – stosuje regułę.
Zasada najmniejszych uprawnień
Każde zadeklarowane narzędzie to zdolność, którą agent może zmobilizować w niewłaściwym momencie. Porównaj te dwie konfiguracje.
# Too many tools — large attack surface
dangerous_agent = client.beta.agents.create(
model="mistral-large-latest",
name="do-it-all-agent",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"},
{"type": "image_generation"},
{"type": "document_library", "library_ids": [lib.id]}
]
)
# Principle of least privilege — only what is necessary
secure_agent = client.beta.agents.create(
model="mistral-large-latest",
name="documentation-agent",
tools=[{"type": "document_library", "library_ids": [lib.id]}]
)
Drugi agent nie może wyjść do sieci, by pobrać informacje brakujące w twoich dokumentach, ani wykonywać kodu na treści, której nie przejrzałeś. Nie jest to ograniczenie, które cię dotyka; to gwarancja, że jego odpowiedzi pochodzą z twojej bazy wiedzy i znikąd indziej. Zadawaj sobie pytanie narzędzie po narzędziu – jeśli nie znajdziesz scenariusza, w którym agent go potrzebuje, usuń je.
Filtrowanie przekazań (handoffs)
W systemie wieloagentowym tryb klienta daje ci prawo weta wobec każdego przekazania. Wystarczy biała lista, by uniemożliwić jednemu agentowi dotarcie do innego ścieżką, której nie przewidziałeś.
response = client.beta.conversations.start(
agent_id=router.id,
inputs=user_query,
handoff_execution="client"
)
ALLOWED_AGENTS = {research.id, analyst.id} # Whitelist
for entry in response.outputs:
if entry.type == "agent.handoff":
if entry.next_agent_id not in ALLOWED_AGENTS:
print(f"BLOCKED: unauthorized handoff to {entry.next_agent_id}")
continue
# Continue with the authorized agent
Biała lista żyje w twoim kodzie, a nie w konfiguracji agenta: pozostaje ważna, nawet jeśli ktoś doda cel przekazania do routera bez powiadomienia cię.
Nie przechowuj tego, co nie musi być przechowywane
W przypadku danych wrażliwych najlepszą ochroną jest nieprzechowywanie niczego.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Ustawienie to jest podejmowane dla każdej konwersacji z osobna, co pozwala zachować historię zwykłych wymian, jednocześnie przetwarzając treści poufne w trybie efemerycznym.
Moderacja na wejściu
Elegancką odmianą jest umieszczenie agenta moderującego na czele łańcucha: bada on żądanie i przekazuje je do specjalisty tylko wtedy, gdy jest ono akceptowalne.
moderator = client.beta.agents.create(
model="mistral-large-latest",
name="moderator",
description="Checks that requests are appropriate.",
instructions="""Analyze the user request:
- If appropriate: transfer to the specialist
- If inappropriate: politely reply that the request is not supported
- If ambiguous: ask for clarification"""
)
specialist = client.beta.agents.create(
model="mistral-large-latest",
name="specialist",
description="Handles validated requests.",
tools=[{"type": "web_search"}]
)
moderator = client.beta.agents.update(
agent_id=moderator.id,
handoffs=[specialist.id]
)
Wartość tego wzorca leży w rozdzieleniu ról: moderator nie ma narzędzi i robi tylko jedną rzecz, więc złośliwe żądanie, które odrzuci, nigdy nie dotrze do agenta, który potrafi działać.
Dostrajanie generowania
Parametry uzupełnienia (completion) również przyczyniają się do bezpieczeństwa z prostego powodu: halucynująca odpowiedź to ryzyko, a kreatywność jest jego pożywką.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Factual Agent",
description="Factual and conservative agent.",
completion_args={
"temperature": 0.1, # Very low creativity
"top_p": 0.85, # Restricted nucleus
"max_tokens": 1024 # Short responses
}
)
Temperatura 0,1 w połączeniu z top_p równym 0,85 pozostawia modelowi bardzo mało swobody: w przypadku pytania, na które odpowiedź znajduje się w twoich dokumentach, model ją pobiera, zamiast haftować wariant. Limit 1024 tokenów odgrywa podobną rolę, ponieważ odpowiedź, która staje się zbyt długa, w końcu odbiega od udokumentowanego zakresu i produkuje wypełniacze. Ustawienia te oczywiście nie pasują do agenta kreatywnego, ale są domyślną konfiguracją dla każdego agenta, od którego oczekuje się podawania faktów – asystenta prawnego, wsparcia technicznego, eksperta produktowego.
Przed wejściem na produkcję
Mechanizmy te są ważne tylko wtedy, gdy są warstwowane, a ostateczna kontrola sprowadza się do kilku weryfikacji. Instrukcje muszą wyraźnie definiować zakres i zakazy, a agent musi mieć tylko narzędzia ściśle niezbędne do jego zadania. Sprawdź, czy guardrails są włączone i czy krytyczne przepływy pracy działają w trybie klienta, aby żadne przekazanie nie zostało wykonane bez twojej zgody. Upewnij się, że store=False towarzyszy każdej konwersacji obejmującej dane wrażliwe oraz że temperatura pozostaje niska wszędzie tam, gdzie od agenta oczekuje się faktograficzności. Na koniec umieść agenta moderującego na początku łańcucha, aby nieakceptowalne żądania nigdy nie dotarły do agentów, które potrafią działać.
Kluczowe wnioski
- Guardrails konfiguruje się na poziomie agenta i/lub konwersacji
- Instrukcje to twoja pierwsza linia obrony – bądź wyraźny co do zakazów
- Stosuj zasadę najmniejszych uprawnień: dawaj tylko niezbędne narzędzia
- Tryb klienta pozwala walidować i blokować nieautoryzowane przekazania
- W produkcji: moderacja na wejściu, logowanie, biała lista agentów,
store=Falsedla danych wrażliwych