Utiliser l'appel de fonction

Cette API est proposée en version preview et n'est soumise à aucun contrat de niveau de service ni aucun règlement relatif aux abandons. Des modifications susceptibles d'affecter la rétrocompatibilité peuvent être apportées à cette API. Pour utiliser cette fonctionnalité, le compte Google de l'appareil doit faire partie du programme Preview développeur AICore.

Grâce à l'accès direct au modèle de ML Kit, vous pouvez utiliser l'appel de fonction pour permettre aux modèles Gemini Nano de générer des requêtes d'exécution de fonction structurées (appels d'outils) au lieu de réponses en texte brut. L'appel de fonction vous permet de connecter des modèles d'IA générative sur l'appareil à des outils externes, des API et des fonctionnalités d'application locales.

Attention : L'appel de fonction repose sur les prédictions du modèle d'IA générative, qui ne suggèrent pas toujours la fonction ou les arguments appropriés. Le SDK ML Kit ne valide ni n'exécute lui-même ces fonctions. Vous êtes responsable de la sécurité et de la qualité des résultats générés ou des actions effectuées en fonction des prédictions de la fonction du modèle.

Capacités clés

L'appel de fonction offre les fonctionnalités clés suivantes :

• Appel de fonction à un seul tour : Gemini Nano prédit un ou plusieurs appels d'outils (FunctionCall), votre application exécute les fonctions localement et le flux se termine sans nécessiter de réponse de modèle de suivi.
• Appel de fonction multitour : Gemini Nano prédit un ou plusieurs appels d'outils (FunctionCall), votre application exécute les fonctions localement et renvoie les résultats (FunctionResponsePart) pour récupérer d'autres appels d'outils ou une réponse textuelle synthétisée finale.

Lorsque vous implémentez l'appel de fonction, vous pouvez profiter des avantages suivants :

• Définitions d'outils programmatiques : créez des définitions d'outils FunctionDeclaration et FunctionSchema dynamiques au moment de l'exécution à l'aide de l'API ML Kit GenAI Schema (com.google.mlkit:genai-schema).
• Analyse des arguments structurés : recevez des valeurs d'arguments fortement typées directement à partir de la réponse du modèle candidat pour exécuter la logique de votre application locale.

Remarque : L'accès direct au modèle (genai-prompt) définit les outils de manière programmatique avec FunctionDeclaration et ne distribue ni n'exécute automatiquement les fonctions. Le modèle renvoie les noms de fonction et les arguments prédits dans sa réponse, et votre application contrôle l'exécution de la logique locale de la fonction et renvoie les résultats de l'exécution. Pour définir des outils de manière déclarative avec l'annotation @AppFunction d'Android et laisser ML Kit orchestrer automatiquement l'exécution d'outils multitours dans une boucle d'agent, consultez Workflows agentiques.

Exemples de résultats

L'appel de fonction est compatible avec les flux monotour et multitour. Dans les deux cas, le modèle prédit un ou plusieurs appels d'outils composés du nom de la fonction et des arguments. Pour les flux multitours, après avoir reçu les résultats d'exécution de l'application, celle-ci peut envoyer une autre requête au modèle avec l'historique complet de la conversation pour obtenir d'autres appels d'outils ou une réponse textuelle finale pour l'utilisateur.

Flux d'exécution	Prompt de l'utilisateur	Sortie du modèle
Un seul tour	"Allume les lumières du salon à 80 % de luminosité."	Appel d'outil : turn_on_light(room="living room", brightness=80)
Un seul tour	"Ouvre l'application Appareil photo."	Appel d'outil : open_app(appName="Camera")
Multitours	"Quel temps fait-il à San Francisco en degrés Celsius ?"	Appel d'outil intermédiaire : get_current_weather(location="San Francisco, CA", unit="celsius") Sortie du modèle final présentée à l'utilisateur : In SF it's currently 25 degrees Celsius.

Prérequis

Pour utiliser l'appel de fonction, vous devez remplir les conditions suivantes concernant l'appareil et le compte :

• Votre appareil est compatible avec l'API Prompt.
• Le compte Google de votre appareil fait partie du programme Preview développeur AICore.

