Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Issikura l-aġenti b'guardrails

Lezzjoni 17 / 18 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Is-sigurtà tal-aġenti mhix għażla
  2. Il-parametru guardrails
  3. Istruzzjonijiet: l-ewwel linja ta’ difiża tiegħek
  4. Il-prinċipju tal-inqas privileġġ
  5. Iffiltra l-handoffs
  6. Taħżinx dak li m’għandux bżonn jinħażen
  7. Modera ‘l fuq mill-katina (Upstream)
  8. Aġġusta l-ġenerazzjoni
  9. Qabel ma tmur għall-produzzjoni
  10. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026. Iż-żewġ eżempji preċedenti għaddew guardrails={"enabled": True}, format li ma jeżistix: il-parametru uffiċjali huwa lista ta’ konfigurazzjonijiet moderation_llm_v2, b’limitu (threshold) għal kull kategorija. It-test jiċċara wkoll dak li tgħid id-dokumentazzjoni dwar l-ambitu tagħhom: huma jimmoderaw biss il-messaġġ li jkun qed jidħol. Sorsi: Moderation & Guardrailing · Agents & Conversations · SDK mistralai 3.7.0.

Is-sigurtà tal-aġenti mhix għażla

Aġent awtonomu li juża għodod, jaċċessa l-internet, u jesegwixxi kodiċi jpoġġi f’riskju jekk l-azzjonijiet tiegħu ma jkunux imrażżna. Id-differenza minn sejħa sempliċi ta’ tlestija (completion) hija fundamentali, mhix sempliċiment kwistjoni ta’ grad: mudell li jipproduċi test jista’ jiġi kkoreġut wara reviżjoni, iżda aġent li jaġixxi diġà għamel hekk. Il-guardrails huma s-sett ta’ mekkaniżmi li jiddefinixxu l-fruntieri ta’ dak li aġent jista’ u ma jistax jagħmel. L-ebda wieħed minnhom mhu biżżejjed waħdu; hija s-sovrappożizzjoni (layering) tagħhom li tipprovdi protezzjoni.

Il-parametru guardrails

L-ewwel livell jiġi ddikjarat meta toħloq l-aġent.

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

Kull kategorija elenkata tirċievi limitu (threshold) minn 0 sa 1: lil hinn minn dan il-punt, il-messaġġ tal-utent jiġi miċħud b’żball 403 qabel ma jilħaq il-mudell, u block_on_error jiċħad ukoll it-talba jekk l-evalwazzjoni nnifisha tfalli. Skont id-dokumentazzjoni, il-konversazzjonijiet kollha għall-aġent jirtu dawn il-guardrails. Huma jimmoderaw biss l-input: la r-riżultati tat-tiftix fuq il-web u lanqas ir-risposta tal-aġent jiġu vverifikati minnhom.

L-istess parametru huwa aċċettat fil-livell tal-konversazzjoni, fejn jissostitwixxi l-konfigurazzjoni tal-aġent. Dan jippermettilek issaħħaħ temporanjament l-imġiba ta’ aġent kondiviż mingħajr ma toħloq verżjoni sekonda ta’ dak l-aġent għal każ ta’ użu wieħed.

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

Istruzzjonijiet: l-ewwel linja ta’ difiża tiegħek

Il-prompt tas-sistema jibqa’ l-aktar leva effettiva għax taġixxi qabel kwalunkwe deċiżjoni tal-mudell. Prompt tas-sigurtà mibni sew jissepara b’mod ċar ir-rwol, l-ambitu, il-projbizzjonijiet u l-format mistenni.

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

Innota x’jagħmel is-sezzjoni “Scope”: ma tgħidx biss dak li l-aġent jittratta; tissemma espliċitament id-dominji adjaċenti li għandu jirrifjuta. Mingħajr din l-enumerazzjoni, mistoqsija dwar it-taxxa relatata ma’ tkeċċija tista’ tgħaddi għax tixbah biżżejjed il-liġi tax-xogħol biex il-mudell jidħol fiha. Is-sezzjoni “Strict Prohibitions” issegwi l-istess loġika: tifformula rifjuti, mhux rakkomandazzjonijiet. Aġent li jingħatalu ordni li jkun “kawt” jikkalibra l-kawtela tiegħu stess; aġent li huwa pprojbit milli jabbozza mingħajr disclaimer japplika regola.

Il-prinċipju tal-inqas privileġġ

Kull għodda ddikjarata hija kapaċità li l-aġent jista’ jimobilizza fil-ħin żbaljat. Qabbel dawn iż-żewġ konfigurazzjonijiet.

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

