max_turns et outils serveur/client

Outils serveur et outils client

La plateforme xAI distingue deux types d’outils que Grok peut utiliser dans une conversation :

• Outils cote serveur : web search, code execution, X search. Ces outils s’executent automatiquement sur les serveurs de xAI. Grok les invoque, obtient le resultat, et continue sans intervention de votre part.
• Outils cote client : vos fonctions personnalisees (function calling). Quand Grok veut appeler une de vos fonctions, l’API vous retourne un appel de fonction. Votre code l’execute, puis renvoie le resultat a l’API.

Cette distinction est importante pour comprendre le comportement de max_turns.

Le parametre max_turns

max_turns controle le nombre de tours assistant/outil que Grok peut effectuer dans une seule requete API. Chaque utilisation d’un outil serveur consomme un tour.

response = await client.chat.completions.create(
    model="grok-4",
    messages=[{"role": "user", "content": "Recherche les dernieres actualites sur Python 3.13"}],
    tools=[...],
    max_turns=5  # Grok peut utiliser jusqu'a 5 outils serveur
)

Si Grok a besoin de faire une recherche web, puis d’executer du code pour analyser les resultats, puis une deuxieme recherche pour completer, cela consomme 3 tours. Avec max_turns=5, il lui reste 2 tours supplementaires.

Reinitialisation par les outils client

Le comportement cle a retenir : les invocations d’outils cote client reinitialisent le compteur max_turns. Quand votre code traite un appel de fonction et renvoie le resultat dans une nouvelle requete API, Grok retrouve son allocation complete de tours.

# Premiere requete : max_turns=3
response = await client.chat.completions.create(
    model="grok-4",
    messages=messages,
    tools=my_tools,
    max_turns=3
)

# Grok demande un appel de fonction client
if response.choices[0].message.tool_calls:
    # Vous executez la fonction localement
    tool_result = execute_tool(response.choices[0].message.tool_calls[0])

    # Deuxieme requete : max_turns repart a 3
    messages.append(response.choices[0].message)
    messages.append({"role": "tool", "content": tool_result, ...})

    response = await client.chat.completions.create(
        model="grok-4",
        messages=messages,
        tools=my_tools,
        max_turns=3  # nouveau compteur
    )

Cette reinitialisation est logique : chaque requete API est independante. Le compteur max_turns s’applique uniquement aux tours effectues au sein d’une meme requete.

Workflows hybrides

La combinaison d’outils serveur et client permet des workflows complexes. Grok peut par exemple :

1. Faire une recherche web (outil serveur, 1 tour)
2. Executer du code pour analyser les resultats (outil serveur, 1 tour)
3. Demander a votre fonction personnalisee de sauvegarder les resultats (outil client, reinitialisation)
4. Faire une nouvelle recherche basee sur les resultats sauvegardes (outil serveur, 1 tour avec nouveau compteur)

async def hybrid_workflow(question: str) -> str:
    messages = [{"role": "user", "content": question}]

    while True:
        response = await client.chat.completions.create(
            model="grok-4",
            messages=messages,
            tools=server_and_client_tools,
            max_turns=5
        )

        message = response.choices[0].message

        # Si pas d'appel d'outil client, on a la reponse finale
        if not message.tool_calls:
            return message.content

        # Traiter les appels d'outils client
        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
            })

Ce pattern en boucle gere automatiquement les allers-retours entre Grok et vos fonctions locales. La boucle continue tant que Grok a besoin d’appeler vos outils. Elle s’arrete quand il fournit une reponse textuelle finale.

Dimensionner max_turns

• max_turns=1 : Grok ne peut utiliser qu’un seul outil serveur. Suffisant pour une recherche web simple.
• max_turns=3-5 : bon compromis pour la plupart des cas. Grok peut enchainer recherche + analyse + verification.
• max_turns=10+ : pour des taches complexes necessitant de nombreuses iterations. Attention au cout en tokens.

Un max_turns trop eleve ne coute rien s’il n’est pas utilise, mais un max_turns trop bas peut tronquer le raisonnement de Grok au milieu d’une tache.

Points cles a retenir

• Les outils serveur (web search, code execution) consomment des tours max_turns
• Les outils client (vos fonctions) reinitialisent le compteur a chaque nouvelle requete
• Le pattern en boucle while True gere les allers-retours jusqu’a la reponse finale
• Commencez avec max_turns=5 et ajustez selon la complexite de vos taches
• Chaque tour serveur consomme des tokens supplementaires (contexte cumule)