Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Mistral Agents API arhitektuur

Õppetund 3 / 18 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Kolm fundamentaalset objekti
  2. Agendi objekt
  3. Vestluse objekt (Conversation)
  4. Kirje objekt (Entry)
  5. Objektide vahelised seosed
  6. Vestluse valikud
  7. Peamised punktid

Uuendatud 3. novembril 2026. Eelmises täielikus agendi näites kasutati parameetrit guardrails={"enabled": True}, mida tegelikkuses ei eksisteeri: ametlik parameeter on loend moderation_llm_v2 konfiguratsioonidest. Sisend tool.execution väljastab tööriista nime väljal entry.name, mitte entry.tool_name, mis varem põhjustas vea AttributeError. Allikad: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

Kolm fundamentaalset objekti

Mistral Agents API tugineb kolmele omavahel seotud objektile: Agent, Conversation ja Entry. Enamik projekteerimisvigu, millega projekti alguses kokku puutud – agendi loomine iga päringu jaoks, aegunud conversation_id uuestikasutamine või vastuse parsimine, mis kukub ootamatu kirje tõttu kokku – tulenevad segadusest nende kolme taseme vahel. Nende rollide ja seoste mõistmine on eelduseks isegi ühe koodirea kirjutamiseks.

Agendi objekt

Agent on konfiguratsioonikomplekt, mis määratleb mudeli käitumise. See ei sisalda vestlusandmeid: see on korduvkasutatav mall, mille lood üks kord ja millele saavad viidata tuhanded vestlused.

Loomine nõuab vähemalt mudelit, nime ja kirjeldust.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Kasutatav LLM-mudel
    name="My Agent",                     # Inimesele loetav identifikaator
    description="Agent for financial analysis"  # Ülesandele orienteeritud kirjeldus
)

Parameeter model määrab agendi käitava mudeli, valides saadaolevate vestluse lõpuleviimise mudelite hulgast, nagu mistral-medium-latest või mistral-large-latest. name on inimesele loetav identifikaator, mida kasutad agendi leidmiseks ja viitamiseks: kui projektis on neid kakskümmend, just see hoiab sind logides kaevamisest, et aru saada, milline neist klientidele vastab. description on seevastu ülesandele orienteeritud ja teenib rohkemat kui ainult sisemist dokumentatsiooni – see aitab mudelil mõista talle oodatavat rolli, mis selgitab sõnastust “finantsanalüüsi agent” ebamäärase “agent number 3” asemel.

Ülejäänu konfigureeritakse valikuliselt ja just siin võtab kuju agendi tegelik isiksus.

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 – Agendi süsteemne viip (määratleb selle isiksuse, reeglid ja stiili)
  • tools – Loend saadaolevatest tööriistadest: web_search, web_search_premium, code_interpreter, image_generation, document_library või kohandatud funktsioonid
  • completion_args – Proovivõtu parameetrid (temperatuur, top_p, max_tokens jne)
  • guardrails – Loend moderatsioonikonfiguratsioonidest (moderation_llm_v2), mida rakendatakse agendi iga vestluse sissetulevale sõnumile; siin blokeeritakse jailbreaking üle 0,2 ja kategooria financial on keelatud (lävi 1), kuna agent on loodud finantsteemade arutamiseks. Üksikasjad leiad kursusest AI Moderation and Security with Mistral.

Ülaltoodud näites pärib finantsagent oma juhistest allikate nõude, oma tööriistadest võime kontrollida arvu ja madala temperatuuri, mis piirab loovust seal, kus oodatakse täpsust.

Vestluse objekt (Conversation)

Vestlus on interaktsioonide ajalugu kasutaja ja agendi vahel – või kasutaja ja üksnes mudeli vahel. See sisaldab sõnumeid, tööriistade käivitamise tulemusi ja üleandmise sündmusi.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Analyze trends in the European AI market."
)

# Vestluse ID taastamine hiljem jätkamiseks
conversation_id = response.conversation_id

Selle objekti käitumine peidab endas mõned üllatused. Vestlus on püsiv: ajalugu salvestatakse Mistrali poolele, välja arvatud juhul, kui edastad store=False. See on agendist sõltumatu, mis tähendab, et vestlus võib täiesti hästi eksisteerida ilma agendita, otseses mudelirežiimis. Lõpuks on see muutumatu: iga lisamine tagastab uue conversation_id, kusjuures vana jääb kättesaadavaks. See viimane punkt on kõige üllatavam: kui salvestad algse ID oma andmebaasi ja kasutad seda kolmandal pöördel uuesti, naased esimese vahetuse konteksti.

Kirje objekt (Entry)

Kirje on individuaalne tegevus vestluse sees: ajaloo aatomühik. Kui saad vastuse, sisaldab väli outputs loendit kirjetest, mille tüüp sõltub sellest, mida agent tegi. Kirje message.output kannab agendi tekstivastust, st teksti, mida sinu liides kuvab. Kirje tool.execution kannab tööriista käivitamise tulemust, nagu kood või veebiotsing: käivitatud skript ja selle väljund või mootori tagastatud lehed. Kirje agent.handoff annab märku üleandmise sündmusest teisele agendile ja ilmub seega ainult mitme agendi stsenaariumides.

Üks vastus sisaldab sageli neid tüüpe segamini. Küsi tööriistadega agendilt arvutust ja saad tulemuseks nii käivitamise kui ka seda saatva kommentaari: sinu kood peab seetõttu iteratsiooniga läbima selle loendi, mitte lugema ühte välia.

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

Objektide vahelised seosed

Järgnev diagramm võtab kokku kolme taseme liigenduse: korduvkasutatava konfiguratsiooni, ajaloolõnga ja üksiktegevused.

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)

Vestluse valikud

Vestluse alustamine aktsepteerib seadeid, mis mõjutavad nii sinu vastavust nõuetele kui ka arhitektuuri, ja parem on need ise otsustada kui hiljem nende tagajärgedega leppida. Kõigepealt salvestamine: store=False takistab igasugust salvestamist Mistrali poolel, mida kasutad andmete töötlemisel, mida sinu sisepoliitika keelab kolmanda osapoole serverisse jätmast.

# Pilvesalvestuse keelamine
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Teine säte määratleb, kes üleandmisi teostab. Režiimis server (vaikimisi väärtus) aheldab Mistral agendi üleandmisi sinu sekkumiseta; režiimis client saad üleandmise sündmused ja hoiad kontrolli, et neid logida, filtreerida või tagasi lükata.

# Serverirežiim (vaikimisi) — Mistral haldab üleandmisi automaatselt
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Kliendirežiim — Saad üleandmise sündmused ja otsustad, mida teha
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Peamised punktid

  • Agent = korduvkasutatav konfiguratsioon (mudel, juhised, tööriistad, guardrails)
  • Conversation = serverisse salvestatud püsiv ajalugu, agendist sõltumatu
  • Entry = üksiktegevus (sõnum, tööriista käivitamine, üleandmine)
  • Vestlused võivad eksisteerida ilma agendita (otsene mudelirežiim)
  • Iga lisamine vestlusesse loob uue conversation_id
  • Režiim store=False takistab salvestamist Mistrali poolel