It-tieni aġent ma jistax imur online biex iġib informazzjoni nieqsa mid-dokumenti tiegħek, u lanqas jesegwixxi kodiċi fuq kontenut li ma rrevedejtx. Din mhix limitazzjoni li tbati minnha; hija l-garanzija li t-tweġibiet tiegħu ġejjin mill-bażi tal-għarfien tiegħek u minn mkien ieħor. Staqsi lilek innifsek għodda wara għodda—jekk ma tistax issib xenarju fejn l-aġent jeħtieġha, neħħiha.

Iffiltra l-handoffs

F’sistema multi-aġent, il-modalità tal-klijent (client mode) tagħtiek dritt ta’ veto fuq kull handoff. Lista bajda (whitelist) hija biżżejjed biex tipprevjeni li aġent wieħed jilħaq ieħor permezz ta’ mogħdija li ma stennejtx.

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

Il-lista bajda tgħix fil-kodiċi tiegħek, mhux fil-konfigurazzjoni tal-aġent: tibqa’ valida anke jekk xi ħadd iżid mira ta’ handoff lir-router mingħajr ma javżak.

Taħżinx dak li m’għandux bżonn jinħażen

Għal data sensittiva, l-aqwa protezzjoni hija li ma taħżen xejn.

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

Dan is-setting jiġi deċiż għal kull konversazzjoni, li jippermettilek iżżomm l-istorja ta’ skambji ordinarji filwaqt li tipproċessa kontenut kunfidenzjali f’modalità effimera.

Modera ‘l fuq mill-katina (Upstream)

Varjant eleganti huwa li tpoġġi aġent ta’ moderazzjoni fil-bidu tal-katina: dan jeżamina t-talba u jittrasferixxiha lis-speċjalista biss jekk tkun aċċettabbli.

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

Il-valur ta’ dan il-mudell jinsab fis-separazzjoni tar-rwoli: il-moderatur m’għandux għodod u jagħmel ħaġa waħda biss, allura talba malizzjuża li jirrifjuta qatt ma tilħaq l-aġent li jaf kif jaġixxi.

Aġġusta l-ġenerazzjoni

Il-parametri tat-tlestija (completion) jikkontribwixxu wkoll għas-sigurtà għal raġuni sempliċi: tweġiba alluċinata hija riskju, u l-kreattività hija t-terra tagħha.

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 ta’ 0.1 flimkien ma’ top_p ta’ 0.85 iħallu lill-mudell ftit ħafna latitude: għal mistoqsija li t-tweġiba tagħha tidher fid-dokumenti tiegħek, jirkuprahha minflok ma jibni varjant. Il-limitu ta’ 1024 token jilgħab rwol simili, għax tweġiba li tikber wisq eventwalment titbiegħed mill-ambitu ddokumentat u tipproduċi kontenut żejjed (filler). Dawn is-settings ovvjament ma jkunux xierqa għal aġent kreattiv, iżda huma l-konfigurazzjoni predefinita għal kwalunkwe aġent li huwa mistenni jiddikjara fatti—assistent legali, appoġġ tekniku, espert tal-prodott.

Qabel ma tmur għall-produzzjoni

Dawn il-mekkaniżmi huma validi biss meta jkunu sovrapposti, u l-verifika finali tinżel għal ftit verifiki. L-istruzzjonijiet iridu jiddefinixxu espliċitament l-ambitu u l-projbizzjonijiet, u l-aġent irid ikollu biss l-għodod strettament meħtieġa għall-kompitu tiegħu. Iverifika li l-guardrails huma attivati, u li flussi ta’ ħidma kritiċi joperaw f’modalità tal-klijent (client mode) sabiex l-ebda handoff ma jesegwixxi mingħajr l-approvazzjoni tiegħek. Żgura li store=False jakkumpanja kwalunkwe konversazzjoni li tinvolvi data sensittiva, u li t-temperatura tibqa’ baxxa fejn l-aġent huwa mistenni jibqa’ fattwali. Fl-aħħar nett, poġġi aġent ta’ moderazzjoni quddiem il-katina sabiex talbiet inaċċettabbli qatt ma jilħqu l-aġenti li jafu kif jaġixxu.

Punti Ewlenin

  • Il-guardrails huma kkonfigurati fil-livell tal-aġent u/jew tal-konversazzjoni
  • L-istruzzjonijiet huma l-ewwel linja ta’ difiża tiegħek—kun espliċitu dwar il-projbizzjonijiet
  • Applika l-prinċipju tal-inqas privileġġ: agħti biss l-għodod meħtieġa
  • Il-modalità tal-klijent (Client mode) tippermettilek tivvalida u timblokka handoffs mhux awtorizzati
  • Fil-produzzjoni: moderazzjoni upstream, reġistrazzjoni (logging), lista bajda tal-aġenti, u store=False għal data sensittiva