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

Arkitettura tal-API tal-Aġenti ta' Mistral

Lezzjoni 3 / 18 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. It-Tliet Oġġetti Fundamentali
  2. L-Oġġett Agent
  3. L-Oġġett Conversation
  4. L-Oġġett Entry
  5. Relazzjonijiet Bejn l-Oġġetti
  6. Għażliet tal-Konversazzjoni
  7. Punti Ewlenin

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’ konfigurazzjonijiet moderation_llm_v2. L-input tool.execution jesponi l-isem tal-għodda f’entry.name, mhux entry.tool_name, li qabel kien iqajjem AttributeError. Sorsi: Aġenti u Konversazzjonijiet · Moderazzjoni u Guardrailing · SDK mistralai 3.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 personalizzati
  • completion_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-kategorija financial hija diżattivata (limitu 1), 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=False tipprevjeni l-ħażna fuq in-naħa ta’ Mistral