Architektur der Mistral Agents API — Mistral Agents: Aufbau autonomer KI

Aktualisiert am 3. November 2026. Das vorherige vollständige Agentenbeispiel verwendete guardrails={"enabled": True}, ein Format, das nicht existiert: Der offizielle Parameter ist eine Liste von moderation_llm_v2-Konfigurationen. Der Eingabe-Parameter tool.execution gibt den Tool-Namen in entry.name aus, nicht in entry.tool_name, was zuvor einen AttributeError ausgelöst hat. Quellen: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

Die drei grundlegenden Objekte

Die Mistral Agents API stützt sich auf drei interagierende Objekte: Agent, Conversation und Entry. Die meisten Designfehler, die zu Beginn eines Projekts auftreten – etwa das Neuerstellen eines Agents für jede Anfrage, die Wiederverwendung einer abgelaufenen conversation_id oder ein Antwortparsing, das bei unerwarteten Einträgen abstürzt – rühren von Verwechslungen zwischen diesen drei Ebenen her. Das Verständnis ihrer Rollen und Beziehungen ist eine Voraussetzung, um überhaupt eine einzige Zeile Code zu schreiben.

Das Agent-Objekt

Ein Agent ist ein Konfigurationsset, das das Verhalten des Modells definiert. Er enthält keine Konversationsdaten: Es handelt sich um eine wiederverwendbare Vorlage, die einmal erstellt wird und von Tausenden von Konversationen referenziert werden kann.

Die Erstellung erfordert mindestens ein Modell, einen Namen und eine Beschreibung.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # LLM-Modell zur Verwendung
    name="My Agent",                     # Menschlich lesbarer Identifier
    description="Agent for financial analysis"  # Aufgabenorientierte Beschreibung
)

Der Parameter model benennt das Modell, das den Agenten antreiben wird, ausgewählt aus verfügbaren Chat-Completion-Modellen wie mistral-medium-latest oder mistral-large-latest. Der name ist ein menschlich lesbarer Identifier, den Sie verwenden, um den Agenten zu finden und zu referenzieren: In einem Projekt mit zwanzig davon ist dies das, was Sie vor dem Durchsuchen von Logs bewahrt, um herauszufinden, welcher Agent die Kunden beantwortet. Die description ist hingegen aufgabenorientiert und dient mehr als nur interner Dokumentation – sie hilft dem Modell, die erwartete Rolle zu verstehen, was die Formulierung „agent for financial analysis” statt einer vagen „agent number 3” erklärt.

Der Rest wird optional konfiguriert, und hier nimmt die eigentliche Persönlichkeit des Agentens Gestalt an.

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 — Der Systemprompt des Agents (definiert Persönlichkeit, Regeln und Stil)
tools — Liste verfügbarer Tools: web_search, web_search_premium, code_interpreter, image_generation, document_library oder benutzerdefinierte Funktionen
completion_args — Sampler-Parameter (temperature, top_p, max_tokens usw.)
guardrails — Eine Liste von Moderationskonfigurationen (moderation_llm_v2), die auf die eingehende Nachricht jeder Konversation des Agents angewendet werden; hier wird Jailbreaking oberhalb von 0,2 blockiert und die Kategorie financial deaktiviert (Schwellenwert 1), da der Agent dafür gebaut ist, Finanzen zu diskutieren. Details finden Sie im Kurs KI-Moderation und Sicherheit mit Mistral.

Im obigen Beispiel erbt der Finanzagent aus seinen Anweisungen die Anforderung nach Quellen, aus seinen Tools die Fähigkeit, eine Zahl zu verifizieren, und eine niedrige Temperatur, die Kreativität dort begrenzt, wo Rigorosität erwartet wird.

Das Conversation-Objekt

Eine Konversation ist die Geschichte der Interaktionen zwischen einem Benutzer und einem Agenten – oder zwischen einem Benutzer und einem Modell allein. Sie enthält Nachrichten, Ergebnisse von Toolausführungen und Handoff-Ereignisse.

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

# Abrufen der Conversation-ID, um später fortzufahren
conversation_id = response.conversation_id

