Fonctions personnalisées (function calling)

Connecter Grok à vos propres services

Les outils serveur (web_search, x_search, code_interpreter) sont pratiques mais limités aux services xAI. Avec les fonctions personnalisées de type function, vous pouvez connecter Grok à n’importe quelle API ou service de votre infrastructure.

Principe de fonctionnement

Le function calling suit un cycle en trois étapes :

1. Déclaration : vous décrivez vos fonctions (nom, description, paramètres) dans la requête
2. Appel : le modèle génère un appel de fonction avec les arguments appropriés et met en pause la génération
3. Résultat : votre code exécute la fonction, puis vous renvoyez le résultat au modèle pour qu’il formule sa réponse

Déclarer une fonction

{
  "model": "grok-4.20-reasoning",
  "input": "Réserve-moi une table pour 2 personnes ce soir à 20h.",
  "tools": [{
    "type": "function",
    "name": "book_restaurant",
    "description": "Réserve une table dans un restaurant",
    "parameters": {
      "type": "object",
      "properties": {
        "restaurant_name": {
          "type": "string",
          "description": "Nom du restaurant"
        },
        "date": {
          "type": "string",
          "description": "Date au format YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "description": "Heure au format HH:MM"
        },
        "guests": {
          "type": "integer",
          "description": "Nombre de convives"
        }
      },
      "required": ["date", "time", "guests"]
    }
  }]
}

La description de chaque fonction et de chaque paramètre est cruciale. Le modèle s’en sert pour décider quand appeler la fonction et comment remplir les arguments.

Recevoir l’appel de fonction

Quand le modèle décide d’appeler votre fonction, la réponse contient un élément function_call :

{
  "id": "resp-xyz789",
  "status": "completed",
  "output": [{
    "type": "function_call",
    "name": "book_restaurant",
    "arguments": "{\"date\": \"2026-04-03\", \"time\": \"20:00\", \"guests\": 2}",
    "call_id": "call-abc123"
  }]
}

Le champ arguments est une chaîne JSON que vous devez parser. Le call_id identifie cet appel spécifique.

Renvoyer le résultat

Après avoir exécuté la fonction dans votre code, renvoyez le résultat :

import json

# 1. Requête initiale
response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quel temps fait-il à Paris ?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Récupère la météo actuelle",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }]
)

# 2. Vérifier si le modèle veut appeler une fonction
for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)

        # 3. Exécuter votre fonction
        weather_data = get_weather_from_api(args["city"])

        # 4. Renvoyer le résultat au modèle
        final = client.responses.create(
            model="grok-4.20-reasoning",
            input=[{
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather_data)
            }],
            previous_response_id=response.id
        )
        print(final.output[0].content[0].text)

Bonnes pratiques pour les descriptions

Le modèle se base sur les descriptions pour comprendre vos fonctions. Soyez précis :

{
  "name": "search_products",
  "description": "Recherche des produits dans le catalogue e-commerce. Retourne les 10 premiers résultats triés par pertinence. Supporte la recherche par nom, catégorie ou fourchette de prix.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Termes de recherche (nom du produit, marque, mot-clé)"
      },
      "category": {
        "type": "string",
        "enum": ["electronique", "vetements", "maison", "sport"],
        "description": "Catégorie de produits à filtrer"
      },
      "max_price": {
        "type": "number",
        "description": "Prix maximum en euros"
      }
    },
    "required": ["query"]
  }
}

Utilisez des enum pour les valeurs prédéfinies, des description détaillées pour chaque paramètre, et marquez comme required uniquement les paramètres indispensables.

Gestion des erreurs

Si votre fonction échoue, renvoyez l’erreur comme résultat :

try:
    result = call_external_api(args)
    output = json.dumps(result)
except Exception as e:
    output = json.dumps({"error": str(e)})

final = client.responses.create(
    model="grok-4.20-reasoning",
    input=[{
        "type": "function_call_output",
        "call_id": call_id,
        "output": output
    }],
    previous_response_id=response.id
)

Le modèle interprète l’erreur et peut reformuler sa réponse ou tenter une approche différente.

Points clés à retenir

• Les fonctions personnalisées connectent Grok à vos propres services
• Le cycle est : déclarer, recevoir l’appel, exécuter, renvoyer le résultat
• Les descriptions de fonctions et de paramètres guident le choix du modèle
• Le champ arguments est une chaîne JSON à parser côté client
• Renvoyez les erreurs comme résultat pour que le modèle puisse s’adapter