Mélange d'outils serveur et client

Workflows hybrides

La véritable puissance de la Responses API se révèle quand vous combinez des outils serveur (exécutés automatiquement par xAI) et des outils client (vos fonctions personnalisées) dans une même requête. Le modèle orchestre ces outils de manière autonome, créant des workflows complexes en quelques lignes de code.

Combiner outils serveur et fonctions

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Recherche les derniers résultats de foot en Ligue 1 et envoie un résumé à mon équipe.",
    tools=[
        {"type": "web_search"},
        {
            "type": "function",
            "name": "send_team_message",
            "description": "Envoie un message à l'équipe via Slack",
            "parameters": {
                "type": "object",
                "properties": {
                    "channel": {"type": "string"},
                    "message": {"type": "string"}
                },
                "required": ["channel", "message"]
            }
        }
    ]
)

Dans ce scénario, le modèle :

1. Lance web_search automatiquement (côté serveur) pour trouver les résultats
2. Intègre les données dans un résumé
3. Appelle send_team_message (côté client) pour que votre code envoie le message Slack

Le flux d’exécution hybride

Le flux diffère selon le type d’outil :

Outils serveur uniquement

Requête → [modèle → web_search → résultat → modèle] → Réponse finale

Tout se passe côté xAI. Vous recevez directement la réponse finale avec les résultats intégrés.

Outils client uniquement

Requête → [modèle → function_call] → PAUSE
Votre code exécute la fonction
Résultat → [modèle] → Réponse finale

Le modèle met en pause, votre code exécute, puis vous renvoyez le résultat.

Flux hybride

Requête → [modèle → web_search → résultat → modèle → function_call] → PAUSE
Votre code exécute la fonction
Résultat → [modèle] → Réponse finale

Le modèle utilise d’abord les outils serveur (automatiquement), puis appelle votre fonction quand il a besoin de votre infrastructure.

Patterns de combinaison courants

Recherche + Action

Combinez web_search ou x_search avec une fonction d’action :

tools = [
    {"type": "web_search"},
    {"type": "x_search"},
    {
        "type": "function",
        "name": "create_report",
        "description": "Crée un rapport dans le CRM",
        "parameters": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "content": {"type": "string"},
                "tags": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["title", "content"]
        }
    }
]

Calcul + Notification

Combinez code_interpreter avec une fonction de notification :

tools = [
    {"type": "code_interpreter"},
    {
        "type": "function",
        "name": "send_alert",
        "description": "Envoie une alerte si un seuil est dépassé",
        "parameters": {
            "type": "object",
            "properties": {
                "metric": {"type": "string"},
                "value": {"type": "number"},
                "threshold": {"type": "number"}
            },
            "required": ["metric", "value"]
        }
    }
]

max_turns et outils hybrides

Le comportement de max_turns est important dans un contexte hybride :

• max_turns limite les tours côté serveur dans une seule requête
• Quand le modèle appelle une fonction client et que votre code renvoie le résultat, une nouvelle allocation de max_turns commence

En pratique, cela signifie que les appels client n’épuisent pas votre budget de tours serveur. Le modèle peut effectuer 3 recherches web, appeler votre fonction, puis effectuer 3 recherches supplémentaires après réception du résultat.

Contexte multi-tour avec stockage

Pour des workflows complexes qui s’étalent sur plusieurs interactions, combinez le stockage et le chaînage :

# Tour 1 : recherche initiale
r1 = client.responses.create(
    model="grok-4.20-reasoning",
    input="Analyse les tendances du marché de l'IA.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}],
    store=True,
    max_turns=5
)

# Tour 2 : approfondir avec vos données internes
r2 = client.responses.create(
    model="grok-4.20-reasoning",
    input="Compare avec nos données internes.",
    tools=[{
        "type": "function",
        "name": "query_internal_db",
        "description": "Interroge la base de données interne",
        "parameters": {"type": "object", "properties": {"query": {"type": "string"}}}
    }],
    previous_response_id=r1.id,
    store=True
)

Points clés à retenir

• Combinez outils serveur et fonctions client dans une même requête pour des workflows hybrides
• Les outils serveur s’exécutent automatiquement, les fonctions client mettent en pause la génération
• max_turns se réinitialise après chaque aller-retour client
• Les patterns courants : recherche + action, calcul + notification, agrégation multi-sources
• Utilisez store: true et previous_response_id pour des workflows multi-tour