Przejdź do głównej treści
Polski— Wybierz język
Menu

Zabezpieczanie agentów za pomocą guardrails

Lekcja 17 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Bezpieczeństwo agenta nie jest opcjonalne
  2. Parametr guardrails
  3. Instrukcje: twoja pierwsza linia obrony
  4. Zasada najmniejszych uprawnień
  5. Filtrowanie przekazań (handoffs)
  6. Nie przechowuj tego, co nie musi być przechowywane
  7. Moderacja na wejściu
  8. Dostrajanie generowania
  9. Przed wejściem na produkcję
  10. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. Oba wcześniejsze przykłady przekazywały guardrails={"enabled": True}, co jest nieistniejącym formatem: oficjalny parametr to lista konfiguracji moderation_llm_v2 z 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 · SDK mistralai 3.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=False dla danych wrażliwych