A chamada de função permite conectar modelos a ferramentas e APIs externas. Em vez de gerar respostas de texto, o modelo entende quando chamar funções e fornece os parâmetros necessários para executar ações reais. Isso permite que o modelo funcione como uma ponte entre a linguagem natural e as ações e dados do mundo real. As chamadas de função têm três casos de uso principais:
- Aumentar o conhecimento:acesse informações de fontes externas, como bancos de dados, APIs e bases de conhecimento.
- Ampliar os recursos:use ferramentas externas para realizar cálculos e ampliar as limitações do modelo, como usar uma calculadora ou criar gráficos.
- Realizar ações:interagir com sistemas externos usando APIs, como agendar compromissos, criar faturas, enviar e-mails ou controlar dispositivos de casa inteligente.
Como a chamada de função funciona
A chamada de função envolve uma interação estruturada entre o aplicativo, o modelo e as funções externas. Confira os detalhes do processo:
- Definir a declaração de função:defina a declaração de função no código do aplicativo. As declarações de função descrevem o nome, os parâmetros e a finalidade da função para o modelo.
- Chamar o LLM com declarações de função:envie o comando do usuário com as declarações de função para o modelo. Ele analisa a solicitação e determina se uma chamada de função seria útil. Nesse caso, ele responde com um objeto JSON estruturado.
- Executar o código da função (sua responsabilidade): o modelo não executa a função. É responsabilidade do seu aplicativo
processar a resposta e verificar a chamada de função, se
- Sim: extraia o nome e os argumentos da função e execute a função correspondente no seu aplicativo.
- Não:o modelo forneceu uma resposta de texto direta ao comando. Esse fluxo é menos enfatizado no exemplo, mas é um resultado possível.
- Criar uma resposta amigável ao usuário:se uma função foi executada, capture o resultado e o envie de volta ao modelo em uma próxima vez na conversa. Ele vai usar o resultado para gerar uma resposta final fácil de usar que incorpora as informações da chamada de função.
Esse processo pode ser repetido em várias rodadas, permitindo interações e fluxos de trabalho complexos. O modelo também oferece suporte à chamada de várias funções em uma única vez (chamada de função paralela) e em sequência (chamada de função composta).
Etapa 1: definir a declaração de função
Defina uma função e a declaração dela no código do aplicativo para permitir que os usuários definam valores de luz e façam uma solicitação de API. Essa função pode chamar serviços ou APIs externos.
from google.genai import types
# Define a function that the model can call to control smart lights
set_light_values_declaration = {
"name": "set_light_values",
"description": "Sets the brightness and color temperature of a light.",
"parameters": {
"type": "object",
"properties": {
"brightness": {
"type": "integer",
"description": "Light level from 0 to 100. Zero is off and 100 is full brightness",
},
"color_temp": {
"type": "string",
"enum": ["daylight", "cool", "warm"],
"description": "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
},
},
"required": ["brightness", "color_temp"],
},
}
# This is the actual function that would be called based on the model's suggestion
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}
import { Type } from '@google/genai';
// Define a function that the model can call to control smart lights
const setLightValuesFunctionDeclaration = {
name: 'set_light_values',
description: 'Sets the brightness and color temperature of a light.',
parameters: {
type: Type.OBJECT,
properties: {
brightness: {
type: Type.NUMBER,
description: 'Light level from 0 to 100. Zero is off and 100 is full brightness',
},
color_temp: {
type: Type.STRING,
enum: ['daylight', 'cool', 'warm'],
description: 'Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.',
},
},
required: ['brightness', 'color_temp'],
},
};
/**
* Set the brightness and color temperature of a room light. (mock API)
* @param {number} brightness - Light level from 0 to 100. Zero is off and 100 is full brightness
* @param {string} color_temp - Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
* @return {Object} A dictionary containing the set brightness and color temperature.
*/
function setLightValues(brightness, color_temp) {
return {
brightness: brightness,
colorTemperature: color_temp
};
}
Etapa 2: chamar o modelo com declarações de função
Depois de definir as declarações de função, você pode solicitar que o modelo use a função. Ele analisa as declarações de comando e função e decide responder diretamente ou chamar uma função. Se uma função for chamada, o objeto de resposta vai conter uma sugestão de chamada de função.
from google import genai
# Generation Config with Function Declaration
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])
# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
# Define user prompt
contents = [
types.Content(
role="user", parts=[types.Part(text="Turn the lights down to a romantic level")]
)
]
# Send request with function declarations
response = client.models.generate_content(
model="gemini-2.0-flash", config=config, contents=contents
)
print(response.candidates[0].content.parts[0].function_call)
import { GoogleGenAI } from '@google/genai';
// Generation Config with Function Declaration
const config = {
tools: [{
functionDeclarations: [setLightValuesFunctionDeclaration]
}]
};
// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Define user prompt
const contents = [
{
role: 'user',
parts: [{ text: 'Turn the lights down to a romantic level' }]
}
];
// Send request with function declarations
const response = await ai.models.generateContent({
model: 'gemini-2.0-flash',
contents: contents,
config: config
});
console.log(response.functionCalls[0]);
O modelo retorna um objeto functionCall em um esquema compatível com a OpenAPI, especificando como chamar uma ou mais das funções declaradas para responder à pergunta do usuário.
id=None args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'
{
name: 'set_light_values',
args: { brightness: 25, color_temp: 'warm' }
}
Etapa 3: executar o código da função set_light_values
Extraia os detalhes da chamada de função da resposta do modelo, analise os argumentos
e execute a função set_light_values no código.
# Extract tool call details
tool_call = response.candidates[0].content.parts[0].function_call
if tool_call.name == "set_light_values":
result = set_light_values(**tool_call.args)
print(f"Function execution result: {result}")
// Extract tool call details
const tool_call = response.functionCalls[0]
let result;
if (tool_call.name === 'set_light_values') {
result = setLightValues(tool_call.args.brightness, tool_call.args.color_temp);
console.log(`Function execution result: ${JSON.stringify(result)}`);
}
Etapa 4: criar uma resposta amigável ao usuário com o resultado da função e chamar o modelo novamente
Por fim, envie o resultado da execução da função de volta ao modelo para que ele possa incorporar essas informações na resposta final ao usuário.
# Create a function response part
function_response_part = types.Part.from_function_response(
name=tool_call.name,
response={"result": result},
)
# Append function call and result of the function execution to contents
contents.append(types.Content(role="model", parts=[types.Part(function_call=tool_call)])) # Append the model's function call message
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response
final_response = client.models.generate_content(
model="gemini-2.0-flash",
config=config,
contents=contents,
)
print(final_response.text)
// Create a function response part
const function_response_part = {
name: tool_call.name,
response: { result }
}
// Append function call and result of the function execution to contents
contents.push({ role: 'model', parts: [{ functionCall: tool_call }] });
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });
// Get the final response from the model
const final_response = await ai.models.generateContent({
model: 'gemini-2.0-flash',
contents: contents,
config: config
});
console.log(final_response.text);
Isso conclui o fluxo de chamada de função. O modelo usou a função set_light_values para realizar a ação de solicitação do usuário.
Declarações de função
Ao implementar a chamada de função em um comando, você cria um objeto tools, que contém um ou mais function declarations. Você define funções usando JSON, especificamente com um subconjunto selecionado do formato de esquema da OpenAPI. Uma única declaração de função pode incluir os seguintes parâmetros:
name(string): um nome exclusivo para a função (get_weather_forecast,send_email). Use nomes descritivos sem espaços ou caracteres especiais (use sublinhados ou letras em caixa alta e baixa).description(string): uma explicação clara e detalhada do propósito e dos recursos da função. Isso é crucial para que o modelo entenda quando usar a função. Seja específico e dê exemplos se for útil ("Encontra cinemas com base na localização e, opcionalmente, no título do filme que está em cartaz").parameters(objeto): define os parâmetros de entrada esperados pela função.type(string): especifica o tipo de dados geral, comoobject.properties(objeto): lista parâmetros individuais, cada um com:type(string): o tipo de dados do parâmetro, comostring,integer,boolean, array.description(string): uma descrição da finalidade e do formato do parâmetro. Dê exemplos e restrições ("A cidade e o estado, por exemplo, "São Paulo, SP" ou um CEP, por exemplo, '95616'.").enum(matriz, opcional): se os valores do parâmetro forem de um conjunto fixo, use "enum" para listar os valores permitidos em vez de apenas descrevê-los na descrição. Isso melhora a precisão ("enum": ["daylight", "cool", "warm"]).
required(matriz): uma matriz de strings que lista os nomes dos parâmetros obrigatórios para a função funcionar.
Chamada de função paralela
Além de chamar uma função por vez, você também pode chamar várias de uma só vez. A chamada de função paralela permite executar várias funções de uma vez e é usada quando as funções não dependem uma da outra. Isso é útil em cenários como a coleta de dados de várias fontes independentes, como a recuperação de detalhes do cliente de diferentes bancos de dados ou a verificação de níveis de inventário em vários armazéns ou a realização de várias ações, como a conversão de um apartamento em um disco.
power_disco_ball = {
"name": "power_disco_ball",
"description": "Powers the spinning disco ball.",
"parameters": {
"type": "object",
"properties": {
"power": {
"type": "boolean",
"description": "Whether to turn the disco ball on or off.",
}
},
"required": ["power"],
},
}
start_music = {
"name": "start_music",
"description": "Play some music matching the specified parameters.",
"parameters": {
"type": "object",
"properties": {
"energetic": {
"type": "boolean",
"description": "Whether the music is energetic or not.",
},
"loud": {
"type": "boolean",
"description": "Whether the music is loud or not.",
},
},
"required": ["energetic", "loud"],
},
}
dim_lights = {
"name": "dim_lights",
"description": "Dim the lights.",
"parameters": {
"type": "object",
"properties": {
"brightness": {
"type": "number",
"description": "The brightness of the lights, 0.0 is off, 1.0 is full.",
}
},
"required": ["brightness"],
},
}
import { Type } from '@google/genai';
const powerDiscoBall = {
name: 'power_disco_ball',
description: 'Powers the spinning disco ball.',
parameters: {
type: Type.OBJECT,
properties: {
power: {
type: Type.BOOLEAN,
description: 'Whether to turn the disco ball on or off.'
}
},
required: ['power']
}
};
const startMusic = {
name: 'start_music',
description: 'Play some music matching the specified parameters.',
parameters: {
type: Type.OBJECT,
properties: {
energetic: {
type: Type.BOOLEAN,
description: 'Whether the music is energetic or not.'
},
loud: {
type: Type.BOOLEAN,
description: 'Whether the music is loud or not.'
}
},
required: ['energetic', 'loud']
}
};
const dimLights = {
name: 'dim_lights',
description: 'Dim the lights.',
parameters: {
type: Type.OBJECT,
properties: {
brightness: {
type: Type.NUMBER,
description: 'The brightness of the lights, 0.0 is off, 1.0 is full.'
}
},
required: ['brightness']
}
};
Chame o modelo com uma instrução que possa usar todas as ferramentas especificadas. Este exemplo usa uma tool_config. Para saber mais, leia sobre como configurar a chamada de função.
from google import genai
from google.genai import types
# Set up function declarations
house_tools = [
types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]
config = {
"tools": house_tools,
"automatic_function_calling": {"disable": True},
# Force the model to call 'any' function, instead of chatting.
"tool_config": {"function_calling_config": {"mode": "any"}},
}
# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
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
print("Example 1: Forced function calling")
for fn in response.function_calls:
args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
print(f"{fn.name}({args})")
import { GoogleGenAI } from '@google/genai';
// Set up function declarations
const houseFns = [powerDiscoBall, startMusic, dimLights];
const config = {
tools: [{
functionDeclarations: houseFns
}],
// Force the model to call 'any' function, instead of chatting.
toolConfig: {
functionCallingConfig: {
mode: 'any'
}
}
};
// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Create a chat session
const chat = ai.chats.create({
model: 'gemini-2.0-flash',
config: config
});
const response = await chat.sendMessage({message: 'Turn this place into a party!'});
// Print out each of the function calls requested from this single call
console.log("Example 1: Forced function calling");
for (const fn of response.functionCalls) {
const args = Object.entries(fn.args)
.map(([key, val]) => `${key}=${val}`)
.join(', ');
console.log(`${fn.name}(${args})`);
}
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.
O SDK do Python oferece suporte a um recurso chamado chamada de função automática, que converte a função Python em declarações, processa a execução da chamada de função e o ciclo de resposta para você. Confira abaixo um exemplo do nosso caso de uso do disco.
from google import genai
from google.genai import types
# Actual implementation functions
def power_disco_ball_impl(power: bool) -> dict:
"""Powers the spinning disco ball.
Args:
power: Whether to turn the disco ball on or off.
Returns:
A status dictionary indicating the current state.
"""
return {"status": f"Disco ball powered {'on' if power else 'off'}"}
def start_music_impl(energetic: bool, loud: bool) -> dict:
"""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:
A dictionary containing the music settings.
"""
music_type = "energetic" if energetic else "chill"
volume = "loud" if loud else "quiet"
return {"music_type": music_type, "volume": volume}
def dim_lights_impl(brightness: float) -> dict:
"""Dim the lights.
Args:
brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
Returns:
A dictionary containing the new brightness setting.
"""
return {"brightness": brightness}
config = {
"tools": [power_disco_ball_impl, start_music_impl, dim_lights_impl],
}
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("\nExample 2: Automatic function calling")
print(response.text)
# I've turned on the disco ball, started playing loud and energetic music, and dimmed the lights to 50% brightness. Let's get this party started!
Chamada de função com composição
O Gemini 2.0 oferece suporte à chamada de função com composição, o que significa que o modelo pode encadear várias chamadas de função. Por exemplo, para responder "Pegar a temperatura no meu local atual", a API Gemini pode invocar uma função get_current_location() e uma função get_weather() que use o local como parâmetro.
# Light control schemas
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}
prompt = """
Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
"""
tools = [
{'code_execution': {}},
{'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]
await run(prompt, tools=tools, modality="AUDIO")
// Light control schemas
const turnOnTheLightsSchema = { name: 'turn_on_the_lights' };
const turnOffTheLightsSchema = { name: 'turn_off_the_lights' };
const prompt = `
Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
`;
const tools = [
{ codeExecution: {} },
{ functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] }
];
await run(prompt, tools=tools, modality="AUDIO")
Modos de chamada de função
A API Gemini permite controlar como o modelo usa as ferramentas fornecidas (declarações de função). Mais especificamente, é possível definir o modo no function_calling_config.
AUTO (Default): o modelo decide se vai gerar uma resposta de linguagem natural ou sugerir uma chamada de função com base no comando e no contexto. Esse é o modo mais flexível e recomendado para a maioria dos casos.ANY: o modelo é restrito a sempre prever uma chamada de função e garantir a adesão ao esquema de função. Seallowed_function_namesnão for especificado, o modelo poderá escolher entre qualquer uma das declarações de função fornecidas. Seallowed_function_namesfor fornecido como uma lista, o modelo só poderá escolher entre as funções dessa lista. Use esse modo quando precisar de uma chamada de função em resposta a cada comando (se aplicável).NONE: o modelo não pode fazer chamadas de função. Isso equivale a enviar uma solicitação sem declarações de função. Use essa opção para desativar temporariamente a chamada de função sem remover as definições de ferramentas.
from google.genai import types
# Configure function calling mode
tool_config = types.ToolConfig(
function_calling_config=types.FunctionCallingConfig(
mode="ANY", allowed_function_names=["get_current_temperature"]
)
)
# Create the generation config
config = types.GenerateContentConfig(
temperature=0,
tools=[tools], # not defined here.
tool_config=tool_config,
)
import { FunctionCallingConfigMode } from '@google/genai';
// Configure function calling mode
const toolConfig = {
functionCallingConfig: {
mode: FunctionCallingConfigMode.ANY,
allowedFunctionNames: ['get_current_temperature']
}
};
// Create the generation config
const config = {
temperature: 0,
tools: tools, // not defined here.
toolConfig: toolConfig,
};
Chamada de função automática (somente Python)
Ao usar o SDK do Python, você pode fornecer funções do Python diretamente como ferramentas. O SDK converte automaticamente a função Python em declarações e processa a execução da chamada de função e o ciclo de resposta para você. O SDK do Python vai:
- Detecta respostas de chamadas de função do modelo.
- Chame a função Python correspondente no código.
- Envia a resposta da função de volta ao modelo.
- Retorna a resposta de texto final do modelo.
Para usar isso, defina sua função com dicas de tipo e um docstring e transmita a própria função (não uma declaração JSON) como uma ferramenta:
from google import genai
from google.genai import types
# Define the function with type hints and docstring
def get_current_temperature(location: str) -> dict:
"""Gets the current temperature for a given location.
Args:
location: The city and state, e.g. San Francisco, CA
Returns:
A dictionary containing the temperature and unit.
"""
# ... (implementation) ...
return {"temperature": 25, "unit": "Celsius"}
# Configure the client and model
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY")) # Replace with your actual API key setup
config = types.GenerateContentConfig(
tools=[get_current_temperature]
) # Pass the function itself
# Make the request
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="What's the temperature in London?",
config=config,
)
print(response.text) # The SDK handles the function call and returns the final text
É possível desativar a chamada automática de funções com:
# To disable automatic function calling:
config = types.GenerateContentConfig(
tools=[get_current_temperature],
automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)
Declaração de esquema de função automática
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. 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:
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.
print(fn_decl.to_json_dict())
Uso de várias ferramentas: combine ferramentas nativas com chamadas de função
Com o Gemini 2.0, você pode ativar várias ferramentas, combinando ferramentas nativas com chamadas de função ao mesmo tempo. Confira um exemplo que ativa duas ferramentas, Grounding with Google Search e code execution, em uma solicitação usando a API Live.
# Multiple tasks example - combining lights, code execution, and search
prompt = """
Hey, I need you to do three things for me.
1. Turn on the lights.
2. Then compute the largest prime palindrome under 100000.
3. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.
Thanks!
"""
tools = [
{'google_search': {}},
{'code_execution': {}},
{'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]} # not defined here.
]
# Execute the prompt with specified tools in audio modality
await run(prompt, tools=tools, modality="AUDIO")
// Multiple tasks example - combining lights, code execution, and search
const prompt = `
Hey, I need you to do three things for me.
1. Turn on the lights.
2. Then compute the largest prime palindrome under 100000.
3. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.
Thanks!
`;
const tools = [
{ googleSearch: {} },
{ codeExecution: {} },
{ functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] } // not defined here.
];
// Execute the prompt with specified tools in audio modality
await run(prompt, {tools: tools, modality: "AUDIO"});
Os desenvolvedores de Python podem testar isso no notebook de uso da ferramenta de API ao vivo.
Modelos compatíveis
Os modelos experimentais não estão incluídos. Você pode encontrar os recursos na página Visão geral do modelo.
| Modelo | Chamada de função | Chamada de função paralela | Chamada de função com estrutura definida (somente API Live) |
|---|---|---|---|
| Gemini 2.0 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 2.0 Flash-Lite | X | X | X |
| Gemini 1.5 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 1.5 Pro | ✔️ | ✔️ | ✔️ |
Práticas recomendadas
- Descrições de função e parâmetro:seja extremamente claro e específico nas descrições. O modelo depende deles para escolher a função correta e fornecer argumentos adequados.
- Nomes:use nomes de função descritivos (sem espaços, pontos ou traços).
- Tipagem forte:use tipos específicos (números inteiros, strings, enumerações) para parâmetros para reduzir erros. Se um parâmetro tiver um conjunto limitado de valores válidos, use um tipo enumerado.
- Engenharia de comando:
- Fornecer contexto: informe ao modelo qual é a função dele (por exemplo, "Você é um assistente de clima útil.").
- Dar instruções: especificar como e quando usar funções (por exemplo, "Não adivinhe as datas. Use sempre uma data futura para as previsões.").
- Incentive a solicitação de esclarecimentos: instrua o modelo a fazer perguntas esclarecedoras, se necessário.
- Temperatura:use uma temperatura baixa (por exemplo, 0) para chamadas de função mais determinísticas e confiáveis.
- Validação:se uma chamada de função tiver consequências significativas (por exemplo, fazer um pedido), valide a chamada com o usuário antes de executá-la.
- Tratamento de erros: implemente um tratamento de erros robusto nas suas funções para lidar com entradas inesperadas ou falhas de API. Retorne mensagens de erro informativas que o modelo pode usar para gerar respostas úteis ao usuário.
- Segurança:tenha cuidado com a segurança ao chamar APIs externas. Use mecanismos de autenticação e autorização adequados. Evite expor dados sensíveis em chamadas de função.
- Limites de tokens:as descrições e os parâmetros da função são contabilizados no limite de tokens de entrada. Se você estiver atingindo os limites de token, considere limitar o número de funções ou a duração das descrições, dividindo tarefas complexas em conjuntos de funções menores e mais focados.
Observações e limitações
- Somente um subconjunto do esquema da OpenAPI é aceito.
- Os tipos de parâmetros compatíveis no Python são limitados.
- A chamada de função automática é um recurso exclusivo do SDK para Python.