max_turns en server-/clienttools
Op deze pagina
Servertools en clienttools
Het xAI-platform onderscheidt twee soorten tools die Grok tijdens een gesprek kan gebruiken:
- Servertools: webzoekopdrachten, code-uitvoering, X-zoekopdrachten. Deze tools worden automatisch op de servers van xAI uitgevoerd. Grok roept ze aan, ontvangt het resultaat en gaat verder zonder uw tussenkomst.
- Clienttools: uw eigen functies (function calling). Wanneer Grok een van uw functies wil aanroepen, retourneert de API een functieverzoek aan u. Uw code voert deze uit en stuurt het resultaat terug naar de API.
Dit onderscheid is essentieel om het gedrag van max_turns te begrijpen.
De parameter max_turns
max_turns bepaalt het aantal beurten dat Grok voor assistent/tool-acties mag uitvoeren binnen één API-verzoek. Elk gebruik van een servertool verbruikt één beurt.
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": "Search for the latest news on Python 3.13"}],
tools=[...],
max_turns=5 # Grok can use up to 5 server tools
)
Als Grok eerst een webzoekopdracht moet uitvoeren, vervolgens code moet draaien om de resultaten te analyseren en daarna een tweede zoekopdracht moet doen om af te ronden, verbruikt dit 3 beurten. Met max_turns=5 blijven er nog 2 beurten over.
Resetten via clienttools
Belangrijk om te onthouden: het aanroepen van clienttools reset de max_turns-teller. Wanneer uw code een functieverzoek afhandelt en het resultaat terugstuurt in een nieuw API-verzoek, krijgt Grok zijn volledige toewijzing van beurten terug.
# First request: max_turns=3
response = await client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=my_tools,
max_turns=3
)
# Grok requests a client function call
if response.choices[0].message.tool_calls:
# You execute the function locally
tool_result = execute_tool(response.choices[0].message.tool_calls[0])
# Second request: max_turns resets to 3
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 # new counter
)
Deze reset is logisch: elk API-verzoek staat op zichzelf. De max_turns-teller geldt alleen voor beurten die binnen hetzelfde verzoek worden uitgevoerd.
Hybride workflows
Door server- en clienttools te combineren, kunt u complexe workflows opzetten. Grok kan bijvoorbeeld:
- Een webzoekopdracht uitvoeren (servertool, 1 beurt)
- Code uitvoeren om de resultaten te analyseren (servertool, 1 beurt)
- Uw aangepaste functie vragen om de resultaten op te slaan (clienttool, reset)
- Een nieuwe zoekopdracht uitvoeren op basis van de opgeslagen resultaten (servertool, 1 beurt met nieuwe teller)
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
# If no client tool call, we have the final answer
if not message.tool_calls:
return message.content
# Process client tool calls
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
})
Dit luspatroon regelt automatisch de uitwisseling tussen Grok en uw lokale functies. De lus loopt zolang Grok uw tools moet aanroepen. Hij stopt zodra Grok een definitief tekstantwoord geeft.
max_turns instellen
- max_turns=1: Grok mag slechts één servertool gebruiken. Voldoende voor een simpele webzoekopdracht.
- max_turns=3-5: goede balans voor de meeste gevallen. Grok kan zoeken + analyseren + verifiëren chainingen.
- max_turns=10+: voor complexe taken die veel iteraties vereisen. Let op de tokencosten.
Een max_turns-waarde die te hoog is, kost niets als deze niet wordt gebruikt, maar een waarde die te laag is, kan de redenering van Grok halverwege de taak afkappen.
Belangrijkste punten
- Servertools (webzoeken, code-uitvoering) verbruiken
max_turns-beurten - Clienttools (uw functies) resetten de teller bij elk nieuw verzoek
- Het
while True-luspatroon regelt de uitwisseling tot het definitieve antwoord - Begin met
max_turns=5en pas deze aan op basis van de complexiteit van uw taak - Elke serverbeurt verbruikt extra tokens (cumulatieve context)