Mistral Agents API arhitektuur
Sellel lehel
Uuendatud 3. novembril 2026. Eelmises täielikus agendi näites kasutati parameetrit
guardrails={"enabled": True}, mida tegelikkuses ei eksisteeri: ametlik parameeter on loendmoderation_llm_v2konfiguratsioonidest. Sisendtool.executionväljastab tööriista nime väljalentry.name, mitteentry.tool_name, mis varem põhjustas veaAttributeError. Allikad: Agents & Conversations · Moderation & Guardrailing ·mistralaiSDK 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_libraryvõi kohandatud funktsioonidcompletion_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 kategooriafinancialon keelatud (lävi1), 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=Falsetakistab salvestamist Mistrali poolel