Das Verhalten dieses Objekts birgt einige Überraschungen. Die Konversation ist persistent: Die Geschichte wird auf der Seite von Mistral gespeichert, es sei denn, Sie übergeben store=False. Sie ist unabhängig vom Agenten, was bedeutet, dass eine Konversation ganz gut auch ohne Agent existieren kann, im direkten Modus des Modells. Schließlich ist sie unveränderlich: Jede Ergänzung erzeugt eine neue conversation_id, wobei die alte weiterhin zugänglich bleibt. Dieser letzte Punkt ist der überraschendste: Wenn Sie die anfängliche ID in Ihrer Datenbank speichern und sie bei der dritten Runde wiederverwenden, kehren Sie zum Kontext des ersten Austauschs zurück.

Das Entry-Objekt

Ein Entry ist eine einzelne Aktion innerhalb einer Konversation: die atomare Einheit der Geschichte. Wenn Sie eine Antwort erhalten, enthält das Feld outputs eine Liste von Einträgen, deren Typ davon abhängt, was der Agent getan hat. Ein message.output-Entry trägt eine Textantwort des Agents, also den Text, den Ihre Schnittstelle anzeigen wird. Ein tool.execution-Entry trägt das Ausführungsergebnis eines Tools, wie etwa Code oder eine Websuche: das ausgeführte Skript und sein Ergebnis oder die zurückgegebenen Seiten des Engines. Ein agent.handoff-Entry signalisiert ein Transferereignis an einen anderen Agenten und erscheint daher nur in Szenarios mit mehreren Agenten.

Eine einzelne Antwort mischt diese Typen häufig. Wenn Sie einen agenten mit Tools nach einer Berechnung fragen, erhalten Sie die Ausführung, gefolgt von dem Kommentar dazu: Ihr Code muss daher durch diese Liste iterieren, anstatt ein einzelnes Feld zu lesen.

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

Beziehungen zwischen den Objekten

Das folgende Diagramm fasst die Artikulation der drei Ebenen zusammen: eine wiederverwendbare Konfiguration, ein Geschichtsfaden und Einzelektionen.

Agent (Konfiguration)
  ├── model, instructions, tools, guardrails
  └── Kann von N Konversationen referenziert werden

Conversation (Geschichte)
  ├── Verknüpft mit 0 oder 1 Agenten (optional)
  ├── Enthält N geordnete Einträge
  └── Jede Ergänzung erzeugt eine neue conversation_id

Entry (Einzelektion)
  ├── message.output (Textantwort)
  ├── tool.execution (Tool-Ergebnis)
  └── agent.handoff (Agenten-Transfer)

Konversationsoptionen

Das Starten einer Konversation akzeptiert Einstellungen, die Ihre Compliance genauso stark beeinflussen wie Ihre Architektur, und es ist besser, diese zu entscheiden, als sie zu erleiden. Speicherung zuerst: store=False verhindert jegliches Speichern auf der Seite von Mistral, was Sie verwenden werden, um Daten zu verarbeiten, die Ihre interne Politik verbietet, auf einem Server einer Drittpartei zu belassen.

# Cloud-Speicherung deaktivieren
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Die zweite Einstellung definiert, wer Handoffs ausführt. Im server-Modus, dem Standardwert, ketten Mistral Agenten-Transfers ohne Ihre Intervention; im client-Modus erhalten Sie Handoff-Ereignisse und behalten die Kontrolle, um sie zu protokollieren, zu filtern oder abzulehnen.

# Server-Modus (Standard) — Mistral behandelt Handoffs automatisch
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Client-Modus — Sie erhalten Handoff-Ereignisse und entscheiden, was zu tun ist
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Kernaussagen

Agent = wiederverwendbare Konfiguration (Modell, Anweisungen, Tools, Guardrails)
Conversation = persistente Geschichte, die auf dem Server gespeichert ist und unabhängig vom Agenten ist
Entry = Einzelektion (Nachricht, Toolausführung, Handoff)
Konversationen können ohne einen Agenten existieren (direkter Modus des Modells)
Jede Ergänzung einer Konversation erzeugt eine neue conversation_id
Der Modus store=False verhindert die Speicherung auf der Seite von Mistral