Instructivo sobre llamadas a funciones

Python Node.js Go Dart (Flutter) Android Swift Web REST

Las llamadas a funciones te permiten obtener resultados de datos estructurados de los modelos generativos con mayor facilidad. Luego, puedes usar estos resultados para llamar a otras APIs y mostrar los datos de respuesta relevantes al modelo. En otras palabras, las llamadas a función te ayudan a conectar modelos generativos a sistemas externos para que el contenido generado incluya la información más actualizada y precisa.

Puedes proporcionar descripciones de funciones a los modelos de Gemini. Estas son funciones que escribes en el lenguaje de tu app (es decir, no son Google Cloud Functions). Es posible que el modelo te solicite que llames a una función y le envíes el resultado para ayudarlo a controlar tu consulta.

Si aún no lo hiciste, consulta la Introducción a las llamadas a funciones para obtener más información.

Ejemplo de API para el control de iluminación

Imagina que tienes un sistema básico de control de iluminación con una interfaz de programación de aplicaciones (API) y quieres permitir que los usuarios controlen las luces a través de solicitudes de texto simples. Puedes usar la función Llamada a función para interpretar las solicitudes de cambio de iluminación de los usuarios y traducirlas en llamadas a la API para establecer los valores de iluminación. Este sistema hipotético de control de iluminación te permite controlar el brillo de la luz y su temperatura de color, definidos como dos parámetros independientes:

Para simplificar, este sistema de iluminación imaginario solo tiene una luz, por lo que el usuario no tiene que especificar una habitación o una ubicación. Este es un ejemplo de solicitud JSON que podrías enviar a la API de control de iluminación para cambiar el nivel de luz al 50% con la temperatura de color de la luz del día:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

En este instructivo, se muestra cómo configurar una llamada a función para la API de Gemini para interpretar las solicitudes de iluminación de los usuarios y asignarlas a la configuración de la API para controlar los valores de brillo y temperatura de color de una luz.

Antes de comenzar: Configura tu proyecto y clave de API

Antes de llamar a la API de Gemini, debes configurar tu proyecto y tu clave de API.

dart pub add google_generative_ai

flutter pub add google_generative_ai

Define una función de API

Crea una función que realice una solicitud a la API. Esta función se debe definir dentro del código de tu aplicación, pero podría llamar a servicios o APIs fuera de tu aplicación. La API de Gemini no llama a esta función directamente, por lo que puedes controlar cómo y cuándo se ejecuta a través del código de tu aplicación. A modo de demostración, este instructivo define una función de API simulada que solo muestra los valores de iluminación solicitados:

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

Crea declaraciones de funciones

Crea la declaración de función que pasarás al modelo generativo. Cuando declares una función para que la use el modelo, debes incluir tantos detalles como sea posible en las descripciones de la función y los parámetros. El modelo generativo usa esta información para determinar qué función seleccionar y cómo proporcionar valores para los parámetros en la llamada a función. En el siguiente código, se muestra cómo declarar la función de control de iluminación:

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

Cómo declarar funciones durante la inicialización del modelo

Cuando quieras usar llamadas a función con un modelo, debes proporcionar tus declaraciones de función cuando inicialices el objeto del modelo. Para declarar funciones, configura el parámetro tools del modelo. El SDK de Dart también admite declarar las funciones como argumentos para las APIs de generateContent o generateContentStream.

final model = GenerativeModel(
  model: 'gemini-2.0-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [lightControlTool])
  ],
);

Genera una llamada a función

Una vez que hayas inicializado el modelo con tus declaraciones de función, puedes solicitarle el modelo con la función definida. Debes usar las llamadas a función con instrucciones de chat (sendMessage()), ya que, por lo general, se benefician de tener el contexto de las instrucciones y respuestas anteriores.

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}