Mistral Agents API Architecture
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d. Ankstesniame pilname agento pavyzdyje buvo perduodama
guardrails={"enabled": True}, tačiau toks formatas neegzistuoja: oficialus parametras yramoderation_llm_v2konfigūracijų sąrašas.tool.executionįvestyje įrankio pavadinimas pateikiamas laukeentry.name, o neentry.tool_name, kas anksčiau sukeldavoAttributeErrorklaidą. Šaltiniai: Agents & Conversations · Moderation & Guardrailing ·mistralaiSDK 3.7.0.
Trys pagrindiniai objektai
Mistral Agents API remiasi trijų sąveikaujančių objektų darbą: Agentu, Pokalbiu ir Įrašu. Dauguma projektų pradžioje daromų dizaino klaidų – agento kūrimas kiekvienai užklausai, galiojimo laikas pasibaigusio conversation_id pakartotinis naudojimas arba atsakymų analizė, kuri stringa netikėtame įraše – kyla dėl painiavos tarp šių trijų lygmenų. Suprasti jų vaidmenis ir ryšius yra būtina sąlyga norint parašyti bent vieną kodo eilutę.
Agento objektas
Agentas yra konfigūracijų rinkinys, apibrėžiantis modelio elgseną. Jame nėra jokių pokalbio duomenų: tai daugkartinio naudojimo šablonas, kurį sukuriate vieną kartą ir kurį gali naudoti tūkstančiai pokalbių.
Kūrimui būtinai reikia bent modelio, pavadinimo ir aprašymo.
agent = client.beta.agents.create(
model="mistral-large-latest", # Naudojamas LLM modelis
name="My Agent", # Žmogui suprantamas identifikatorius
description="Agent for financial analysis" # Užduotimi grindžiamas aprašymas
)
Parametras model nurodo modelį, kuris valdys agentą; jį pasirenkate iš galimų pokalbių užbaigimo modelių, pavyzdžiui, mistral-medium-latest arba mistral-large-latest. name yra žmogui suprantamas identifikatorius, kurį naudojate agentui rasti ir nurodyti: projekte, kuriame jų yra dvidešimt, būtent tai apsaugo jus nuo naršymo žurnaluose norint išsiaiškinti, kuris iš jų atsako klientams. Tuo tarpu description yra orientuotas į užduotį ir tarnauja ne tik vidinei dokumentacijai – jis padeda modeliui suprasti jam keliamą vaidmenį, todėl formuluojama „agentas finansinei analizei“, o ne miglotai „agentas numeris 3“.
Likusi dalis konfigūruojama pasirinktinai, ir būtent čia įgauna formą tikroji agento asmenybė.
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– Agento sistemos promptas (apibrėžia jo asmenybę, taisykles ir stilių)tools– Galimų įrankių sąrašas:web_search,web_search_premium,code_interpreter,image_generation,document_libraryarba tinkintos funkcijoscompletion_args– Imtuvo parametrai (temperatūra, top_p, max_tokens ir kt.)guardrails– Moderacijos konfigūracijų (moderation_llm_v2) sąrašas, taikomas kiekvienam agento pokalbio gaunamam pranešimui; čia „jailbreaking“ blokuojamas viršijus 0,2 ribą, o kategorijafinanciališjungta (riba1), nes agentas sukurtas diskutuoti apie finansus. Detalės pateiktos kurse „AI Moderation and Security with Mistral“.
Pirmiau pateiktame pavyzdyje finansų agentas iš savo instrukcijų perima reikalavimą naudoti šaltinius, iš įrankių gauna galimybę patikrinti skaičių, o žema temperatūra riboja kūrybiškumą ten, kur tikimasi griežtumo.
Pokalbio objektas
Pokalbis yra sąveikų istorija tarp naudotojo ir agento – arba tarp naudotojo ir vien modelio. Jame yra pranešimai, įrankių vykdymo rezultatai ir perdavimo įvykiai.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Gaukite pokalbio ID, kad galėtumėte tęsti vėliau
conversation_id = response.conversation_id
Šio objekto elgsena turi keletą netikėtumų. Pokalbis yra nuolatinis: istorija saugoma „Mistral“ pusėje, nebent perduodate store=False. Jis yra nepriklausomas nuo agento, tai reiškia, kad pokalbis gali puikiai egzistuoti ir be agento, tiesioginio modelio režimu. Galiausiai, jis yra nekintamas: kiekvienas papildymas grąžina naują conversation_id, o senasis lieka pasiekiamas. Šis paskutinis punktas yra pats netikėčiausias: jei savo duomenų bazėje išsaugosite pradinį ID ir jį panaudosite trečiajame etape, grįšite prie pirmojo keitimosi konteksto.
Įrašo objektas
Įrašas yra individualus veiksmas pokalbio viduje: tai atomiškas istorijos vienetas. Kai gaunate atsakymą, lauke outputs yra įrašų sąrašas, kurio tipas priklauso nuo to, ką agentas atliko. message.output įrašas perduoda tekstinį agento atsakymą, t. y. tekstą, kurį rodys jūsų sąsaja. tool.execution įrašas perduoda įrankio vykdymo rezultatą, pavyzdžiui, kodą arba internetinės paieškos duomenis: paleistą scenarijų ir jo išvestį arba variklio grąžintus puslapius. agent.handoff įrašas signalizuoja perdavimo įvykį kitam agentui, todėl atsiranda tik daugiaagentėse situacijose.
Viename atsakyme šie tipai dažnai maišomi. Paprašykite įrankiais aprūpinto agento atlikti skaičiavimą ir gausite vykdymo rezultatą, o po jo – jį lydinčią komentarą: todėl jūsų kodas turi iteruoti per šį sąrašą, o ne skaityti vieną lauką.
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}")
Ryšiai tarp objektų
Toliau pateikta schema apibendrina trijų lygmenų sąveiką: daugkartinio naudojimo konfigūracijos, istorijos gijos ir vienetinių veiksmų.
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)
Pokalbio parinktys
Pradedant pokalbį galima nustatyti parametrus, kurie daro įtaką tiek jūsų atitikčiai reikalavimams, tiek architektūrai, ir geriau juos nusprasti patiems, nei leisti jiems jus nustebinti. Pirmiausia – saugojimas: store=False neleidžia nieko išsaugoti „Mistral“ pusėje; tai naudosite tvarkydami duomenis, kuriuos jūsų vidaus politika draudžia palikti trečiosios šalies serveryje.
# Išjungti debesijos saugyklą
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
Antrasis nustatymas apibrėžia, kas vykdo perdavimus (handoffs). Veiksena server (numatytoji vertė) reiškia, kad „Mistral“ grandininiais būdu perduoda agentus be jūsų įsikišimo; veiksena client reiškia, kad gaunate perdavimo įvykius ir išlaikote kontrolę juos registruoti, filtruoti arba atmesti.
# Serverio veiksena (numatytoji) – „Mistral“ automatiškai valdo perdavimus
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Kliento veiksena – gaunate perdavimo įvykius ir patys sprendžiate, ką daryti
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Svarbiausi punktai
- Agentas = daugkartinio naudojimo konfigūracija (modelis, instrukcijos, įrankiai, apsaugos taisyklės)
- Pokalbis = serveryje saugoma nuolatinė istorija, nepriklausoma nuo agento
- Įrašas = vienetinis veiksmas (pranešimas, įrankio vykdymas, perdavimas)
- Pokalbiai gali egzistuoti be agento (tiesioginio modelio režimas)
- Kiekvienas pokalbio papildymas sukuria naują
conversation_id - Režimas
store=Falseneleidžia saugoti duomenų „Mistral“ pusėje