Comment construire des agents IA avec l'appel de fonctions Gemma 4

Gemma 4 est livré avec un support natif de l'appel de fonctions, ce qui signifie que vous pouvez construire des agents IA qui ne se contentent pas de générer du texte — ils prennent des actions. Appeler des API, interroger des bases de données, chercher sur le web, faire des calculs. Ce guide vous montre comment construire un agent fonctionnel à partir de zéro en utilisant Gemma 4 et Python.

Qu'est-ce que l'appel de fonctions ?

L'appel de fonctions laisse le modèle décider quand utiliser des outils externes au lieu de deviner une réponse. Au lieu de demander à Gemma 4 « quel temps fait-il à Tokyo ? » et obtenir une réponse hallucinée, le modèle produit une requête structurée pour appeler votre API météo, vous l'exécutez, renvoyez le résultat, et le modèle génère une réponse en langage naturel basée sur des données réelles.

Le flux ressemble à ça :

Utilisateur : "Quel temps fait-il à Tokyo ?"
  → Modèle : {"function": "get_weather", "args": {"city": "Tokyo"}}
  → Votre code appelle l'API météo → retourne {"temp": 22, "condition": "sunny"}
  → Modèle : "Il fait 22°C et ensoleillé à Tokyo en ce moment."

Définir les outils avec un schéma JSON

