Issikura l-aġenti b'guardrails
F'din il-paġna
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’ konfigurazzjonijietmoderation_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 · SDKmistralai3.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=Falsegħal data sensittiva