Arkitettura tal-API tal-Aġenti ta' Mistral
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026. L-eżempju preċedenti ta’ aġent sħiħ għadda
guardrails={"enabled": True}, format li ma jeżistix: il-parametru uffiċjali huwa lista ta’ konfigurazzjonijietmoderation_llm_v2. L-inputtool.executionjesponi l-isem tal-għodda f’entry.name, mhuxentry.tool_name, li qabel kien iqajjemAttributeError. Sorsi: Aġenti u Konversazzjonijiet · Moderazzjoni u Guardrailing · SDKmistralai3.7.0.
It-Tliet Oġġetti Fundamentali
L-API tal-Aġenti ta’ Mistral tiddependi fuq tliet oġġetti li jinteraġixxu: Agent, Conversation, u Entry. Ħafna mill-iżbalji tad-disinn li tiltaqa’ magħhom fil-bidu ta’ proġett—bħall-ħolqien mill-ġdid ta’ aġent għal kull talba, l-użu mill-ġdid ta’ conversation_id skadut, jew parsing tar-rispons li jikkraċċja fuq entry mhux mistennija—jiġu minn konfużjoni bejn dawn it-tliet livelli. Li tifhem ir-rwoli u r-relazzjonijiet tagħhom huwa prerekwiżit biex tikteb anke linja waħda ta’ kodiċi.
L-Oġġett Agent
Aġent huwa sett ta’ konfigurazzjoni li jiddefinixxi l-imġiba tal-mudell. Ma fih l-ebda data ta’ konversazzjoni: huwa mudell li tuża darba waħda u li eluf ta’ konversazzjonijiet jistgħu jirreferenzjawh.
Il-ħolqien jeħtieġ mill-inqas mudell, isem u deskrizzjoni.
agent = client.beta.agents.create(
model="mistral-large-latest", # Mudell LLM li għandu jintuża
name="My Agent", # Identifikatur li jista' jaqrah il-bniedem
description="Agent for financial analysis" # Deskrizzjoni orjentata lejn il-kompitu
)
Il-parametru model jindika l-mudell li se jmexxi l-aġent, magħżul minn mudelli ta’ tlestija taċ-chat disponibbli bħal mistral-medium-latest jew mistral-large-latest. L-name huwa identifikatur li jista’ jaqrah il-bniedem li tuża biex issib u tirreferenzja l-aġent: f’proġett b’għoxrin minnhom, dan huwa dak li jsalvak milli tgħarbel il-logs biex tifhem liema wieħed qed iwieġeb lill-klijenti. Id-description, min-naħa l-oħra, hija orjentata lejn il-kompitu u sservi għal aktar minn dokumentazzjoni interna biss—tgħin lill-mudell jifhem ir-rwol mistenni minnu, li jispjega l-frażi “aġent għall-analiżi finanzjarja” minflok “aġent numru 3” vaga.
Il-bqija tiġi kkonfigurata b’mod fakultattiv, u hawnhekk tieħu forma l-personalità attwali tal-aġent.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Complete Agent",
description="Agent with all parameters",
instructions="You are a finance expert. Always respond with sources.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95},
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
"action": "block",
},
}
],
)
instructions— Il-prompt tas-sistema tal-aġent (jiddefinixxi l-personalità, ir-regoli u l-istil tiegħu)tools— Lista ta’ għodod disponibbli:web_search,web_search_premium,code_interpreter,image_generation,document_library, jew funzjonijiet personalizzaticompletion_args— Parametri tas-sampler (temperatura, top_p, max_tokens, eċċ.)guardrails— Lista ta’ konfigurazzjonijiet ta’ moderazzjoni (moderation_llm_v2) applikati għall-messaġġ li jidħol ta’ kull waħda mill-konversazzjonijiet tal-aġent; hawnhekk, il-jailbreaking huwa mblukkat ‘il fuq minn 0.2 u l-kategorijafinancialhija diżattivata (limitu1), peress li l-aġent inbena biex jiddiskuti l-finanzi. Id-dettalji jinsabu fil-kors AI Moderation and Security with Mistral.
Fl-eżempju ta’ hawn fuq, l-aġent finanzjarju jwirt rekwiżit ta’ sorsi mill-istruzzjonijiet tiegħu, il-kapaċità li jivverifika ċifra mill-għodod tiegħu, u temperatura baxxa li tillimita l-kreattività fejn tkun meħtieġa r-riġorożità.
L-Oġġett Conversation
Konversazzjoni hija l-istorja tal-interazzjonijiet bejn utent u aġent—jew bejn utent u mudell waħdu. Fiha messaġġi, riżultati ta’ eżekuzzjoni ta’ għodod, u avvenimenti ta’ trasferiment (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Irkupera l-ID tal-konversazzjoni biex tkompli aktar tard
conversation_id = response.conversation_id
L-imġiba ta’ dan l-oġġett fiha ftit sorpriżi. Il-konversazzjoni hija persistenti: l-istorja tinħażen fuq in-naħa ta’ Mistral, sakemm ma tgħaddix store=False. Hija indipendenti mill-aġent, li jfisser li konversazzjoni tista’ perfettament teżisti mingħajr aġent, f’modalità ta’ mudell dirett. Fl-aħħar nett, hija immobbli: kull żieda tirritorna conversation_id ġdid, filwaqt li l-qadim jibqa’ aċċessibbli. Dan l-aħħar punt huwa l-aktar wieħed sorprendenti: jekk taħżen l-ID inizjali fil-bażi tad-data tiegħek u terġa’ tużah fit-tielet dawra, se terġa’ lura għall-kuntest tal-ewwel skambju.
L-Oġġett Entry
Entry hija azzjoni individwali fi ħdan konversazzjoni: l-unità atomika tal-istorja. Meta tirċievi rispons, il-qasam outputs fih lista ta’ entries li t-tip tagħhom jiddependi fuq dak li għamel l-aġent. Entry message.output iġġib rispons testwali mill-aġent, jiġifieri t-test li l-interfaċċja tiegħek se turi. Entry tool.execution iġġib ir-riżultat tal-eżekuzzjoni ta’ għodda, bħal kodiċi jew tfittxija fuq il-web: l-iskript imnedija u l-output tiegħu, jew il-paġni rritornati mill-magna. Entry agent.handoff tissuġġerixxi avveniment ta’ trasferiment lejn aġent ieħor, u għalhekk tidher biss f’xenarji multi-aġent.
Rispons wieħed spiss iħallat dawn it-tipi. Jekk titlob lil aġent mgħammar b’għodod jagħmel kalkolu, se tirċievi l-eżekuzzjoni, imbagħad il-kummentarju li jakkumpanjaha: il-kodiċi tiegħek għandu għalhekk jgħaddi minn din il-lista minflok ma jaqra qasam wieħed.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the square root of 144"
)
for entry in response.outputs:
print(f"Type: {entry.type}")
if entry.type == "message.output":
print(f"Message: {entry.content}")
elif entry.type == "tool.execution":
print(f"Tool: {entry.name}")
Relazzjonijiet Bejn l-Oġġetti
Id-dijagramma li ġejja tissintetizza l-artikolazzjoni tat-tliet livelli: konfigurazzjoni li tista’ terġa’ tintuża, thread tal-istorja, u azzjonijiet unitarji.
Agent (configuration)
├── model, instructions, tools, guardrails
└── Can be referenced by N conversations
Conversation (history)
├── Linked to 0 or 1 Agent (optional)
├── Contains N ordered entries
└── Each append creates a new conversation_id
Entry (unit action)
├── message.output (text response)
├── tool.execution (tool result)
└── agent.handoff (agent transfer)
Għażliet tal-Konversazzjoni
Il-bidu ta’ konversazzjoni jaċċetta settings li jaffettwaw il-konformità tiegħek daqskemm l-arkitettura tiegħek, u huwa aħjar li tiddeċiedi int dwarhom milli tbati bil-konsegwenzi. L-ewwel nett il-ħażna: store=False jipprevjeni kwalunkwe salvataġġ fuq in-naħa ta’ Mistral, li se tuża biex tipproċessa data li l-politika interna tiegħek tipprojbixxi li titħalla fuq server ta’ parti terza.
# Iddiżattiva l-ħażna fil-cloud
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
It-tieni setting jiddefinixxi min jeseġwixxi t-trasferimenti (handoffs). Fil-modalità server, il-valur default, Mistral iċċatena t-trasferimenti tal-aġenti mingħajr l-intervent tiegħek; fil-modalità client, tirċievi avvenimenti ta’ handoff u żżomm il-kontroll biex tirreġistra, tiffiltra, jew tirrifjutahom.
# Modalità Server (default) — Mistral jimmaniġġja l-handoffs awtomatikament
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Modalità Client — Tirċievi avvenimenti ta' handoff u tiddeċiedi x'tagħmel
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Punti Ewlenin
- Agent = konfigurazzjoni li tista’ terġa’ tintuża (mudell, istruzzjonijiet, għodod, guardrails)
- Conversation = storja persistenti maħżuna fuq is-server, indipendenti mill-aġent
- Entry = azzjoni unitarja (messaġġ, eżekuzzjoni ta’ għodda, handoff)
- Il-konversazzjonijiet jistgħu jeżistu mingħajr aġent (modalità ta’ mudell dirett)
- Kull żieda għal konversazzjoni toħloq
conversation_idġdid - Il-modalità
store=Falsetipprevjeni l-ħażna fuq in-naħa ta’ Mistral