Pour vérifier que vous remplissez ces conditions, vérifiez que le modèle Gemini Nano 4 Fast est disponible dans l'application AICore : ouvrez l'application AICore, cliquez sur le menu déroulant Sélectionner un modèle, puis vérifiez que Gemini Nano 4 Fast est listé. Si le modèle n'y figure pas, cela signifie qu'il y a un problème de compatibilité de l'appareil ou d'enregistrement du compte, et que l'appel de fonction ne fonctionnera pas.

Conseil : Téléchargez le modèle Gemini Nano 4 sur votre appareil pour gagner du temps lors de votre première inférence.

De plus, votre projet doit répondre aux exigences suivantes :

• Kotlin version 2.3.0 ou ultérieure
• SDK minimum (minSdk) version 26 ou ultérieure

Commencer

Voici la procédure à suivre pour commencer à utiliser l'appel de fonction.

1. Dans le fichier settings.gradle.kts (ou settings.gradle) au niveau du projet, ajoutez mavenCentral() au bloc repositories {}.

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   }
   

2. Dans votre fichier build.gradle.kts (ou build.gradle) au niveau du module, ajoutez les dépendances de l'API Prompt et du schéma de ML Kit :

   Kotlin

   plugins {
       id("com.android.application")
       id("org.jetbrains.kotlin.android")
   }
   
   dependencies {
       // ML Kit GenAI Prompt and Schema SDKs
       implementation("com.google.mlkit:genai-prompt:1.0.0-beta5")
       implementation("com.google.mlkit:genai-schema:1.0.0-alpha2")
   }
   

   Groovy

   plugins {
       id 'com.android.application'
       id 'org.jetbrains.kotlin.android'
   }
   
   dependencies {
       // ML Kit GenAI Prompt and Schema SDKs
       implementation 'com.google.mlkit:genai-prompt:1.0.0-beta5'
       implementation 'com.google.mlkit:genai-schema:1.0.0-alpha2'
   }
   

3. Dans le fichier build.gradle (ou build.gradle.kts) au niveau du module, définissez la version de minSdk sur 26 ou une version ultérieure.

   Kotlin

   android {
       defaultConfig {
           // ...
           minSdk = 26
           // ...
       }
   }
   

   Groovy

   android {
       defaultConfig {
           // ...
           minSdk 26
           // ...
       }
   }
   

Utiliser l'API d'appel de fonction

Pour implémenter l'appel de fonction, procédez comme suit :

1. Définissez vos outils.
2. Sélectionnez le modèle.
3. Associez des outils à votre requête.
4. Gérer les appels d'outils (à un seul tour ou multitours)

Les sections suivantes présentent un exemple qui illustre ces étapes.

Définir vos outils

