Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

API mit Tools aufrufen

Lektion 5 von 14 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Tools an die Mistral-API senden
  2. Die erste Anfrage
  3. Verständnis der Modellantwort
  4. Parsen der Antwort und Extrahieren von tool_calls
  5. Wenn das Modell fehlende Informationen anfordert
  6. Handhabung der System-Nachricht
  7. Vollständiger Code für Schritte 2–3
  8. Kernaussagen

Tools an die Mistral-API senden

Sie haben Ihre Funktionen und deren JSON-Spezifikationen definiert. Nun müssen Sie diese an die Mistral-API senden und, noch wichtiger, verstehen, was das Modell zurückgibt. Wir befinden uns nun bei Schritt 2 und 3 des Prozesses: Das Modell erhält die Benutzeranfrage zusammen mit den Tools und erzeugt einen Funktionsaufruf – oder lehnt ihn ab, was ebenso lehrreich ist.

Die erste Anfrage

import os
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Tools aus der vorherigen Lektion definiert
tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Ruft den Status einer Zahlung basierend auf der Transaktions-ID ab.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Einzigartige Transaktionskennung (z. B. T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

# Benutzer-Nachricht
messages = [
    {"role": "user", "content": "Wie ist der Status der Zahlung T1001?"}
]

# API-Aufruf mit Tools
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Verständnis der Modellantwort

Die Antwort enthält ein message-Objekt, das zwei Formen annehmen kann. Ihr Code muss dies von Anfang an berücksichtigen. Im ersten Fall antwortet das Modell direkt, da keine Funktion benötigt wird: content enthält Text, und tool_calls ist None.

# response.choices[0].message.content enthält den Text der Antwort
# response.choices[0].message.tool_calls ist None
print(response.choices[0].message.content)
# → "Hallo! Wie kann ich Ihnen helfen?"

Im zweiten Fall möchte das Modell eine Funktion aufrufen. Die Situation kehrt sich um: content ist leer oder null, und tool_calls enthält die Nutzlast.

# response.choices[0].message.content ist None oder leer
# response.choices[0].message.tool_calls enthält die Aufrufe
message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"Funktion: {tool_call.function.name}")
        print(f"Argumente: {tool_call.function.arguments}")
        print(f"ID: {tool_call.id}")

Typische Ausgabe:

Funktion: retrieve_payment_status
Argumente: {"transaction_id": "T1001"}
ID: call_abc123xyz

Parsen der Antwort und Extrahieren von tool_calls

Hier ist der vollständige Code, um Informationen aus einem Tool-Aufruf sauber zu extrahieren:

message = response.choices[0].message

if message.tool_calls and len(message.tool_calls) > 0:
    tool_call = message.tool_calls[0]

    # Funktionennamen extrahieren
    function_name = tool_call.function.name

    # JSON-Argumente in ein Python-Dictionary parsen
    function_params = json.loads(tool_call.function.arguments)

    # Die eindeutige Kennung des Aufrufs abrufen
    tool_call_id = tool_call.id

    print(f"Das Modell möchte aufrufen: {function_name}")
    print(f"Mit Parametern: {function_params}")
    print(f"Aufruf-ID: {tool_call_id}")
else:
    # Das Modell hat direkt geantwortet
    print(f"Antwort: {message.content}")

Aus diesem Block ergeben sich drei Informationen, und die dritte ist diejenige, die oft übersehen wird. Der Funktionsname dient zur Weiterleitung (Dispatch), die geparsenen Argumente werden für den Aufruf verwendet, aber die tool_call_id ermöglicht es dem Modell, Ihr Ergebnis beim Zurücksenden mit dem korrekten Aufruf zu verknüpfen. Verlieren Sie diese, wird der Gesprächswechsel unrettbar.

Wenn das Modell fehlende Informationen anfordert

Manchmal liefert der Benutzer nicht genügend Informationen. Das Modell verfügt über eine elegante Lösung: Es ruft keine Funktion auf, sondern stellt stattdessen eine klärende Frage.

