Vai al contenuto principale
Italiano— Scegli una lingua
Menu

max_turns e strumenti Server/Client

Lezione 8 di 12 Aggiornata il 30 luglio 2026 Avanzato
In questa pagina
  1. Strumenti Server e Strumenti Client
  2. Il parametro max_turns
  3. Reset tramite strumenti Client
  4. Flussi di lavoro ibridi
  5. Impostazione di max_turns
  6. Punti chiave

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ò:

  1. Eseguire una ricerca web (strumento server, 1 turno)
  2. Eseguire codice per analizzare i risultati (strumento server, 1 turno)
  3. Chiedere alla tua funzione personalizzata di salvare i risultati (strumento client, reset)
  4. 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 True gestisce l’andirivieni fino alla risposta finale
  • Inizia con max_turns=5 e regola in base alla complessità del tuo compito
  • Ogni turno server consuma token aggiuntivi (contesto cumulativo)