Salt la conținutul principal
Română— Alege o limbă
Meniu

Securizarea agenților cu guardrails

Lecția 17 din 18 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Securitatea agenților nu este opțională
  2. Parametrul guardrails
  3. Instrucțiuni: prima linie de apărare
  4. Principiul privilegiului minim
  5. Filtrarea handoff-urilor
  6. Nu stocați ceea ce nu trebuie stocat
  7. Moderare în amonte
  8. Ajustarea generării
  9. Înainte de a merge în producție
  10. Puncte cheie

Actualizat la 3 noiembrie 2026. Ambele exemple anterioare transmiteau guardrails={"enabled": True}, un format care nu există: parametrul oficial este o listă de configurații moderation_llm_v2, cu un prag per categorie. Textul clarifică, de asemenea, ceea ce afirmă documentația despre domeniul lor de aplicare: acestea modulează doar mesajul incoming. Surse: Moderation & Guardrailing · Agents & Conversations · SDK mistralai 3.7.0.

Securitatea agenților nu este opțională

Un agent autonom care utilizează instrumente, accesează internetul și execută cod prezintă un risc dacă acțiunile sale nu sunt constrânse. Diferența față de un apel simplu de completare este fundamentală, nu doar o chestiune de grad: un model care produce text poate fi corectat la revizuire, dar un agent care acționează a acționat deja. Guardrails reprezintă ansamblul de mecanisme care definesc limitele a ceea ce un agent poate și nu poate face. Niciunul dintre ele nu este suficient de unul singur; stratificarea lor este cea care asigură protecția.

Parametrul guardrails

Primul nivel este declarat la crearea agentului.

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",
            },
        }
    ],
)

Fiecare categorie listată primește un prag de la 0 la 1: dincolo de acest punct, mesajul utilizatorului este respins cu o eroare 403 înainte de a ajunge la model, iar block_on_error respinge, de asemenea, cererea dacă evaluarea în sine eșuează. Conform documentației, toate conversațiile pentru agent moștenesc aceste guardrails. Acestea modulează doar input-ul: nici rezultatele căutării pe web, nici răspunsul agentului nu sunt verificate de ele.

Același parametru este acceptat la nivelul conversației, unde suprascrie configurația agentului. Acest lucru vă permite să strângeți temporar comportamentul unui agent partajat fără a crea o a doua versiune a acelui agent pentru un singur caz de utilizare.

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",
            },
        }
    ],
)

Instrucțiuni: prima linie de apărare

Promptul de sistem rămâne pârghia cea mai eficientă deoarece acționează înainte de orice decizie a modelului. Un prompt de securitate bine construit separă clar rolul, domeniul de aplicare, interdicțiile și formatul așteptat.

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"""

Observați ce face secțiunea „Scope“: nu spune doar cu ce se ocupă agentul, ci numește explicit domeniile adiacente pe care trebuie să le refuze. Fără această enumerare, o întrebare fiscală legată de o concediere ar putea să scape deoarece seamănă suficient cu dreptul muncii pentru ca modelul să se implice. Secțiunea „Strict Prohibitions“ urmează aceeași logică: formulează refuzuri, nu recomandări. Un agent căruia i se spune să fie „prudent“ își calibrează propria prudență; un agent căruia i se interzice redactarea fără un disclaimer aplică o regulă.

Principiul privilegiului minim

Fiecare instrument declarat este o capacitate pe care agentul o poate mobiliza la momentul nepotrivit. Comparați aceste două configurații.

# 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]}]
)

Al doilea agent nu poate merge online pentru a prelua informații lipsă din documentele dumneavoastră, nici nu poate executa cod pe conținut pe care nu l-ați revizuit. Aceasta nu este o limitare pe care o suferiți; este garanția că răspunsurile sale provin din baza dumneavoastră de cunoștințe și din niciun alt loc. Întrebați-vă instrument cu instrument – dacă nu găsiți un scenariu în care agentul are nevoie de el, eliminați-l.

Filtrarea handoff-urilor

Într-un sistem multi-agent, modul client vă oferă drept de veto asupra fiecărui handoff. O listă albă este suficientă pentru a împiedica un agent să ajungă la altul printr-o cale pe care nu ați anticipat-o.

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

Lista albă trăiește în codul dumneavoastră, nu în configurația agentului: aceasta rămâne valabilă chiar dacă cineva adaugă o țintă de handoff la router fără să vă通知eze.

Nu stocați ceea ce nu trebuie stocat

Pentru datele sensibile, cea mai bună protecție este să nu stocați nimic.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Confidential data: Q1 2026 financial report...",
    store=False  # Nothing persists
)

Această setare se decide per conversație, ceea ce vă permite să păstrați istoricul schimburilor obișnuite, procesând în același timp conținutul confidențial în mod efemer.

Moderare în amonte

O variantă elegantă este plasarea unui agent de moderare la capătul lanțului: acesta examinează cererea și o transferă specialistului doar dacă este acceptabilă.

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]
)

Valoarea acestui model constă în separarea rolurilor: moderatorul nu are instrumente și face un singur lucru, astfel încât o cerere malițioasă pe care o respinge nu ajunge niciodată la agentul care știe să acționeze.

Ajustarea generării

Parametrii de completare contribuie, de asemenea, la securitate dintr-un motiv simplu: un răspuns halucinat este un risc, iar creativitatea este terenul său de reproducere.

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
    }
)

O temperatură de 0.1 cuplată cu un top_p de 0.85 lasă modelului foarte puțină libertate: pentru o întrebare al cărei răspuns apare în documentele dumneavoastră, acesta îl recuperează în loc să brodeze o variantă. Limita de 1024 de tokeni joacă un rol similar, deoarece un răspuns care crește prea mult se abate în cele din urmă de la domeniul documentat și produce conținut de umplutură. Aceste setări nu se potrivesc evident unui agent creativ, dar sunt configurația implicită pentru orice agent care trebuie să enunțe fapte – asistent juridic, suport tehnic, expert produs.

Înainte de a merge în producție

Aceste mecanisme sunt valabile doar atunci când sunt stratificate, iar verificarea finală se reduce la câteva verificări. Instrucțiunile trebuie să definească explicit domeniul de aplicare și interdicțiile, iar agentul trebuie să aibă doar instrumentele strict necesare pentru sarcina sa. Verificați dacă guardrails sunt activate și dacă fluxurile de lucru critice rulează în modul client, astfel încât niciun handoff să nu se execute fără aprobarea dumneavoastră. Asigurați-vă că store=False însoțește orice conversație care implică date sensibile și că temperatura rămâne scăzută oriunde se așteaptă ca agentul să rămână factual. În final, plasați un agent de moderare în fața lanțului, astfel încât cererile inacceptabile să nu ajungă niciodată la agenții care știu să acționeze.

Puncte cheie

  • Guardrails sunt configurate la nivelul agentului și/sau al conversației
  • Instrucțiunile sunt prima linie de apărare – fiți expliciți privind interdicțiile
  • Aplicați principiul privilegiului minim: oferiți doar instrumentele necesare
  • Modul client vă permite să validați și să blocați handoff-urile neautorizate
  • În producție: moderare în amonte, jurnalizare, listă albă de agenți, store=False pentru datele sensibile