Créez des schémas d'outils de manière programmatique à l'aide de FunctionDeclaration, FunctionSchema et FunctionType du package com.google.mlkit.genai.schema.tools. (Pour définir des outils de manière déclarative au moment de la compilation à l'aide de l'annotation @AppFunction d'Android avec exécution automatique, consultez Définir des outils.)

Par exemple, vous pouvez définir un outil orienté action (comme l'allumage d'une ampoule connectée pour une exécution en un seul tour) :

import com.google.mlkit.genai.schema.tools.FunctionDeclaration
import com.google.mlkit.genai.schema.tools.FunctionSchema
import com.google.mlkit.genai.schema.tools.FunctionType

val turnOnLightTool = FunctionDeclaration(
    name = "turn_on_light",
    description = "Turn on the lights in a room and set the brightness",
    parameters = FunctionSchema(
        type = FunctionType.OBJECT,
        properties = mapOf(
            "room" to FunctionSchema(
                type = FunctionType.STRING,
                description = "The room name"
            ),
            "brightness" to FunctionSchema(
                type = FunctionType.INTEGER,
                description = "Brightness level from 0 to 100"
            )
        ),
        required = listOf("room")
    )
)

Vous pouvez également définir un outil de récupération de données (par exemple, pour récupérer la météo actuelle pour une synthèse multitour) :

import com.google.mlkit.genai.schema.tools.FunctionDeclaration
import com.google.mlkit.genai.schema.tools.FunctionSchema
import com.google.mlkit.genai.schema.tools.FunctionType

val getWeatherTool = FunctionDeclaration(
    name = "get_current_weather",
    description = "Get the current weather for a location",
    parameters = FunctionSchema(
        type = FunctionType.OBJECT,
        properties = mapOf(
            "location" to FunctionSchema(
                type = FunctionType.STRING,
                description = "The city and state, e.g. San Francisco, CA"
            ),
            "unit" to FunctionSchema(
                type = FunctionType.STRING,
                description = "The temperature unit, either 'celsius' or 'fahrenheit'"
            )
        ),
        required = listOf("location")
    )
)

Sélectionnez le modèle

L'appel de fonction nécessite Gemini Nano 4. Pour accéder à Gemini Nano 4, utilisez l'API de sélection de modèle afin de configurer votre instance GenerativeModel pour cibler ModelReleaseStage.PREVIEW ET ModelPreference.FAST.

Remarque : Sur les Samsung Galaxy Z Flip 8 et Fold 8, Gemini Nano 4 est déjà disponible en production. Si vous utilisez ces appareils, vous n'avez pas besoin de spécifier le modèle rapide en version preview. L'appel du client Generation.getClient() par défaut fonctionne.

import com.google.mlkit.genai.prompt.Generation
import com.google.mlkit.genai.prompt.ModelPreference
import com.google.mlkit.genai.prompt.ModelReleaseStage
import com.google.mlkit.genai.prompt.generationConfig
import com.google.mlkit.genai.prompt.modelConfig

// Target the preview fast model (Gemini Nano 4)
val config = generationConfig {
    modelConfig = modelConfig {
        releaseStage = ModelReleaseStage.PREVIEW
        preference = ModelPreference.FAST
    }
}
val generativeModel = Generation.getClient(config)

Associer des outils à votre requête

Lorsque vous créez un objet GenerateContentRequest, transmettez votre liste FunctionDeclaration à setTools() dans le générateur de requêtes.

Par exemple, pour associer un outil à une requête d'action à un seul tour avec une instruction système :

import com.google.mlkit.genai.prompt.SystemInstruction
import com.google.mlkit.genai.prompt.TextPart
import com.google.mlkit.genai.prompt.generateContentRequest

val requestText = "Turn on the living room lights and set brightness to 50"

val request = generateContentRequest(
    SystemInstruction("You are a helpful home automation assistant."),
    TextPart(requestText)
) {
    // Attach the FunctionDeclaration tool schemas
    setTools(listOf(turnOnLightTool))
    temperature = 0.2f
}

// Run non-streaming inference
val response = generativeModel.generateContent(request)

Ou pour joindre votre liste FunctionDeclaration pour une requête multitour :

import com.google.mlkit.genai.prompt.SystemInstruction
import com.google.mlkit.genai.prompt.TextPart
import com.google.mlkit.genai.prompt.generateContentRequest

val availableTools = listOf(getWeatherTool)

// Use the generateContentRequest DSL
val request = generateContentRequest(
    TextPart("What is the weather in San Francisco, CA in celsius?")
) {
    setTools(availableTools)
}
val response = generativeModel.generateContent(request)

Gérer les appels d'outils

Lorsque Gemini Nano décide d'appeler un outil, la réponse candidate du modèle contient un ou plusieurs objets FunctionCall dans candidate.functionCalls. Pour gérer les appels d'outils, votre application doit d'abord inspecter la réponse candidate pour vérifier si des appels d'outils ont été prédits :

import com.google.mlkit.genai.common.FunctionArgValue
import com.google.mlkit.genai.prompt.Content
import com.google.mlkit.genai.prompt.FunctionCallPart
import com.google.mlkit.genai.prompt.FunctionResponsePart
import com.google.mlkit.genai.prompt.GenerateContentRequest
import com.google.mlkit.genai.prompt.TextPart
import com.google.mlkit.genai.prompt.content

val candidate = response.candidates.firstOrNull()
val functionCalls = candidate?.functionCalls ?: emptyList()

if (functionCalls.isNotEmpty()) {
    // Process tool calls using either the single-turn or multi-turn flow
    // described in the following sections
}

Appel de fonction à un seul tour

Utilisez l'appel de fonction à un seul tour pour les tâches orientées action où l'application répond directement à la requête (par exemple, "Ouvre l'application Appareil photo" ou "Allume les lumières du salon"). Une fois que votre application a exécuté la fonction localement, le flux est terminé. Aucune réponse de suivi du modèle n'est requise.

for (functionCall in functionCalls) {
    val name = functionCall.name
    val args = functionCall.arguments // Map<String, FunctionArgValue>

    when (name) {
        "open_app" -> {
            val appName = (args["appName"] as? FunctionArgValue.StringValue)?.value
            launchApp(appName)
        }
        "turn_on_light" -> {
            val room = (args["room"] as? FunctionArgValue.StringValue)?.value
            val brightness = (args["brightness"] as? FunctionArgValue.IntValue)?.value ?: 100
            setLightState(room, brightness)
        }
        else -> Log.w(TAG, "Unhandled tool call: $name")
    }
}

Appel de fonction multitour

Utilisez l'appel de fonction multitour lorsque l'utilisateur attend une réponse en langage naturel basée sur les données récupérées par l'outil (par exemple, "Quel temps fait-il à San Francisco ?").

Dans un flux multitour, votre application effectue les opérations suivantes :

1. Exécute la fonction demandée localement.
2. Empaqueter le résultat dans un objet FunctionResponsePart.
3. Ajoute l'appel du modèle (rôle MODEL) et le résultat de l'exécution (rôle USER) à l'historique de la conversation.
4. Envoie une requête de suivi à Gemini Nano pour synthétiser la réponse finale en langage naturel.

// 1. Execute each predicted tool call and collect results
val responseParts = mutableListOf<FunctionResponsePart>()

for (functionCall in functionCalls) {
    val responsePart: FunctionResponsePart = when {
        functionCall.name == "get_current_weather" -> {
            val location = (functionCall.arguments["location"] as? FunctionArgValue.StringValue)?.value ?: ""
            val unit = (functionCall.arguments["unit"] as? FunctionArgValue.StringValue)?.value ?: "celsius"

            val weatherData = fetchWeather(location, unit) // Local network/API call

            // Package the tool execution result as a key-value map
            FunctionResponsePart(
                id = functionCall.id,
                name = functionCall.name,
                response = mapOf("result" to weatherData)
            )
        }

        else -> throw IllegalArgumentException("Unknown tool: ${functionCall.name}")
    }
    responseParts.add(responsePart)
}

// 2. Append turns to conversation history to construct the multi-turn context
val history = request.contents.toMutableList().apply {
    // Turn 1: Model's request containing the predicted FunctionCallPart object
    add(
        content(Content.Role.MODEL) {
            for (call in functionCalls) {
                addPart(FunctionCallPart(call))
            }
        }
    )
    // Turn 2: User's response containing the executed FunctionResponsePart object
    add(
        content(Content.Role.USER) {
            for (responsePart in responseParts) {
                addPart(responsePart)
            }
        }
    )
}

// 3. Send the updated history back to Gemini Nano for final text synthesis
val followUpRequest = GenerateContentRequest.Builder(history)
    .setTools(availableTools) // Include tools in case the model requires subsequent tool calls
    .build()

val finalResponse = generativeModel.generateContent(followUpRequest)
val answer = finalResponse.candidates.firstOrNull()?.text

Log.d(TAG, "Final Model Response: $answer")

Exemple de code

Pour obtenir un exemple complet d'appel de fonction dans une application Android, consultez cet exemple d'application ML Kit.

Problèmes connus

• AndroidX AppFunctions (@AppFunction) dans l'accès direct au modèle (genai-prompt) : la découverte et l'exécution d'outils @AppFunction au moment de la compilation directement via l'API Prompt (com.google.mlkit:genai-prompt:1.0.0-beta5) ne sont pas encore disponibles. Les outils de la bibliothèque genai-prompt doivent être définis de manière programmatique à l'aide de la classe FunctionDeclaration. Pour utiliser les outils @AppFunction dès aujourd'hui, utilisez des workflows agentiques (com.google.mlkit:genai-agent).
• Lorsque vous utilisez des requêtes de streaming (generateContentStream), les appels d'outils ne sont pas diffusés jeton par jeton. À la place, des objets FunctionCall complets sont émis (via StreamingCallback.onNewFunctionCall ou dans le GenerateContentResponse.candidates[0].functionCalls final diffusé en streaming) une fois que le modèle a fini de générer l'appel d'outil.