Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Mistral Agents API - Arkkitehtuuri

Oppitunti 3 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Kolme perusoliota
  2. Agent-olio
  3. Conversation-olio
  4. Entry-olio
  5. Olioiden väliset suhteet
  6. Keskustelun asetukset
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026. Edellinen täydellinen agenttiesimerkki välitti parametrin guardrails={"enabled": True}, joka on virheellinen muoto: virallinen parametri on lista moderation_llm_v2 -määrityksiä. Syöte tool.execution paljastaa työkalun nimen kentässä entry.name, ei entry.tool_name, mikä aiheutti aiemmin AttributeError-virheen. Lähteet: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 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_library tai mukautetut funktiot
  • completion_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 kategoria financial on poistettu käytöstä (kynnysarvo 1), 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=False estää tallentamisen Mistralin puolelle