max_turns und Server-/Client-Tools
Auf dieser Seite
Server-Tools und Client-Tools
Die xAI-Plattform unterscheidet zwei Arten von Tools, die Grok in einem Gespräch verwenden kann:
- Server-seitige Tools: Websuche, Codeausführung, X-Suche. Diese Tools laufen automatisch auf den Servern von xAI. Grok ruft sie auf, erhält das Ergebnis und setzt den Vorgang fort, ohne dass Sie eingreifen müssen.
- Client-seitige Tools: Ihre benutzerdefinierten Funktionen (Function Calling). Wenn Grok eine Ihrer Funktionen aufrufen möchte, gibt die API einen Funktionsaufruf an Sie zurück. Ihr Code führt diese aus und sendet das Ergebnis anschließend an die API zurück.
Diese Unterscheidung ist entscheidend für das Verständnis des Verhaltens von max_turns.
Der Parameter max_turns
max_turns steuert die Anzahl der Assistant-/Tool-Runden, die Grok in einer einzelnen API-Anfrage durchführen kann. Jeder Einsatz eines Server-Tools verbraucht eine Runde.
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": "Suchen Sie nach den neuesten Nachrichten zu Python 3.13"}],
tools=[...],
max_turns=5 # Grok kann bis zu 5 Server-Tools verwenden
)
Wenn Grok eine Websuche durchführen muss, dann Code ausführt, um die Ergebnisse zu analysieren, und schließlich eine zweite Suche durchführt, um alles abzuschließen, verbraucht dies 3 Runden. Bei max_turns=5 stehen ihm noch 2 Runden zur Verfügung.
Zurücksetzen über Client-Tools
Ein wichtiges Verhalten, das Sie sich merken sollten: Aufrufe von Client-seitigen Tools setzen den max_turns Zähler zurück. Wenn Ihr Code einen Funktionsaufruf verarbeitet und das Ergebnis in einer neuen API-Anfrage zurückgibt, erhält Grok seine volle Zuteilung für Runden zurück.
# Erste Anfrage: max_turns=3
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3
)
# Grok fordert einen Client-Funktionsaufruf an
if response.choices[0].message.tool_calls:
# Sie führen die Funktion lokal aus
tool_result = execute_tool(response.choices[0].message.tool_calls[0])
# Zweite Anfrage: max_turns wird auf 3 zurückgesetzt
messages.append(response.choices[0].message)
messages.append({"role": "tool", "content": tool_result, ...})
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3 # neuer Zähler
)
Dieses Zurücksetzen ist sinnvoll: Jede API-Anfrage ist unabhängig. Der max_turns-Zähler gilt nur für Runden, die innerhalb derselben Anfrage durchgeführt werden.
Hybride Workflows
Die Kombination aus Server- und Client-Tools ermöglicht komplexe Workflows. Zum Beispiel kann Grok:
- Eine Websuche durchführen (Server-Tool, 1 Runde)
- Code ausführen, um die Ergebnisse zu analysieren (Server-Tool, 1 Runde)
- Ihre benutzerdefinierte Funktion auffordern, die Ergebnisse zu speichern (Client-Tool, Zähler zurücksetzen)
- Eine neue Suche basierend auf den gespeicherten Ergebnheiten durchführen (Server-Tool, 1 Runde mit neuem Zähler)
async def hybrid_workflow(question: str) -> str:
messages = [{"role": "user", "content": question}]
while True:
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=server_and_client_tools,
max_turns=5
)
message = response.choices[0].message
# Wenn kein Client-Tool-Aufruf vorliegt, haben wir die finale Antwort
if not message.tool_calls:
return message.content
# Verarbeiten von Client-Tool-Aufrufen
messages.append(message)
for tool_call in message.tool_calls:
result = await execute_local_tool(tool_call)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result
})
Dieses Schleifenmuster verwaltet automatisch den Hin- und Her-Verkehr zwischen Grok und Ihren lokalen Funktionen. Die Schleife läuft so lange weiter, bis Grok Ihre Tools aufrufen muss. Sie endet, wenn eine finale Textantwort bereitgestellt wird.
Festlegen von max_turns
- max_turns=1: Grok kann nur ein Server-Tool verwenden. Ausreichend für eine einfache Websuche.
- max_turns=3-5: Gutes Gleichgewicht für die meisten Fälle. Grok kann Suche + Analyse + Verifizierung verketten.
- max_turns=10+: Für komplexe Aufgaben, die viele Iterationen erfordern. Achten Sie auf Token-Kosten.
Ein max_turns-Wert, der zu hoch ist, verursacht keine Kosten, wenn er nicht genutzt wird, aber ein max_turns-Wert, der zu niedrig ist, kann das Denken von Grok mitten in einer Aufgabe unterbrechen.
Kernaussagen
- Server-Tools (Websuche, Codeausführung) verbrauchen
max_turns-Runden - Client-Tools (Ihre Funktionen) setzen den Zähler bei jeder neuen Anfrage zurück
- Das
while True-Schleifenmuster verwaltet den Hin- und Her-Verkehr bis zur finalen Antwort - Beginnen Sie mit
max_turns=5und passen Sie den Wert basierend auf der Komplexität Ihrer Aufgabe an - Jede Server-Runde verbraucht zusätzliche Tokens (kumulativer Kontext)