max_turns e strumenti Server/Client
In questa pagina
Strumenti Server e Strumenti Client
La piattaforma xAI distingue due tipi di strumenti che Grok può utilizzare durante una conversazione:
- Strumenti lato server: ricerca web, esecuzione di codice, ricerca su X. Questi strumenti vengono eseguiti automaticamente sui server di xAI. Grok li invoca, ottiene il risultato e prosegue senza alcun tuo intervento.
- Strumenti lato client: le tue funzioni personalizzate (chiamate di funzione). Quando Grok desidera chiamare una delle tue funzioni, l’API restituisce una chiamata di funzione a te. Il tuo codice la esegue, quindi invia il risultato all’API.
Questa distinzione è fondamentale per comprendere il comportamento di max_turns.
Il parametro max_turns
max_turns controlla il numero di turni assistente/strumento che Grok può eseguire in una singola richiesta API. Ogni utilizzo di uno strumento server consuma un turno.
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
)
Se Grok deve eseguire una ricerca web, poi analizzare i risultati tramite codice ed infine effettuare una seconda ricerca per concludere, ciò consuma 3 turni. Con max_turns=5, gli restano 2 turni disponibili.
Reset tramite strumenti Client
Comportamento chiave da ricordare: le invocazioni di strumenti lato client azzerano il contatore max_turns. Quando il tuo codice gestisce una chiamata di funzione e restituisce il risultato in una nuova richiesta API, Grok recupera l’intera allocazione di turni.
# 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
)
Questo reset ha senso: ogni richiesta API è indipendente. Il contatore max_turns si applica solo ai turni eseguiti all’interno della stessa richiesta.
Flussi di lavoro ibridi
Combinare strumenti server e client consente di creare flussi di lavoro complessi. Ad esempio, Grok può:
- Eseguire una ricerca web (strumento server, 1 turno)
- Eseguire codice per analizzare i risultati (strumento server, 1 turno)
- Chiedere alla tua funzione personalizzata di salvare i risultati (strumento client, reset)
- Eseguire una nuova ricerca basata sui risultati salvati (strumento server, 1 turno con nuovo contatore)
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
})
Questo schema a ciclo gestisce automaticamente l’andirivieni tra Grok e le tue funzioni locali. Il ciclo continua finché Grok ha bisogno di chiamare i tuoi strumenti. Si interrompe quando fornisce una risposta testuale finale.
Impostazione di max_turns
- max_turns=1: Grok può utilizzare un solo strumento server. Sufficiente per una semplice ricerca web.
- max_turns=3-5: buon equilibrio per la maggior parte dei casi. Grok può concatenare ricerca + analisi + verifica.
- max_turns=10+: per compiti complessi che richiedono molte iterazioni. Attenzione ai costi in token.
Un valore di max_turns troppo alto non comporta costi se non utilizzato, ma un valore troppo basso può troncare il ragionamento di Grok a metà compito.
Punti chiave
- Gli strumenti server (ricerca web, esecuzione codice) consumano turni
max_turns - Gli strumenti client (le tue funzioni) azzerano il contatore ad ogni nuova richiesta
- Lo schema a ciclo
while Truegestisce l’andirivieni fino alla risposta finale - Inizia con
max_turns=5e regola in base alla complessità del tuo compito - Ogni turno server consuma token aggiuntivi (contesto cumulativo)