Mistral Agents API - Arkkitehtuuri
Tällä sivulla
Päivitetty 3. marraskuuta 2026. Edellinen täydellinen agenttiesimerkki välitti parametrin
guardrails={"enabled": True}, joka on virheellinen muoto: virallinen parametri on listamoderation_llm_v2-määrityksiä. Syötetool.executionpaljastaa työkalun nimen kentässäentry.name, eientry.tool_name, mikä aiheutti aiemminAttributeError-virheen. Lähteet: Agents & Conversations · Moderation & Guardrailing ·mistralaiSDK 3.7.0.
Kolme perusoliota
Mistral Agents API perustuu kolmeen vuorovaikutteiseen olioon: Agent, Conversation ja Entry. Useimmat projektin alkuvaiheessa tehdyt suunnitteluvirheet – kuten agentin luominen uudelleen jokaista pyyntöä varten, vanhentuneen conversation_id:n uudelleenkäyttö tai vastauksen jäsentäminen, joka kaatuu odottamattoman entryn takia – johtuvat näiden kolmen tason sekoittamisesta. Niiden roolien ja suhteiden ymmärtäminen on edellytys edes yhden koodirivin kirjoittamiselle.
Agent-olio
Agent on konfiguraatiokokonaisuus, joka määrittelee mallin käyttäytymisen. Se ei sisällä keskusteludataa: se on uudelleenkäytettävä malli, jonka luot kerran ja johon tuhannet keskustelut voivat viitata.
Luominen vaatii vähintään mallin, nimen ja kuvauksen.
agent = client.beta.agents.create(
model="mistral-large-latest", # Käytettävä LLM-malli
name="My Agent", # Ihmiselle luettava tunniste
description="Agent for financial analysis" # Tehtäväsuuntautunut kuvaus
)
Parametri model määrittää agenttia käyttävän mallin, joka valitaan saatavilla olevista chat-valmistumismalleista, kuten mistral-medium-latest tai mistral-large-latest. name on ihmiselle luettava tunniste, jota käytät agentin löytämiseen ja viittaamiseen: projektissa, jossa on kaksikymmentä agenttia, tämä säästää sinut lokien kaivelulta selvittääksesi, mikä niistä vastaa asiakkaille. description puolestaan on tehtäväsuuntautunut ja palvelee muutakin kuin sisäistä dokumentaatiota – se auttaa mallia ymmärtämään siltä odotettua roolia, mikä selittää muotoilun “agentti rahoitusanalyysiin” epäselvän “agentti numero 3” sijaan.
Loppu konfiguroidaan valinnaisesti, ja tässä agentin todellinen persoonallisuus hahmottuu.
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– Agentin järjestelmäkehote (määrittelee sen persoonallisuuden, säännöt ja tyylin)tools– Luettelo käytettävissä olevista työkaluista:web_search,web_search_premium,code_interpreter,image_generation,document_librarytai mukautetut funktiotcompletion_args– Näytteenotinparametrit (lämpötila, top_p, max_tokens jne.)guardrails– Lista moderointimäärityksiä (moderation_llm_v2), joita sovelletaan agentin jokaisen keskustelun saapuvaan viestiin; tässä jailbreaking estetään, jos arvo ylittää 0.2, ja kategoriafinancialon poistettu käytöstä (kynnysarvo1), koska agentti on rakennettu keskustelemaan rahoituksesta. Yksityiskohdat löytyvät kurssilta AI Moderation and Security with Mistral.
Yllä olevassa esimerkissä rahoitusagentti perii lähteiden vaatimuksen ohjeistaan, kyvyn tarkistaa luku työkaluillaan ja matalan lämpötilan, joka rajoittaa luovuutta tilanteissa, joissa vaaditaan tarkkuutta.
Conversation-olio
Conversation on vuorovaikutushistoria käyttäjän ja agentin välillä – tai käyttäjän ja pelkän mallin välillä. Se sisältää viestejä, työkalujen suoritus tuloksia ja siirtotapahtumia (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Hae keskustelun tunniste jatkaaksesi myöhemmin
conversation_id = response.conversation_id
Tämän olion käyttäytyminen sisältää muutamia yllätyksiä. Keskustelu on pysyvä: historia tallennetaan Mistralin puolelle, ellet välitä parametria store=False. Se on riippumaton agentista, mikä tarkoittaa, että keskustelu voi hyvin olemassa ilman agenttia suorassa mallitilassa. Lopuksi se on muuttumaton: jokainen lisäys palauttaa uuden conversation_id:n, kun taas vanha pysyy saatavilla. Tämä viimeinen kohta on yllättävin: jos tallennat alkuperäisen tunnisteen tietokantaasi ja käytät sitä uudelleen kolmannella kierroksella, palaat ensimmäisen vaihdon kontekstiin.
Entry-olio
Entry on yksittäinen toiminto keskustelun sisällä: historian atomiyksikkö. Kun vastaanotat vastauksen, kenttä outputs sisältää listan entryjä, joiden tyyppi riippuu agentin suorittamasta toiminnasta. message.output-entry kuljettaa agentin tekstivastauksen, eli tekstin, jonka käyttöliittymäsi näyttää. tool.execution-entry kuljettaa työkalun suorituksen tuloksen, kuten koodin tai verkkohaun: käynnistetyn skriptin ja sen tulosteen tai hakukoneen palauttamat sivut. agent.handoff-entry signaloi siirtotapahtuman toiselle agentille, ja se esiintyy siis vain moniagenttisissa skenaarioissa.
Yksi vastaus yhdistelee usein näitä tyyppejä. Jos pyydät työkaluja käyttävältä agentilta laskutoimitusta, vastaanotat ensin suorituksen ja sen jälkeen siihen liittyvän kommentoinnin: koodisi täytyy siis iteroida tämän listan läpi yhden kentän lukemisen sijaan.
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}")
Olioiden väliset suhteet
Seuraava kaavio tiivistää kolmen tason yhteyden: uudelleenkäytettävän konfiguraation, historiasäikeen ja yksikkötoiminnot.
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)
Keskustelun asetukset
Keskustelun aloittaminen hyväksyy asetuksia, jotka vaikuttavat yhtä lailla vaatimustenmukaisuuteesi kuin arkkitehtuuriisi, ja on parempi päättää niistä itse kuin joutua niiden armoille. Ensinnäkin tallennus: store=False estää kaiken tallentamisen Mistralin puolelle, mitä käytät käsittelemään dataa, jonka sisäinen policiesi kieltää jättämästä kolmannen osapuolen palvelimelle.
# Poista pilvitallennus käytöstä
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
Toinen asetus määrittelee, kuka suorittaa siirrot (handoffs). Oletusarvoisessa server-tilassa Mistral ketjuttaa agenttisiirrot ilman väliintuloasi; client-tilassa vastaanotat siirtotapahtumat ja pidät kontrollin kirjataksesi, suodattaaksesi tai kieltäytyäksesi niistä.
# Server-tila (oletus) — Mistral hoitaa siirrot automaattisesti
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Client-tila — Vastaanotat siirtotapahtumat ja päätät, mitä tehdä
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Keskeiset asiat
- Agent = uudelleenkäytettävä konfiguraatio (malli, ohjeet, työkalut, guardrails)
- Conversation = palvelimelle tallennettu pysyvä historia, riippumaton agentista
- Entry = yksikkötoiminto (viesti, työkalun suoritus, siirto)
- Keskustelut voivat olla olemassa ilman agenttia (suora mallitila)
- Jokainen keskusteluun tehty lisäys luo uuden
conversation_id:n - Tila
store=Falseestää tallentamisen Mistralin puolelle