Usar a chamada de função

Com o acesso direto ao modelo do Kit de ML, é possível usar a chamada de função para permitir que os modelos do Gemini Nano gerem solicitações de execução de função estruturadas (chamadas de ferramenta) em vez de respostas de texto simples. A chamada de função permite conectar modelos de IA generativa no dispositivo a ferramentas externas, APIs e recursos de apps locais.

Principais recursos

A chamada de função oferece os seguintes recursos principais:

• Chamada de função de turno único: o Gemini Nano prevê uma ou mais chamadas de ferramenta (FunctionCall), seu app executa as funções localmente e o fluxo é concluído sem precisar de uma resposta de modelo de acompanhamento.
• Chamada de função multiturno: o Gemini Nano prevê uma ou mais chamadas de ferramenta (FunctionCall), seu app executa as funções localmente e transmite os resultados de volta (FunctionResponsePart) para recuperar mais chamadas de ferramenta ou uma resposta de texto sintetizada final.

Ao implementar a chamada de função, você pode aproveitar o seguinte:

• Definições de ferramentas programáticas: crie definições de ferramentas FunctionDeclaration e FunctionSchema dinâmicas no ambiente de execução usando a API GenAI Schema do Kit de ML (com.google.mlkit:genai-schema).
• Análise de argumentos estruturados: receba valores de argumentos fortemente tipados diretamente da resposta do modelo candidato para executar a lógica do app local.

Resultados de exemplo

A chamada de função é compatível com fluxos de turno único e multiturno. Em ambos os casos, o modelo prevê uma ou mais chamadas de ferramenta que consistem no nome da função e nos argumentos. Para fluxos de várias interações, depois de receber os resultados da execução do app, ele pode enviar outra solicitação ao modelo com o histórico completo da conversa para receber mais chamadas de ferramentas ou uma resposta de texto final para o usuário.

Pré-requisitos

Para usar a chamada de função, você precisa atender aos seguintes requisitos de dispositivo e conta:

• Seu dispositivo é compatível com a API Prompt.
• A Conta do Google no seu dispositivo faz parte do programa de prévia para desenvolvedores do AICore.

Para verificar se você atende a esses requisitos, confira se o modelo Gemini Nano 4 Fast está disponível no app AICore: abra o app AICore, clique no menu suspenso Selecionar um modelo e verifique se o Gemini Nano 4 Fast está listado. Se o modelo não estiver lá, há um problema com o suporte do dispositivo ou com o registro da conta, e a chamada de função não vai funcionar.

Além disso, o projeto precisa atender aos seguintes requisitos:

• Kotlin versão 2.3.0 ou mais recente
• SDK mínimo (minSdk) versão 26 ou mais recente

Primeiros passos

Confira as etapas para começar a usar a chamada de função.

1. No arquivo settings.gradle.kts (ou settings.gradle) do projeto, adicione mavenCentral() ao bloco repositories {}.

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

2. No arquivo build.gradle.kts (ou build.gradle) do módulo, adicione as dependências da API Prompt do Kit de ML e do esquema:

   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. No arquivo build.gradle (ou build.gradle.kts) no nível do módulo, defina a versão de minSdk como 26 ou mais recente.

   Kotlin

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

   Groovy

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

Como usar a API de chamada de função

Para implementar a chamada de função, siga estas etapas:

1. Defina as ferramentas.
2. Selecione o modelo.
3. Anexe ferramentas à sua solicitação.
4. Processar chamadas de ferramentas (turno único ou vários turnos).

As próximas seções mostram um exemplo que demonstra essas etapas.

Definir as ferramentas

Crie esquemas de ferramentas de forma programática usando FunctionDeclaration, FunctionSchema e FunctionType do pacote com.google.mlkit.genai.schema.tools. Para definir ferramentas de forma declarativa no tempo de compilação usando a anotação @AppFunction do Android com execução automática, consulte Definir ferramentas.

Por exemplo, é possível definir uma ferramenta orientada a ações (como acender uma luz inteligente para execução de turno único):

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")
    )
)

Ou defina uma ferramenta de recuperação de dados (como buscar o clima atual para síntese de vários turnos):

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")
    )
)

Selecione o modelo

A chamada de função requer o Gemini Nano 4. Para acessar o Gemini Nano 4, use a API de seleção de modelo para configurar sua instância GenerativeModel para segmentar ModelReleaseStage.PREVIEW E ModelPreference.FAST.

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)

Anexar ferramentas à sua solicitação

Ao criar um objeto GenerateContentRequest, transmita sua lista FunctionDeclaration para setTools() no builder de solicitações.

Por exemplo, para anexar uma ferramenta para uma solicitação de ação de turno único com uma instrução do sistema:

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 para anexar sua lista de FunctionDeclaration para uma consulta de vários turnos:

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)

Processar chamadas de ferramentas

Quando o Gemini Nano decide invocar uma ferramenta, a resposta candidata do modelo contém um ou mais objetos FunctionCall em candidate.functionCalls. Para processar chamadas de ferramentas, o app precisa primeiro inspecionar o candidato de resposta para verificar se alguma chamada de ferramenta foi prevista:

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
}

Chamada de função de turno único

Use a chamada de função de turno único para tarefas orientadas a ações em que o app atende diretamente à solicitação (por exemplo, "Abrir o app da câmera" ou "Acender as luzes da sala de estar"). Depois que o app executa a função localmente, o fluxo é concluído. Não é necessária uma resposta de acompanhamento do modelo.

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")
    }
}

Chamada de função multiturno

Use a chamada de função multiturno quando o usuário espera uma resposta em linguagem natural com base nos dados recuperados pela ferramenta (por exemplo, "Como está o clima em São Francisco?").

Em um fluxo de várias interações, o app faz o seguinte:

1. Executa a função solicitada localmente.
2. Empacota o resultado em um objeto FunctionResponsePart.
3. Anexa a chamada do modelo (papel MODEL) e o resultado da execução (papel USER) ao histórico de conversas.
4. Envia uma solicitação de acompanhamento de volta ao Gemini Nano para sintetizar a resposta final em linguagem natural.

// 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")

Exemplo de código

Para um exemplo completo de chamada de função em um app Android, consulte este app de exemplo do Kit de ML.

Problemas conhecidos

• AppFunctions do AndroidX (@AppFunction) no acesso direto ao modelo (genai-prompt): ainda não é possível descobrir e executar ferramentas @AppFunction em tempo de compilação diretamente pela API Prompt (com.google.mlkit:genai-prompt:1.0.0-beta5). As ferramentas na biblioteca genai-prompt precisam ser definidas de forma programática usando a classe FunctionDeclaration. Para usar as ferramentas do @AppFunction hoje, use Agentic Workflows (com.google.mlkit:genai-agent).
• Ao usar solicitações de streaming (generateContentStream), as chamadas de ferramenta não são transmitidas token por token. Em vez disso, objetos FunctionCall completos são emitidos (via StreamingCallback.onNewFunctionCall ou no GenerateContentResponse.candidates[0].functionCalls transmitido final) quando o modelo termina de gerar a chamada de ferramenta.