Tutorial sobre chamada de função

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

A chamada de função facilita a geração de saídas de dados estruturados de modelos generativos. É possível usar essas saídas para chamar outras APIs e retornar os dados de resposta relevantes ao modelo. Em outras palavras, a chamada de função ajuda a conectar modelos generativos a sistemas externos para que o conteúdo gerado inclua as informações mais atualizadas e precisas.

É possível fornecer descrições de funções aos modelos do Gemini. Essas são funções que você escreve no idioma do seu app, ou seja, elas não são funções do Google Cloud. O modelo pode pedir que você chame uma função e envie de volta o resultado para ajudar o modelo a processar sua consulta.

Se ainda não fez isso, confira a Introdução à chamada de função para saber mais. Você também pode testar esse recurso no Google Colab ou conferir o código de exemplo no repositório Gemini API Cookbook.

Exemplo de API para controle de iluminação

Imagine que você tenha um sistema básico de controle de iluminação com uma interface de programação de aplicativos (API) e queira permitir que os usuários controlem as luzes por meio de solicitações de texto simples. Você pode usar o recurso de chamada de função para interpretar solicitações de mudança de iluminação dos usuários e traduzi-las em chamadas de API para definir os valores de iluminação. Esse sistema hipotético de controle de iluminação permite controlar o brilho da luz e a temperatura da cor, definidos como dois parâmetros separados:

Para simplificar, esse sistema de iluminação imaginário tem apenas uma luz, para que o usuário não precise especificar um cômodo ou local. Confira um exemplo de solicitação JSON que pode ser enviada à API de controle de iluminação para mudar o nível de luz para 50% usando a temperatura de cor do dia:

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

Este tutorial mostra como configurar uma chamada de função para a API Gemini para interpretar as solicitações de iluminação dos usuários e mapeá-las para as configurações da API para controlar os valores de brilho e temperatura de cor de uma luz.

Antes de começar: configure o projeto e a chave de API

Antes de chamar a API Gemini, você precisa configurar seu projeto e a chave de API.

Definir uma função de API

Crie uma função que faça uma solicitação de API. Essa função precisa ser definida no código do seu aplicativo, mas pode chamar serviços ou APIs fora dele. A API Gemini não chama essa função diretamente. Assim, você pode controlar como e quando ela é executada pelo código do aplicativo. Para fins de demonstração, este tutorial define uma função de API simulada que retorna apenas os valores de iluminação solicitados:

def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

Ao criar uma função para ser usada em uma chamada de função pelo modelo, inclua o máximo de detalhes possível nas descrições da função e do parâmetro. O modelo generativo usa essas informações para determinar qual função selecionar e como fornecer valores para os parâmetros na chamada de função.

Declarar funções durante a inicialização do modelo

Quando você quer usar a chamada de função, define as funções como ferramentas no GenerateContentConfig, junto com outras configurações relacionadas à geração (como tokens de temperatura ou de parada).

from google.genai import types

config = types.GenerateContentConfig(tools=[set_light_values])

Isso também pode ser definido como um dicionário Python.

config = {
    'tools': [set_light_values],
}

Gerar uma chamada de função

Depois de definir as declarações de função, você pode solicitar que o modelo use a função. Você pode gerar conteúdo diretamente ou usando a interface de chat.

from google import genai

client = genai.Client()

# Generate directly with generate_content.
response = client.models.generate_content(
    model='gemini-2.0-flash',
    config=config,
    contents='Turn the lights down to a romantic level'
)
print(response.text)

# Use the chat interface.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn the lights down to a romantic level')
print(response.text)

No SDK do Python, as funções são chamadas automaticamente. Se você quiser processar cada chamada de função ou executar outra lógica entre as chamadas, desative a flag na configuração de geração.

from google.genai import types

# Use strong types.
config = types.GenerateContentConfig(
    tools=[set_light_values],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

# Use a dictionary.
config = {
    'tools': [set_light_values],
    'automatic_function_calling': {'disable': True},
}

Chamada de função paralela

Além da chamada de função básica descrita acima, você também pode chamar várias funções em um único turno. Esta seção mostra um exemplo de como usar a chamada de função paralela.

Defina as ferramentas.

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

Agora chame o modelo com uma instrução que possa usar todas as ferramentas especificadas. Este exemplo usa um tool_config. Para saber mais, leia sobre como configurar chamadas de função.

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

config = {
    # Set the available functions.
    'tools': house_fns,
    # Disable AFC so you can inspect the results first.
    'automatic_function_calling': {'disable': True},
    # Force the model to act (call 'any' function), instead of chatting.
    'tool_config': {
        'function_calling_config': {
            'mode': 'any'
        }
    }
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn this place into a party!')

# Print out each of the function calls requested from this single call.
for fn in response.function_calls:
  args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
  print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True)
dim_lights(brightness=0.3)

Cada um dos resultados impressos reflete uma única chamada de função solicitada pelo modelo. Para enviar os resultados de volta, inclua as respostas na mesma ordem em que foram solicitadas.

A maneira mais simples de fazer isso é deixando automatic_function_calling ativado, para que o SDK processe as chamadas de função e a transmissão de resposta automaticamente.

config = {
    'tools': house_fns,
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Do everything you need to this place into party!')

print(response.text)

Disco ball is spinning!
Starting music! energetic=True loud=True
Lights are now set to 50%
Alright, I've turned on the disco ball, started playing "Never gonna give you up.", and dimmed the lights. Let's get this party started!

Mapeamento de tipo de dados de chamada de função

A extração automática de esquemas de funções do Python não funciona em todos os casos. Por exemplo, ele não processa casos em que você descreve os campos de um objeto-dicionário aninhado, mas a API oferece suporte a isso. A API pode descrever qualquer um dos seguintes tipos:

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

Para conferir como é o esquema inferido, converta-o usando from_callable:

from pprint import pprint

def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
pprint(fn_decl.to_json_dict())

{'description': 'Returns a * b.',
 'name': 'multiply',
 'parameters': {'properties': {'a': {'type': 'NUMBER'},
                               'b': {'type': 'NUMBER'}},
                'type': 'OBJECT'}}

Esses campos JSON são mapeados para os campos equivalentes no esquema Pydantic e podem ser agrupados como Tool.

config = types.GenerateContentConfig(
    tools=[types.Tool(function_declarations=[fn_decl])]
)

Esta é uma declaração da mesma função multiply escrita usando as classes genai.types. Essas classes apenas descrevem a função da API, não incluem uma implementação dela. Portanto, essa abordagem não funciona com a chamada automática de funções. No entanto, ele permite definir funções que não são funções concretas do Python (por exemplo, para agrupar uma chamada HTTP remota) e oferece mais controle entre as chamadas de função (por exemplo, para mudar function_calling_config para seguir um gráfico de estado).

tool = types.Tool(function_declarations=[
    types.FunctionDeclaration(
        name="multiply",
        description="Returns a * b.",
        parameters=types.Schema(
            properties={
                'a': types.Schema(type='NUMBER'),
                'b': types.Schema(type='NUMBER'),
            },
            type='OBJECT',
        ),
    )
])
assert tool.function_declarations[0] == fn_decl