Architectuur van de Mistral Agents API
Op deze pagina
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 metmoderation_llm_v2-configuraties. Detool.execution-input exposeert de tool-naam inentry.name, niet inentry.tool_name, wat eerder eenAttributeErrorveroorzaakte. Bronnen: Agents & Conversations · Moderation & Guardrailing ·mistralaiSDK 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_libraryof aangepaste functiescompletion_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 categoriefinancialuitgeschakeld (drempel1), 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=Falsevoorkomt opslag aan de kant van Mistral