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 côté serveur : web search, code execution, X search. Ces outils s’exécutent automatiquement sur les serveurs de xAI. Grok les invoque, obtient le résultat, et continue sans intervention de votre part.
• Outils côté client : vos fonctions personnalisées (function calling). Quand Grok veut appeler une de vos fonctions, l’API vous retourne un appel de fonction. Votre code l’exécute, puis renvoie le résultat à l’API.

Cette distinction est importante pour comprendre le comportement de max_turns.

Le paramètre max_turns

max_turns contrôle le nombre de tours assistant/outil que Grok peut effectuer dans une seule requête API. Chaque utilisation d’un outil serveur consomme un tour.

response = await client.chat.completions.create(
    model="grok-4.5",
    messages=[{"role": "user", "content": "Recherche les dernières actualités sur Python 3.13"}],
    tools=[...],
    max_turns=5  # Grok peut utiliser jusqu'à 5 outils serveur
)

Si Grok a besoin de faire une recherche web, puis d’exécuter du code pour analyser les résultats, puis une deuxième recherche pour compléter, cela consomme 3 tours. Avec max_turns=5, il lui reste 2 tours supplémentaires.

Réinitialisation par les outils client

Le comportement clé à retenir : les invocations d’outils côté client réinitialisent le compteur max_turns. Quand votre code traite un appel de fonction et renvoie le résultat dans une nouvelle requête API, Grok retrouve son allocation complète de tours.

# Première requête : max_turns=3
response = await client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=my_tools,
    max_turns=3
)

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

    # Deuxième requête : max_turns repart à 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  # nouveau compteur
    )

Cette réinitialisation est logique : chaque requête API est indépendante. Le compteur max_turns s’applique uniquement aux tours effectués au sein d’une même requête.

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. Exécuter du code pour analyser les résultats (outil serveur, 1 tour)
3. Demander à votre fonction personnalisée de sauvegarder les résultats (outil client, réinitialisation)
4. Faire une nouvelle recherche basée sur les résultats sauvegardés (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.5",
            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 réponse 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 gère automatiquement les allers-retours entre Grok et vos fonctions locales. La boucle continue tant que Grok a besoin d’appeler vos outils. Elle s’arrête quand il fournit une réponse 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 enchaîner recherche + analyse + vérification.
• max_turns=10+ : pour des tâches complexes nécessitant de nombreuses itérations. Attention au coût en tokens.

Un max_turns trop élevé ne coûte rien s’il n’est pas utilisé, mais un max_turns trop bas peut tronquer le raisonnement de Grok au milieu d’une tâche.

Points clés à retenir

• Les outils serveur (web search, code execution) consomment des tours max_turns
• Les outils client (vos fonctions) réinitialisent le compteur à chaque nouvelle requête
• Le pattern en boucle while True gère les allers-retours jusqu’à la réponse finale
• Commencez avec max_turns=5 et ajustez selon la complexité de vos tâches
• Chaque tour serveur consomme des tokens supplémentaires (contexte cumulé)