Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Architectuur van de Mistral Agents API

Les 3 van 18 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. De drie fundamentele objecten
  2. Het Agent-object
  3. Het Conversation-object
  4. Het Entry-object
  5. Relaties tussen objecten
  6. Opties voor conversaties
  7. Belangrijkste punten

Bijgewerkt op 3 november 2026. Het eerdere volledige agent-voorbeeld gaf guardrails={"enabled": True} door, een formaat dat niet bestaat: de officiële parameter is een lijst met moderation_llm_v2-configuraties. De tool.execution-input exposeert de tool-naam in entry.name, niet in entry.tool_name, wat eerder een AttributeError veroorzaakte. Bronnen: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

De drie fundamentele objecten

De Mistral Agents API steunt op drie onderling verbonden objecten: Agent, Conversation en Entry. De meeste ontwerpfouten die vroeg in een project optreden—zoals het voor elk verzoek opnieuw aanmaken van een agent, het hergebruiken van een verlopen conversation_id, of respons-parsing die crasht bij een onverwachte entry—vloeien voort uit verwarring tussen deze drie niveaus. Inzicht in hun rollen en relaties is een voorwaarde om ook maar één regel code te schrijven.

Het Agent-object

Een Agent is een configuratieset die het gedrag van het model definieert. Het bevat geen conversatiegegevens: het is een herbruikbaar sjabloon dat u eenmaal aanmaakt en waarnaar duizenden conversaties kunnen verwijzen.

Voor het aanmaken zijn minimaal een model, een naam en een beschrijving vereist.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Te gebruiken LLM-model
    name="My Agent",                     # Voor mensen leesbare identificatie
    description="Agent for financial analysis"  # Taakgerichte beschrijving
)

De parameter model wijst het model aan dat de agent aandrijft, gekozen uit beschikbare chat-completion-modellen zoals mistral-medium-latest of mistral-large-latest. De name is een voor mensen leesbare identificatie die u gebruikt om de agent te vinden en ernaar te verwijzen: in een project met twintig agents voorkomt dit dat u door logs moet wroeten om uit te zoeken welke agent klanten beantwoordt. De description daarentegen is taakgericht en dient meer dan alleen interne documentatie; het helpt het model de verwachte rol te begrijpen, wat de formulering “agent for financial analysis” verklaart in plaats van een vaag “agent number 3”.

De rest wordt optioneel geconfigureerd, en hier krijgt de eigenlijke persoonlijkheid van de agent vorm.

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 — De systeemprompt van de agent (definieert persoonlijkheid, regels en stijl)
  • tools — Lijst met beschikbare tools: web_search, web_search_premium, code_interpreter, image_generation, document_library of aangepaste functies
  • completion_args — Sampler-parameters (temperature, top_p, max_tokens, enz.)
  • guardrails — Een lijst met moderatieconfiguraties (moderation_llm_v2) die worden toegepast op het binnenkomende bericht van elke conversatie van de agent; hier wordt jailbreaking geblokkeerd boven 0,2 en is de categorie financial uitgeschakeld (drempel 1), omdat de agent is gebouwd om over financiën te discussiëren. Details vindt u in de cursus AI Moderation and Security with Mistral.

In het bovenstaande voorbeeld erft de financiële agent een bronvermeldingsvereiste uit zijn instructies, de mogelijkheid om een cijfer te verifiëren via zijn tools, en een lage temperature die creativiteit beperkt waar nauwkeurigheid vereist is.

Het Conversation-object

Een Conversation is de geschiedenis van interacties tussen een gebruiker en een agent—of tussen een gebruiker en een model alleen. Het bevat berichten, uitvoeringsresultaten van tools en overdrachtsgebeurtenissen (handoffs).

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

# Haal de conversation_id op om later verder te gaan
conversation_id = response.conversation_id

Het gedrag van dit object houdt enkele verrassingen in. De conversatie is persistent: de geschiedenis wordt aan de kant van Mistral opgeslagen, tenzij u store=False doorgeeft. Het is onafhankelijk van de agent, wat betekent dat een conversatie prima kan bestaan zonder agent, in directe modelmodus. Tot slot is het immutable: elke toevoeging retourneert een nieuwe conversation_id, terwijl de oude toegankelijk blijft. Dit laatste punt is het meest verrassend: als u de initiële ID in uw database opslaat en deze bij de derde beurt hergebruikt, keert u terug naar de context van de eerste uitwisseling.

Het Entry-object

Een Entry is een individuele actie binnen een conversatie: de atomaire eenheid van de geschiedenis. Wanneer u een respons ontvangt, bevat het veld outputs een lijst met entries waarvan het type afhangt van wat de agent heeft gedaan. Een message.output-entry bevat een tekstrespons van de agent, dus de tekst die uw interface zal weergeven. Een tool.execution-entry bevat het uitvoeringsresultaat van een tool, zoals code of een webzoekopdracht: het gestarte script en de output, of de pagina’s die door de engine zijn teruggegeven. Een agent.handoff-entry signaleert een overdrachtsgebeurtenis naar een andere agent en verschijnt dus alleen in multi-agent-scenario’s.

Een enkele respons combineert vaak deze typen. Vraag een agent met tools om een berekening en u ontvangt eerst de uitvoering, daarna het begeleidende commentaar: uw code moet daarom door deze lijst itereren in plaats van één veld uit te lezen.

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

Relaties tussen objecten

Het volgende diagram vat de articulatie van de drie niveaus samen: een herbruikbare configuratie, een geschiedenisdraad en unitaire acties.

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)

Opties voor conversaties

Het starten van een conversatie accepteert instellingen die evenzeer van invloed zijn op uw compliance als op uw architectuur, en het is beter deze zelf te bepalen dan ze ondergaan. Opslag eerst: store=False voorkomt elke opslag aan de kant van Mistral, wat u gebruikt om gegevens te verwerken die uw interne beleid verbiedt op een server van derden achter te laten.

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

De tweede instelling definieert wie handoffs uitvoert. In de modus server, de standaardwaarde, ketent Mistral agent-overdrachten zonder uw tussenkomst; in de modus client ontvangt u handoff-gebeurtenissen en houdt u de controle om ze te loggen, filteren of weigeren.

# Server-modus (standaard) — Mistral handelt handoffs automatisch af
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Client-modus — U ontvangt handoff-gebeurtenissen en beslist wat u doet
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Belangrijkste punten

  • Agent = herbruikbare configuratie (model, instructies, tools, guardrails)
  • Conversation = persistente geschiedenis opgeslagen op de server, onafhankelijk van de agent
  • Entry = unitaire actie (bericht, tool-uitvoering, handoff)
  • Conversaties kunnen bestaan zonder agent (directe modelmodus)
  • Elke toevoeging aan een conversatie creëert een nieuwe conversation_id
  • De modus store=False voorkomt opslag aan de kant van Mistral