Stellen Sie sich folgendes Szenario vor: Sie haben einen AI-Agenten entwickelt, der Termine verwalten soll. Der Benutzer sagt: „Plane einen Termin mit Dr. Schmidt nächste Woche Dienstag um 14 Uhr." Ihr Agent antwortet höflich, versteht den Kontext perfekt – und tut dann nichts. Der Grund: Ein schlecht konzipiertes Function Schema, das dem Modell nicht klar genug macht, wann und wie es das Werkzeug aufrufen soll.
Oder schlimmer noch: Der Agent ruft das Werkzeug auf, erhält aber einen ConnectionError: timeout oder 401 Unauthorized, weil das Schema keine vernünftige Fehlerbehandlung definiert. In diesem umfassenden Leitfaden erfahren Sie, wie Sie robuste Function Schemas entwickeln, die zuverlässig funktionieren.
Was ist Tool Calling und warum ist das Schema entscheidend?
Tool Calling (auch Function Calling genannt) ermöglicht es AI-Modellen, externe Werkzeuge und APIs zu nutzen. Das Model gibt dabei ein strukturiertes JSON-Objekt zurück, das die aufzurufende Funktion und deren Parameter definiert.
Das Function Schema ist das Herzstück dieser Interaktion. Es besteht aus:
- name: Der eindeutige Name der Funktion
- description: Eine verständliche Erklärung, wann dieses Werkzeug verwendet werden soll
- parameters: Die erwarteten Eingabeparameter im JSON Schema Format
Ein schlecht gestaltetes Schema führt zu falschen Tool-Aufrufen, fehlenden Parametern oder unverständlichen Fehlermeldungen. HolySheep AI bietet hierfür eine besonders zuverlässige API mit <50ms Latenz, die das Testen und Debugging erheblich beschleunigt.
Grundstruktur eines professionellen Function Schemas
Ein hochwertiges Schema folgt dem JSON Schema Standard und enthält alle notwendigen Informationen für das Modell, um fundierte Entscheidungen zu treffen.
{
"name": "get_weather",
"description": "Ruft die aktuelle Wettervorhersage für einen bestimmten Standort ab. Verwende dieses Werkzeug, wenn der Benutzer nach dem Wetter fragt oder planen möchte, ob eine Aktivität wetterabhängig ist.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Der Stadtname oder die GPS-Koordinaten des gesuchten Standorts. Beispiel: 'Berlin' oder '52.5200,13.4050'"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Die Temperatureinheit für die Anzeige. Standard ist 'celsius'.",
"default": "celsius"
}
},
"required": ["location"]
}
}Beachten Sie die drei Schlüsselelemente: präzise description, strukturierte properties und klar definierte required-Felder.
Praxisbeispiel: Terminplanung mit HolySheep AI
Lassen Sie uns ein vollständiges Beispiel durchgehen. Wir erstellen einen Terminplanungs-Agenten mit der HolySheep AI API:
import requests
import json
HolySheep AI Konfiguration
BASE_URL = "https://api.holysheep.ai/v1"
def call_holysheep_tools(user_message):
"""Sendet eine Nachricht mit Tool-Definitionen an HolySheep AI"""
headers = {
"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY",
"Content-Type": "application/json"
}
tools = [
{
"type": "function",
"function": {
"name": "create_appointment",
"description": "Erstellt einen neuen Termin im Kalender. Verwende dieses Werkzeug, wenn der Benutzer einen Termin vereinbaren möchte.",
"parameters": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Der Titel/Betreff des Termins"
},
"date": {
"type": "string",
"format": "date",
"description": "Das Datum im Format YYYY-MM-DD"
},
"time": {
"type": "string",
"description": "Die Uhrzeit im 24-Stunden-Format, z.B. '14:30'"
},
"participants": {
"type": "array",
"items": {"type": "string"},
"description": "Liste der Teilnehmer-E-Mail-Adressen"
},
"duration_minutes": {
"type": "integer",
"minimum": 15,
"maximum": 480,
"default": 60,
"description": "Dauer des Termins in Minuten"
}
},
"required": ["title", "date", "time"]
}
}
},
{
"type": "function",
"function": {
"name": "search_available_slots",
"description": "Sucht freie Terminslots basierend auf Datum und Präferenzen. Verwende dieses Werkzeug, um Verfügbarkeiten zu prüfen, bevor ein Termin erstellt wird.",
"parameters": {
"type": "object",
"properties": {
"start_date": {"type": "string", "format": "date"},
"end_date": {"type": "string", "format": "date"},
"preferred_time_of_day": {
"type": "string",
"enum": ["morning", "afternoon", "evening", "any"]
}
},
"required": ["start_date", "end_date"]
}
}
}
]
payload = {
"model": "gpt-4.1", # Nur $8/MTok bei HolySheep
"messages": [
{"role": "system", "content": "Du bist ein professioneller Terminplanungsassistent."},
{"role": "user", "content": user_message}
],
"tools": tools,
"tool_choice": "auto"
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers=headers,
json=payload
)
return response.json()
Beispiel-Aufruf
result = call_holysheep_tools(
"Plane einen Termin mit [email protected] für nächsten Dienstag um 14 Uhr"
)
print(json.dumps(result, indent=2, ensure_ascii=False))Dieses Beispiel demonstriert mehrere Best Practices, die wir im nächsten Abschnitt vertiefen.
Best Practices für hochwertige Function Schemas
1. Deskriptive und kontextreiche Beschreibungen
Die description-Felder sind entscheidend für die Modell-Performance. Verwenden Sie:
- Klare Anwendungsfälle: Wann soll dieses Werkzeug verwendet werden?
- Kontextbezogene Hinweise: Welche Informationen sind wichtig?
- Vermeidung von Mehrdeutigkeiten: Was sollte explizit vermieden werden?
# ❌ Schlecht: Zu vage
"description": "Ruft Informationen ab."
✅ Gut: Kontextbezogen und handlungsorientiert
"description": "Ruft aktuelle Wetterdaten ab. Verwende dieses Werkzeug, wenn der Benutzer das Wetter für einen bestimmten Tag oder Ort wissen möchte, oder bevor Aktivitäten im Freien geplant werden. Gibt Temperatur, Niederschlagswahrscheinlichkeit und Windgeschwindigkeit zurück."2. Präzise Parameterdefinitionen
Jeder Parameter sollte klar definiert sein:
- Verwenden Sie
enumfür eingeschränkte Wertebereiche - Definieren Sie
minimumundmaximumfür numerische Werte - Nutzen Sie
default-Werte für optionale Parameter - Fügen Sie
formatfür Datums- und Zeitangaben hinzu
"email": {
"type": "string",
"format": "email",
"description": "Gültige E-Mail-Adresse im Format [email protected]"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 3,
"description": "Prioritätsstufe von 1 (niedrigste) bis 5 (höchste Dringlichkeit)"
},
"status": {
"type": "string",
"enum": ["pending", "in_progress", "completed", "cancelled"],
"description": "Aktueller Status des Vorgangs"
}3. Verschachtelte Objekte und Arrays
Komplexe Datenstrukturen erfordern eine rekursive Definition:
"shipping_address": {
"type": "object",
"description": "Vollständige Lieferadresse",
"properties": {
"street": {"type": "string"},
"city": {"type": "string"},
"postal_code": {"type": "string", "pattern": "^[0-9]{5}$"},
"country": {"type": "string"}
},
"required": ["street", "city", "postal_code"]
},
"items": {
"type": "array",
"description": "Liste der zu bestellenden Produkte",
"items": {
"type": "object",
"properties": {
"product_id": {"type": "string"},
"quantity": {"type": "integer", "minimum": 1},
"special_instructions": {"type": "string"}
},
"required": ["product_id", "quantity"]
},
"minItems": 1
}Häufige Fehler und Lösungen
Fehler 1: ConnectionError: timeout
Ursache: Das Modell generiert wiederholt Tool-Aufrufe, ohne auf Ergebnisse zu warten, oder die API-Antwortzeit ist zu hoch.
Lösung:
- Implementieren Sie einen Retry-Mechanismus mit exponentieller Backoff-Strategie
- Fügen Sie Timeouts für API-Anfragen hinzu
- Nutzen Sie HolySheeps <50ms Latenz für schnellere Antworten
- Begrenzen Sie die Anzahl aufeinanderfolgender Tool-Aufrufe (z.B. max 5)
import time
from requests.exceptions import ConnectionError, Timeout
def call_with_retry(messages, max_retries=3):
"""Führt API-Aufrufe mit Retry-Logik durch"""
for attempt in range(max_retries):
try:
response = requests.post(
f"{BASE_URL}/chat/completions",
headers=headers,
json={"model": "gpt-4.1", "messages": messages, "tools": tools},
timeout=30 # 30 Sekunden Timeout
)
return response.json()
except (ConnectionError, Timeout) as e:
if attempt == max_retries - 1:
raise Exception(f"API nicht erreichbar nach {max_retries} Versuchen: {e}")
# Exponentielle Backoff: 1s, 2s, 4s
wait_time = 2 ** attempt
time.sleep(wait_time)
continueFehler 2: 401 Unauthorized
Ursache: Ungültiger oder fehlender API-Schlüssel.
Lösung:
- Überprüfen Sie, ob der API-Schlüssel korrekt formatiert ist
- Stellen Sie sicher, dass der Schlüssel nicht abgelaufen ist
- Prüfen Sie die Zugriffsrechte für spezifische Endpunkte
- Nutzen Sie Umgebungsvariablen statt hardcodierter Schlüssel
import os
✅ Sicher: Aus Umgebungsvariable laden
api_key = os.environ.get("HOLYSHEEP_API_KEY")
if not api_key:
# Fallback für HolySheep kostenlose Credits
api_key = os.environ.get("HOLYSHEEP_FREE_KEY", "")
if not api_key:
raise ValueError(
"API-Schlüssel nicht gefunden. "
"Registrieren Sie sich bei HolySheep AI für kostenlose Credits: "
"https://holysheep.ai/register"
)
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}Fehler 3: Ungültige Tool-Aufrufe (Schema-Mismatch)
Ursache: Das Modell generiert Parameter, die nicht dem Schema entsprechen.
Lösung:
- Validieren Sie Tool-Aufrufe serverseitig vor der Ausführung
- Verwenden Sie strikte JSON-Schema-Validierung
- Senden Sie informative Fehlermeldungen zurück ans Modell
- Verbessern Sie die Parameter-Beschreibungen basierend auf Fehlermustern
from jsonschema import validate, ValidationError
def execute_tool_safely(tool_call, available_tools):
"""Valideert und führt Tool-Aufrufe sicher aus"""
tool_name = tool_call["function"]["name"]
arguments = tool_call["function"]["arguments"]
# Finde das entsprechende Schema
tool_schema = next(
(t["function"] for t in available_tools if t["function"]["name"] == tool_name),
None
)
if not tool_schema:
return {
"role": "tool",
"tool_call_id": tool_call["id"],
"content": f"Fehler: Werkzeug '{tool_name}' nicht gefunden."
}
try:
# Validiere gegen das Schema
validate(instance=arguments, schema=tool_schema["parameters"])
# Führe das Werkzeug aus
result = execute_tool(tool_name, arguments)
return {
"role": "tool",
"tool_call_id": tool_call["id"],
"content": json.dumps(result)
}
except ValidationError as e:
return {
"role": "tool",
"tool_call_id": tool_call["id"],
"content": f"Validierungsfehler: {e.message}. Bitte überprüfen Sie die Parameter."
}Fehler 4: Endlosschleifen bei Tool-Aufrufen
Ursache: Das Modell ruft kontinuierlich Werkzeuge auf, ohne zu einem Ergebnis zu kommen.
Lösung:
- Implementieren Sie eine maximale Iterationsgrenze
- Fügen Sie eine Stopp-Bedingung in die System-Prompt ein
- Ermöglichen Sie dem Modell, direkt zu antworten, wenn keine weiteren Werkzeuge nötig sind
MAX_TOOL_ITERATIONS = 10
def chat_with_tools(messages):
"""Verarbeitet Nachrichten mit Tool-Aufrufen"""
iteration_count = 0
while iteration_count < MAX_TOOL_ITERATIONS:
response = call_holysheep_api(messages)
if not response.get("choices")[0