Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Mistral Agents API-arkitektur

Lektion 3 af 18 Opdateret 3. november 2026 Udvikler
På denne side
  1. De tre fundamentale objekter
  2. Agent-objektet
  3. Conversation-objektet
  4. Entry-objektet
  5. Relationer mellem objekter
  6. Muligheder for samtaler
  7. Vigtige pointer

Opdateret 3. november 2026. Det tidligere fulde agenteksempel brugte guardrails={"enabled": True}, et format der ikke eksisterer: den officielle parameter er en liste af moderation_llm_v2-konfigurationer. Inputtet tool.execution eksponerer værktøjsnavnet i entry.name, ikke entry.tool_name, hvilket tidligere udløste en AttributeError. Kilder: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

De tre fundamentale objekter

Mistral Agents API hviler på tre interagerende objekter: Agent, Conversation og Entry. De fleste designfejl, man støder på tidligt i et projekt – som at genoprette en agent for hver anmodning, genbruge et udløbet conversation_id, eller respons-parsning der crascher på en uventet entry – stammer fra forvirring mellem disse tre niveauer. At forstå deres roller og relationer er en forudsætning for overhovedet at skrive én eneste linje kode.

Agent-objektet

En agent er et konfigurationssæt, der definerer modellens adfærd. Den indeholder ingen samtaledata: det er en genanvendelig skabelon, som du opretter én gang, og som tusindvis af samtaler kan referere til.

Oprettelse kræver som minimum en model, et navn og en beskrivelse.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # LLM-model der skal bruges
    name="My Agent",                     # Menneskelæselig identifikator
    description="Agent for financial analysis"  # Opgaveorienteret beskrivelse
)

Parameteren model udpeger den model, der skal drive agenten, valgt blandt tilgængelige chat completion-modeller som mistral-medium-latest eller mistral-large-latest. name er en menneskelæselig identifikator, du bruger til at finde og referere til agenten: i et projekt med tyve af dem, er det dette, der sparer dig for at grave i logs for at finde ud af, hvilken der svarer kunderne. description er derimod opgaveorienteret og tjener mere end bare intern dokumentation – den hjælper modellen med at forstå den rolle, der forventes af den, hvilket forklarer formuleringen „agent for financial analysis” frem for en vag „agent nummer 3”.

Resten konfigureres valgfrit, og det er her, agentens egentlige personlighed tager form.

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 – Agentens systemprompt (definerer dens personlighed, regler og stil)
  • tools – Liste over tilgængelige værktøjer: web_search, web_search_premium, code_interpreter, image_generation, document_library eller brugerdefinerede funktioner
  • completion_args – Sampler-parametre (temperature, top_p, max_tokens osv.)
  • guardrails – En liste over moderationskonfigurationer (moderation_llm_v2) anvendt på den indgående besked i hver af agentens samtaler; her blokeres jailbreaking over 0,2, og kategorien financial er deaktiveret (tærskel 1), da agenten er bygget til at diskutere finans. Detaljer findes i kurset AI Moderation and Security with Mistral.

I eksemplet ovenfor arver finansagenten et krav om kildeangivelse fra sine instrukser, evnen til at verificere et tal via sine værktøjer, og en lav temperatur, der begrænser kreativiteten, hvor der forventes rigorøsitet.

Conversation-objektet

En conversation er historikken over interaktioner mellem en bruger og en agent – eller mellem en bruger og en model alene. Den indeholder beskeder, resultater af værktøjskørsel og handoff-begivenheder.

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

# Hent conversation-ID'et for at fortsætte senere
conversation_id = response.conversation_id

Dette objekts adfærd rummer nogle overraskelser. Samtalen er persistent: historikken gemmes på Mistrals side, medmindre du sender store=False. Den er uafhængig af agenten, hvilket betyder, at en conversation sagtens kan eksistere uden en agent, i direkte modeltilstand. Endelig er den immutable: hver tilføjelse returnerer et nyt conversation_id, mens det gamle forbliver tilgængeligt. Dette sidste punkt er det mest overraskende: hvis du gemmer det oprindelige ID i din database og genbruger det ved tredje tur, vil du falde tilbage til konteksten fra den første udveksling.

Entry-objektet

En entry er en individuel handling inden for en conversation: historikkens atomare enhed. Når du modtager et svar, indeholder feltet outputs en liste over entries, hvis type afhænger af, hvad agenten gjorde. En message.output-entry bærer et tekstsvar fra agenten, dvs. den tekst, din grænseflade vil vise. En tool.execution-entry bærer kørselsresultatet af et værktøj, såsom kode eller en websøgning: scriptet der blev lanceret og dets output, eller de sider returneret af motoren. En agent.handoff-entry signalerer en overførselsbegivenhed til en anden agent og optræder derfor kun i multi-agent-scenarier.

Et enkelt svar blander ofte disse typer. Spørger du en agent med værktøjer om en beregning, vil du modtage eksekveringen og derefter kommentaren, der ledsager den: din kode skal derfor iterere gennem denne liste i stedet for at læse ét enkelt felt.

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

Relationer mellem objekter

Følgende diagram opsummerer sammenhængen mellem de tre niveauer: en genanvendelig konfiguration, en historiktråd og enhedshandlinger.

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)

Muligheder for samtaler

Start af en conversation accepterer indstillinger, der påvirker både din compliance og din arkitektur, og det er bedre at beslutte dem end at lide under dem. Først lagring: store=False forhindrer enhver lagring på Mistrals side, hvilket du vil bruge til at behandle data, som din interne politik forbyder at leave på en tredjepartsserver.

# Deaktiver cloud-lagring
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Den anden indstilling definerer, hvem der udfører handoffs. I tilstanden server, som er standardværdien, kæder Mistral agentoverførsler sammen uden din indgriben; i tilstanden client modtager du handoff-begivenheder og beholder kontrollen til at logge, filtrere eller afvise dem.

# Server-tilstand (standard) — Mistral håndterer handoffs automatisk
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Client-tilstand — Du modtager handoff-begivenheder og beslutter, hvad du vil gøre
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Vigtige pointer

  • Agent = genanvendelig konfiguration (model, instrukser, værktøjer, guardrails)
  • Conversation = persistent historik gemt på serveren, uafhængig af agenten
  • Entry = enhedshandling (besked, værktøjskørsel, handoff)
  • Samtaler kan eksistere uden en agent (direkte modeltilstand)
  • Hver tilføjelse til en conversation skaber et nyt conversation_id
  • Tilstanden store=False forhindrer lagring på Mistrals side