Tools in JSON definieren

Von der Theorie zur Praxis

Sie verstehen nun das Konzept des Funktionsaufrufs und die Struktur von JSON-Schemas. Es ist Zeit, zur konkreten Implementierung überzugehen. In dieser Lektion erfahren Sie, wie Sie eine vollständige Anfrage mit Tool-Definitionen erstellen und die Antwort des Modells verarbeiten.

Anfragestruktur mit Tools

Hier ist eine vollständige Anfrage an die Grok-API mit einem definierten Tool:

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "default": "celsius"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "user", "content": "What's the weather like in Paris?"}
    ],
    tools=tools
)

Beachten Sie die verschachtelte Struktur: Das tools-Objekt enthält ein Array, wobei jedes Element ein type und ein function-Objekt mit den Details aufweist.

Implementierungsschwerpunkte

Verarbeitung der tool_call-Antwort

Wenn das Modell entscheidet, eine Funktion aufzurufen, enthält die Antwort ein tool_calls-Array:

message = response.choices[0].message

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

Das Feld tool_call.function.arguments ist eine JSON-Zeichenkette (kein Python-Objekt). Sie müssen diese parsen:

import json

args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")

Ausführung und Rückgabe des Ergebnisses

Sobald die Funktion ausgeführt wurde, senden Sie das Ergebnis in einem zweiten Aufruf an das Modell zurück:

import json

# 1. Funktion ausführen
weather_data = get_weather(city="Paris", unit="celsius")

# 2. Nachrichten mit dem Ergebnis erstellen
messages = [
    {"role": "user", "content": "What's the weather like in Paris?"},
    message,  # Die Modellantwort mit tool_calls
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(weather_data)
    }
]

# 3. Das Modell erneut mit dem Ergebnis aufrufen
final_response = client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=tools
)

print(final_response.choices[0].message.content)

Die Nachricht mit der Rolle tool muss enthalten:

• tool_call_id: die eindeutige Kennzeichnung des tool_calls (zur Verknüpfung mit der Anfrage)
• content: das Ergebnis als JSON-Zeichenkette

Mehrere Tools definieren

Sie können in dem tools-Array so viele Tools deklarieren, wie benötigt werden:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_restaurants",
            "description": "Search for restaurants by city and cuisine type",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "book_table",
            "description": "Book a table at a restaurant",
            "parameters": { ... }
        }
    }
]

Das Modell wählt automatisch die relevanten Tool(s) basierend auf der Benutzeranfrage aus.

Prüfung von finish_reason

Das Feld finish_reason in der Antwort gibt an, ob das Modell seine Antwort abgeschlossen hat oder auf ein Tool-Ergebnis wartet:

finish_reason = response.choices[0].finish_reason

if finish_reason == "tool_calls":
    # Das Modell wartet auf das Ergebnis eines oder mehrerer Tools
    handle_tool_calls(response)
elif finish_reason == "stop":
    # Das Modell hat seine Antwort abgeschlossen
    print(response.choices[0].message.content)

Kernaussagen

• Die Anfrage enthält messages und tools (Definitionen)
• Argumente für tool_calls sind eine JSON-Zeichenkette, die geparsed werden muss
• Senden Sie das Ergebnis in einer Nachricht mit der Rolle tool, einschließlich der tool_call_id
• Prüfen Sie finish_reason, um zu wissen, ob das Modell auf ein Ergebnis wartet
• Sie können mehrere Tools deklarieren – das Modell wählt automatisch