messages = [
    {"role": "user", "content": "Wie ist der Status meiner Zahlung?"}
]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

message = response.choices[0].message
print(message.content)
# → "Ich benötige die Transaktions-ID, um den Status zu prüfen.
#     Könnten Sie mir bitte die Transaktionsnummer mitteilen?"

Dieses Verhalten ist genau das, was Sie wollen. Das Modell weiß, dass transaction_id in required aufgeführt ist; anstatt eine plausible ID zu erfinden und eine Anfrage für nicht existierende Daten auszulösen, gibt es das Wort an den Benutzer ab. Dies ist auch die beste Demonstration des Nutzens des required-Felds, das in der vorherigen Lektion behandelt wurde.

Handhabung der System-Nachricht

Die System-Nachricht ermöglicht es Ihnen, dieses Verhalten zu rahmen, anstatt darauf zu hoffen, dass es eintritt.

messages = [
    {
        "role": "system",
        "content": "Sie sind ein Assistent zur Verfolgung von Zahlungen. "
                   "Antworten Sie auf Englisch. "
                   "Verwenden Sie die verfügbaren Tools, um Fragen zu Transaktionen zu beantworten. "
                   "Falls der Benutzer die Transaktions-ID nicht bereitstellt, bitten Sie höflich darum."
    },
    {
        "role": "user",
        "content": "Wie ist der Status der Zahlung T1001?"
    }
]

Lesen Sie Zeile für Zeile: Der erste Satz setzt die Rolle, der zweite den Ton und die Sprache des Assistenten fest, der dritte gibt an, wann Funktionen zu verwenden sind, und der letzte gibt eine explizite Anweisung für einen Sonderfall – fehlende Informationen. Dies sind die drei Anwendungsfälle, für die eine System-Nachricht empfohlen wird, und sie reichen in den meisten Fällen aus.

Vollständiger Code für Schritte 2–3

Hier ist der vollständige, wiederverwendbare Code zum Senden einer Anfrage mit Tools. Er kapselt alles oben Genannte und normalisiert die Antwort in ein Dictionary mit zwei Formen, sodass Sie if message.tool_calls-Prüfungen nicht über Ihre gesamte Anwendung verstreuen müssen.

import os
import json
from mistralai.client import Mistral

def call_mistral_with_tools(
    messages: list,
    tools: list,
    model: str = "mistral-large-latest",
    tool_choice: str = "auto"
) -> dict:
    """Sendet eine Anfrage an Mistral mit Tools und gibt die geparte Antwort zurück."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    response = client.chat.complete(
        model=model,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice
    )

    message = response.choices[0].message

    if message.tool_calls and len(message.tool_calls) > 0:
        return {
            "type": "tool_call",
            "message": message,
            "tool_calls": [
                {
                    "id": tc.id,
                    "function_name": tc.function.name,
                    "arguments": json.loads(tc.function.arguments)
                }
                for tc in message.tool_calls
            ]
        }

    return {
        "type": "text",
        "message": message,
        "content": message.content
    }

Beachten Sie, dass der List-Comprehension über alle tool_calls iteriert, nicht nur über den ersten. Das Modell kann mehrere auf einmal erzeugen; eine spätere Lektion wird dies behandeln, aber Ihre Hilfsfunktion ist bereits bereit, sie zu verarbeiten.

Kernaussagen

  • Senden Sie tools und messages an client.chat.complete(), um Funktionsaufrufe zu ermöglichen.
  • Prüfen Sie immer, ob message.tool_calls existiert, bevor Sie versuchen, diese zu parsen.
  • Die tool_call_id ist obligatorisch, um das Ergebnis an das Modell zurückzusenden.
  • Argumente sind eine JSON-String, die mit json.loads() geparsed werden muss.
  • Das Modell kann entscheiden, direkt zu antworten, wenn es keine Funktion benötigt oder wenn Informationen fehlen.