D'abord, vous devez dire à Gemma 4 quels outils sont disponibles. Chaque outil est défini avec un schéma JSON qui décrit son nom, son but et ses paramètres :

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle pour une ville. À utiliser quand l'utilisateur demande les conditions météo.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Nom de la ville, par exemple 'Tokyo', 'New York'"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Unité de température"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Effectuer des calculs mathématiques. À utiliser pour tout calcul demandé par l'utilisateur.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "Expression mathématique à évaluer, par exemple '2 + 2', 'sqrt(144)'"
                    }
                },
                "required": ["expression"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "Rechercher sur le web des informations actuelles. À utiliser quand l'utilisateur demande des événements récents ou des faits dont vous n'êtes pas sûr.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Requête de recherche"
                    },
                    "num_results": {
                        "type": "integer",
                        "description": "Nombre de résultats à retourner (défaut : 3)"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

De bonnes descriptions d'outils sont critiques. Le modèle les utilise pour décider quel outil appeler et quand. Soyez spécifique sur quand chaque outil doit être utilisé.

Construire la boucle d'agent

Voici un agent Python complet qui utilise Gemma 4 via l'API Ollama :

import json
import requests
import math

OLLAMA_URL = "http://localhost:11434/api/chat"
MODEL = "gemma4:12b"

# Définir vos implémentations d'outils
def get_weather(city: str, unit: str = "celsius") -> dict:
    """API météo simulée — remplacez par un vrai appel API"""
    # En production, appelez OpenWeatherMap, WeatherAPI, etc.
    return {
        "city": city,
        "temperature": 22,
        "unit": unit,
        "condition": "sunny",
        "humidity": 45
    }

def calculate(expression: str) -> dict:
    """Évaluation mathématique sécurisée"""
    allowed_names = {
        "sqrt": math.sqrt,
        "sin": math.sin,
        "cos": math.cos,
        "pi": math.pi,
        "e": math.e,
        "abs": abs,
        "round": round
    }
    try:
        result = eval(expression, {"__builtins__": {}}, allowed_names)
        return {"expression": expression, "result": result}
    except Exception as e:
        return {"expression": expression, "error": str(e)}

def web_search(query: str, num_results: int = 3) -> dict:
    """Recherche web simulée — remplacez par une vraie API de recherche"""
    return {
        "query": query,
        "results": [
            {"title": f"Résultat sur {query}", "snippet": "Information pertinente..."}
        ]
    }

# Mapper les noms de fonctions aux implémentations
TOOL_MAP = {
    "get_weather": get_weather,
    "calculate": calculate,
    "web_search": web_search,
}

def call_gemma(messages: list, tools: list) -> dict:
    """Envoyer une requête chat à Gemma 4 via Ollama"""
    response = requests.post(OLLAMA_URL, json={
        "model": MODEL,
        "messages": messages,
        "tools": tools,
        "stream": False
    })
    return response.json()

def run_agent(user_input: str, tools: list, max_steps: int = 5):
    """Exécuter la boucle d'agent avec utilisation multi-étapes des outils"""
    messages = [
        {
            "role": "system",
            "content": "Tu es un assistant serviable. Utilise les outils fournis quand nécessaire. Utilise toujours les outils pour la météo, les calculs et les informations actuelles au lieu de deviner."
        },
        {"role": "user", "content": user_input}
    ]

    for step in range(max_steps):
        response = call_gemma(messages, tools)
        message = response["message"]

        # Vérifier si le modèle veut appeler un outil
        if "tool_calls" in message and message["tool_calls"]:
            # Traiter chaque appel d'outil
            for tool_call in message["tool_calls"]:
                func_name = tool_call["function"]["name"]
                func_args = tool_call["function"]["arguments"]

                print(f"  → Appel de {func_name}({func_args})")

                # Exécuter l'outil
                if func_name in TOOL_MAP:
                    result = TOOL_MAP[func_name](**func_args)
                else:
                    result = {"error": f"Outil inconnu : {func_name}"}

                # Ajouter l'appel d'outil et le résultat aux messages
                messages.append(message)
                messages.append({
                    "role": "tool",
                    "content": json.dumps(result)
                })
        else:
            # Le modèle a donné une réponse texte finale
            print(f"Agent : {message['content']}")
            return message["content"]

    return "L'agent a atteint le maximum d'étapes sans terminer."

# Exécuter l'agent
if __name__ == "__main__":
    run_agent("Quel temps fait-il à Tokyo et combien fait 15% de 8500 ?", tools)

Cet agent peut gérer des requêtes multi-étapes. Quand vous demandez « Quel temps fait-il à Tokyo et combien fait 15% de 8500 ? », Gemma 4 appellera get_weather et calculate séparément, puis combinera les deux résultats en une seule réponse naturelle.

Patterns d'agent multi-étapes

Les vrais agents ont souvent besoin d'enchaîner plusieurs appels d'outils où les appels suivants dépendent des résultats précédents :

# Exemple : "Trouve des restaurants près de moi et vérifie la météo là-bas"
# Étape 1 : Le modèle appelle web_search("restaurants near me")
# Étape 2 : Le modèle voit les résultats, appelle get_weather(ville des résultats)
# Étape 3 : Le modèle combine les deux en une recommandation

# La boucle d'agent gère cela naturellement — chaque résultat d'outil
# est ajouté à la conversation, et le modèle décide quoi faire ensuite
# en fonction de l'historique complet

Sortie structurée pour une utilisation fiable des outils

Gemma 4 supporte la sortie structurée, ce qui signifie que vous pouvez forcer le modèle à répondre dans un format JSON spécifique. C'est utile quand vous avez besoin de la réponse finale de l'agent dans une structure lisible par machine :

response = requests.post(OLLAMA_URL, json={
    "model": MODEL,
    "messages": messages,
    "format": {
        "type": "object",
        "properties": {
            "answer": {"type": "string"},
            "confidence": {"type": "number"},
            "sources": {
                "type": "array",
                "items": {"type": "string"}
            }
        },
        "required": ["answer", "confidence"]
    },
    "stream": False
})

Cela garantit que la sortie est du JSON valide correspondant à votre schéma — plus de parsing de texte libre en espérant que ça passe.

Conseils pour un meilleur appel de fonctions

Conseil	Pourquoi
Écrivez des descriptions d'outils détaillées	Le modèle se base sur les descriptions pour choisir le bon outil
Utilisez les champs `required` dans les schémas	Empêche le modèle d'omettre des paramètres critiques
Limitez le nombre d'outils à 5-10	Trop d'outils déroute le modèle
Incluez des exemples dans les descriptions	"par exemple, 'New York', 'Londres'" aide le modèle à formater correctement les arguments
Gérez les erreurs avec élégance	Retournez les infos d'erreur pour que le modèle puisse réessayer ou informer l'utilisateur
Définissez une limite max_steps	Empêche les boucles infinies si le modèle continue d'appeler des outils

Pièges courants

Le modèle ignore les outils et répond directement : Faites en sorte que votre system prompt dise explicitement au modèle d'utiliser les outils. Ajoutez « Ne JAMAIS deviner la météo/les maths/les faits — utilisez toujours les outils fournis. »

Mauvais types d'arguments : Si le modèle envoie "3" au lieu de 3 pour un paramètre entier, ajoutez une coercition de type dans vos implémentations d'outils.

Le modèle appelle des outils inutilement : Soyez spécifique dans les descriptions d'outils sur quand les utiliser. « À utiliser UNIQUEMENT quand l'utilisateur demande explicitement la météo » est mieux que « Obtenir des informations météo. »

Prochaines étapes

Envie d'apprendre d'abord les bases de l'API Ollama ? Consultez notre Tutoriel API Gemma 4 pour une introduction en douceur
Besoin de choisir le bon modèle pour les charges de travail d'agent ? Le modèle 12B est le point optimal — voir Quel modèle Gemma 4 ?
Construire des agents multimodaux ? Lisez le Guide multimodal pour ajouter des capacités de vision à votre agent

L'appel de fonctions transforme Gemma 4 d'un chatbot en un véritable outil. Une fois que vous avez connecté de vraies API — météo, recherche, bases de données, email — vous avez un agent IA qui peut prendre des actions significatives dans le monde réel, le tout tournant localement sur votre propre matériel.

gemma4 — interact