La chiamata di funzioni ti consente di collegare i modelli a strumenti e API esterni. Anziché generare risposte di testo, il modello comprende quando chiamare funzioni specifiche e fornisce i parametri necessari per eseguire azioni reali. In questo modo, il modello funge da ponte tra il linguaggio naturale e le azioni e i dati del mondo reale. Le chiamate di funzione hanno tre casi d'uso principali:
- Aumenta la conoscenza:accedi alle informazioni da origini esterne come database, API e knowledge base.
- Espandi le funzionalità:utilizza strumenti esterni per eseguire calcoli ed estendere le limitazioni del modello, ad esempio utilizzando una calcolatrice o creando grafici.
- Esegui azioni:interagisci con sistemi esterni utilizzando le API, ad esempio per pianificare appuntamenti, creare fatture, inviare email o controllare dispositivi per la smart home.
from google import genai
from google.genai import types
# Define the function declaration for the model
schedule_meeting_function = {
"name": "schedule_meeting",
"description": "Schedules a meeting with specified attendees at a given time and date.",
"parameters": {
"type": "object",
"properties": {
"attendees": {
"type": "array",
"items": {"type": "string"},
"description": "List of people attending the meeting.",
},
"date": {
"type": "string",
"description": "Date of the meeting (e.g., '2024-07-29')",
},
"time": {
"type": "string",
"description": "Time of the meeting (e.g., '15:00')",
},
"topic": {
"type": "string",
"description": "The subject or topic of the meeting.",
},
},
"required": ["attendees", "date", "time", "topic"],
},
}
# Configure the client and tools
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
tools = types.Tool(function_declarations=[schedule_meeting_function])
config = types.GenerateContentConfig(tools=[tools])
# Send request with function declarations
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about the Q3 planning.",
config=config,
)
# Check for a function call
if response.candidates[0].content.parts[0].function_call:
function_call = response.candidates[0].content.parts[0].function_call
print(f"Function to call: {function_call.name}")
print(f"Arguments: {function_call.args}")
# In a real app, you would call your function here:
# result = schedule_meeting(**function_call.args)
else:
print("No function call found in the response.")
print(response.text)
import { GoogleGenAI, Type } from '@google/genai';
// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Define the function declaration for the model
const scheduleMeetingFunctionDeclaration = {
name: 'schedule_meeting',
description: 'Schedules a meeting with specified attendees at a given time and date.',
parameters: {
type: Type.OBJECT,
properties: {
attendees: {
type: Type.ARRAY,
items: { type: Type.STRING },
description: 'List of people attending the meeting.',
},
date: {
type: Type.STRING,
description: 'Date of the meeting (e.g., "2024-07-29")',
},
time: {
type: Type.STRING,
description: 'Time of the meeting (e.g., "15:00")',
},
topic: {
type: Type.STRING,
description: 'The subject or topic of the meeting.',
},
},
required: ['attendees', 'date', 'time', 'topic'],
},
};
// Send request with function declarations
const response = await ai.models.generateContent({
model: 'gemini-2.0-flash',
contents: 'Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about the Q3 planning.',
config: {
tools: [{
functionDeclarations: [scheduleMeetingFunctionDeclaration]
}],
},
});
// Check for function calls in the response
if (response.functionCalls && response.functionCalls.length > 0) {
const functionCall = response.functionCalls[0]; // Assuming one function call
console.log(`Function to call: ${functionCall.name}`);
console.log(`Arguments: ${JSON.stringify(functionCall.args)}`);
// In a real app, you would call your actual function here:
// const result = await scheduleMeeting(functionCall.args);
} else {
console.log("No function call found in the response.");
console.log(response.text);
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about the Q3 planning."
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "schedule_meeting",
"description": "Schedules a meeting with specified attendees at a given time and date.",
"parameters": {
"type": "object",
"properties": {
"attendees": {
"type": "array",
"items": {"type": "string"},
"description": "List of people attending the meeting."
},
"date": {
"type": "string",
"description": "Date of the meeting (e.g., '2024-07-29')"
},
"time": {
"type": "string",
"description": "Time of the meeting (e.g., '15:00')"
},
"topic": {
"type": "string",
"description": "The subject or topic of the meeting."
}
},
"required": ["attendees", "date", "time", "topic"]
}
}
]
}
]
}'
Come funzionano le chiamate di funzione
La chiamata di funzioni prevede un'interazione strutturata tra l'applicazione, il modello e le funzioni esterne. Ecco una suddivisione della procedura:
- Definisci la dichiarazione di funzione:definisci la dichiarazione di funzione nel codice dell'applicazione. Le dichiarazioni di funzione descrivono il nome, i parametri e lo scopo della funzione al modello.
- Chiama LLM con dichiarazioni di funzione:invia al modello la richiesta dell'utente insieme alle dichiarazioni di funzione. Analizza la richiesta e determina se una chiamata di funzione sarebbe utile. In questo caso, risponde con un oggetto JSON strutturato.
- Codice funzione di esecuzione (responsabilità dell'utente): il modello non
esegue la funzione stessa. È responsabilità della tua applicazione elaborare la risposta e verificare la presenza di una chiamata di funzione, se
- Sì: estrai il nome e gli argomenti della funzione ed esegui la funzione corrispondente nella tua applicazione.
- No: il modello ha fornito una risposta di testo diretta al prompt (questo flusso è meno enfatizzato nell'esempio, ma è un possibile risultato).
- Crea una risposta facile da usare:se è stata eseguita una funzione, acquisisci il risultato e rispediscilo al modello in un turno successivo della conversazione. Utilizzerà il risultato per generare una risposta finale facile da usare che incorpori le informazioni della chiamata di funzione.
Questa procedura può essere ripetuta per più turni, consentendo interazioni e flussi di lavoro complessi. Il modello supporta anche la chiamata di più funzioni in un singolo turno (chiamate di funzioni in parallelo) e in sequenza (chiamate di funzioni compositive).
Passaggio 1: definisci la dichiarazione della funzione
Definisci una funzione e la relativa dichiarazione all'interno del codice dell'applicazione che consenta agli utenti di impostare i valori delle luci ed effettuare una richiesta API. Questa funzione potrebbe chiamare API o servizi esterni.
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
};
}
Passaggio 2: chiama il modello con le dichiarazioni di funzione
Dopo aver definito le dichiarazioni delle funzioni, puoi chiedere al modello di utilizzarla. Analizza le dichiarazioni del prompt e delle funzioni e decide se rispondere direttamente o chiamare una funzione. Se viene chiamata una funzione, l'oggetto risposta conterrà un suggerimento per la chiamata della funzione.
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]);
Il modello restituisce quindi un oggetto functionCall in uno schema compatibile con OpenAPI che specifica come chiamare una o più delle funzioni dichiarate per rispondere alla domanda dell'utente.
id=None args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'
{
name: 'set_light_values',
args: { brightness: 25, color_temp: 'warm' }
}
Passaggio 3: esegui il codice della funzione set_light_values
Estrai i dettagli della chiamata di funzione dalla risposta del modello, analizza gli argomenti
esegui la funzione set_light_values nel nostro codice.
# 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)}`);
}
Passaggio 4: crea una risposta facile da usare con il risultato della funzione e chiama di nuovo il modello
Infine, invia il risultato dell'esecuzione della funzione al modello in modo che possa incorporare queste informazioni nella risposta finale all'utente.
# 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);
In questo modo, il flusso di chiamata della funzione è completato. Il modello ha utilizzato correttamente la funzione set_light_values per eseguire l'azione di richiesta dell'utente.
Dichiarazioni di funzione
Quando implementi la chiamata di funzione in un prompt, crei un oggetto tools contenente uno o più function declarations. Definisci le funzioni utilizzando JSON, in particolare con un sottoinsieme selezionato del formato dello schema OpenAPI. Una singola dichiarazione di funzione può includere i seguenti parametri:
name(stringa): un nome univoco per la funzione (get_weather_forecast,send_email). Utilizza nomi descrittivi senza spazi o caratteri speciali (utilizza trattini bassi o lettere maiuscole e minuscole).description(stringa): una spiegazione chiara e dettagliata dello scopo e delle funzionalità della funzione. Questo è fondamentale per consentire al modello di capire quando utilizzare la funzione. Fornisci esempi se utili ("Trova i cinema in base alla località e, facoltativamente, al titolo del film attualmente in programmazione").parameters(oggetto): definisce i parametri di input previsti dalla funzione.type(stringa): specifica il tipo di dati complessivo, ad esempioobject.properties(oggetto): elenca i singoli parametri, ciascuno con:type(stringa): il tipo di dati del parametro, ad esempiostring,integer,boolean, array.description(stringa): una descrizione dello scopo e del formato del parametro. Fornisci esempi e vincoli ("La città e lo stato, ad es. "San Francisco, CA" o un codice postale, ad esempio '95616'.").enum(array, facoltativo): se i valori del parametro provengono da un insieme fisso, utilizza "enum" per elencare i valori consentiti anziché descriverli semplicemente nella descrizione. In questo modo si migliora la precisione ("enum": ["daylight", "cool", "warm"]).
required(array): un array di stringhe che elenca i nomi dei parametri obbligatori per il funzionamento della funzione.
Chiamata di funzioni parallele
Oltre a chiamare una singola funzione di svolta, puoi anche chiamare più funzioni contemporaneamente. La chiamata di funzioni parallele consente di eseguire più funzioni contemporaneamente e viene utilizzata quando le funzioni non sono dipendenti l'una dall'altra. Questo è utile in scenari come la raccolta di dati da più origini indipendenti, ad esempio il recupero dei dettagli dei clienti da diversi database o il controllo dei livelli di inventario in vari magazzini o l'esecuzione di più azioni come la conversione del tuo appartamento in un locale.
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']
}
};
Chiama il modello con un'istruzione che potrebbe utilizzare tutti gli strumenti specificati. Questo esempio utilizza un tool_config. Per scoprire di più, puoi leggere l'articolo sulla configurazione delle chiamate di funzione.
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})`);
}
Ciascuno dei risultati stampati riflette una singola chiamata di funzione richiesta dal modello. Per inviare i risultati, includi le risposte nello stesso ordine in cui sono state richieste.
L'SDK Python supporta una funzionalità chiamata chiamata di funzioni automatica che converte la funzione Python in dichiarazioni, gestisce l'esecuzione della chiamata di funzione e il ciclo di risposta per te. Di seguito è riportato un esempio per il nostro caso d'uso 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!
Chiamata di funzioni compositive
Gemini 2.0 supporta le chiamate di funzioni compositive, il che significa che il modello può mettere in catena più chiamate di funzioni. Ad esempio, per rispondere a "Richiedi la temperatura nella mia posizione attuale", l'API Gemini potrebbe chiamare sia una funzione get_current_location() sia una funzione get_weather() che prende la posizione come parametro.
# 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")
Modalità di chiamata di funzione
L'API Gemini ti consente di controllare il modo in cui il modello utilizza gli strumenti forniti (dichiarazioni di funzione). Nello specifico, puoi impostare la modalità in function_calling_config.
AUTO (Default): il modello decide se generare una risposta in linguaggio naturale o suggerire una chiamata di funzione in base al prompt e al contesto. Si tratta della modalità più flessibile e consigliata per la maggior parte degli scenari.ANY: il modello è vincolato a prevedere sempre una chiamata di funzione e a garantire l'adesione allo schema della funzione. Seallowed_function_namesnon è specificato, il modello può scegliere tra le dichiarazioni di funzione fornite. Seallowed_function_namesviene fornito come elenco, il modello può scegliere solo tra le funzioni nell'elenco. Utilizza questa modalità quando richiedi una chiamata di funzione in risposta a ogni prompt (se applicabile).NONE: al modello è vietato effettuare chiamate di funzione. Ciò equivale a inviare una richiesta senza dichiarazioni di funzioni. Utilizzalo per disattivare temporaneamente le chiamate di funzione senza rimuovere le definizioni degli strumenti.
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,
};
Chiamata di funzioni automatiche (solo Python)
Quando utilizzi l'SDK Python, puoi fornire le funzioni Python direttamente come strumenti. L'SDK converte automaticamente la funzione Python in dichiarazioni e gestisce l'esecuzione della chiamata della funzione e il ciclo di risposta. L'SDK Python esegue automaticamente le seguenti operazioni:
- Rileva le risposte alle chiamate di funzione del modello.
- Chiama la funzione Python corrispondente nel codice.
- Invia la risposta della funzione al modello.
- Restituisce la risposta di testo finale del modello.
Per utilizzarlo, definisci la funzione con suggerimenti sui tipi e una docstring, quindi passa la funzione stessa (non una dichiarazione JSON) come strumento:
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
Puoi disattivare la chiamata automatica delle funzioni con:
# To disable automatic function calling:
config = types.GenerateContentConfig(
tools=[get_current_temperature],
automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)
Dichiarazione dello schema della funzione automatica
L'estrazione automatica dello schema dalle funzioni Python non funziona in tutti i casi. Ad esempio, non gestisce i casi in cui descrivi i campi di un oggetto dizionario nidificato. L'API è in grado di descrivere uno dei seguenti tipi:
AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])
Per vedere l'aspetto dello schema dedotto, puoi convertirlo utilizzando 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())
Utilizzo di più strumenti: combina gli strumenti nativi con le chiamate di funzione
Con Gemini 2.0, puoi attivare più strumenti contemporaneamente combinando gli strumenti nativi con le chiamate di funzione. Di seguito è riportato un esempio che attiva due strumenti, Grounding con la Ricerca Google ed esecuzione di codice, in una richiesta che utilizza l'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"});
Gli sviluppatori Python possono provare questa funzionalità nel notebook di utilizzo dello strumento API Live.
Utilizzare il protocollo MCP (Model Context Protocol)
Model Context Protocol (MCP) è uno standard aperto per collegare le applicazioni di IA a strumenti, origini dati e sistemi esterni. MCP fornisce un protocollo comune per consentire ai modelli di accedere al contesto, ad esempio funzioni (strumenti), origini dati (risorse) o prompt predefiniti. Puoi utilizzare i modelli con il server MCP utilizzando le funzionalità di chiamata dello strumento.
I server MCP espongono gli strumenti come definizioni dello schema JSON, che possono essere utilizzati con le dichiarazioni di funzioni compatibili con Gemini. In questo modo puoi utilizzare direttamente un server MCP con i modelli Gemini. Qui puoi trovare un esempio di come utilizzare un server MCP locale con Gemini, l'SDK Python e l'SDK mcp.
import asyncio
import os
from datetime import datetime
from google import genai
from google.genai import types
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
# Create server parameters for stdio connection
server_params = StdioServerParameters(
command="npx", # Executable
args=["-y", "@philschmid/weather-mcp"], # Weather MCP Server
env=None, # Optional environment variables
)
async def run():
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# Prompt to get the weather for the current day in London.
prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"
# Initialize the connection between client and server
await session.initialize()
# Get tools from MCP session and convert to Gemini Tool objects
mcp_tools = await session.list_tools()
tools = [
types.Tool(
function_declarations=[
{
"name": tool.name,
"description": tool.description,
"parameters": {
k: v
for k, v in tool.inputSchema.items()
if k not in ["additionalProperties", "$schema"]
},
}
]
)
for tool in mcp_tools.tools
]
# Send request to the model with MCP function declarations
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=prompt,
config=types.GenerateContentConfig(
temperature=0,
tools=tools,
),
)
# Check for a function call
if response.candidates[0].content.parts[0].function_call:
function_call = response.candidates[0].content.parts[0].function_call
print(function_call)
# Call the MCP server with the predicted tool
result = await session.call_tool(
function_call.name, arguments=function_call.args
)
print(result.content[0].text)
# Continue as shown in step 4 of "How Function Calling Works"
# and create a user friendly response
else:
print("No function call found in the response.")
print(response.text)
# Start the asyncio event loop and run the main function
asyncio.run(run())
Modelli supportati
I modelli sperimentali non sono inclusi. Puoi trovare le relative funzionalità nella pagina Panoramica del modello.
| Modello | Chiamate di funzione | Chiamata di funzioni parallele | Chiamate di funzioni compositive (solo API Live) |
|---|---|---|---|
| Gemini 2.0 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 2.0 Flash-Lite | X | X | X |
| Gemini 1.5 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 1.5 Pro | ✔️ | ✔️ | ✔️ |
Best practice
- Descrizioni di funzioni e parametri:descrivi le funzioni e i parametri in modo estremamente chiaro e specifico. Il modello si basa su questi dati per scegliere la funzione corretta e fornire gli argomenti appropriati.
- Nomi: utilizza nomi di funzioni descrittivi (senza spazi, punti o trattini).
- Tipizzazione forte:utilizza tipi specifici (integer, string, enum) per i parametri per ridurre gli errori. Se un parametro ha un insieme limitato di valori validi, utilizza un enum.
- Selezione degli strumenti:anche se il modello può utilizzare un numero arbitrario di strumenti, fornendoli in eccesso puoi aumentare il rischio di selezionare uno strumento errato o non ottimale. Per ottenere risultati ottimali, cerca di fornire solo gli strumenti pertinenti per il contesto o l'attività, mantenendo idealmente l'insieme attivo a un massimo di 10-20. Valuta la selezione dinamica degli strumenti in base al contesto della conversazione se hai un numero elevato di strumenti.
- Prompt engineering:
- Fornisci il contesto: indica al modello il suo ruolo (ad es. "Sei un'assistente meteo utile").
- Fornisci istruzioni: specifica come e quando utilizzare le funzioni (ad es. "Non indovinare le date; utilizza sempre una data futura per le previsioni".
- Incoraggia i chiarimenti: se necessario, chiedi al modello di porre domande per chiarire.
- Temperatura:utilizza una temperatura bassa (ad es. 0) per chiamate di funzioni più deterministiche e affidabili.
- Convalida:se una chiamata di funzione ha conseguenze significative (ad es. l'inserimento di un ordine), convalida la chiamata con l'utente prima di eseguirla.
- Gestione degli errori: implementa una gestione degli errori solida nelle tue funzioni per gestire in modo elegante input imprevisti o errori dell'API. Restituire messaggi di errore informativi che il modello può utilizzare per generare risposte utili all'utente.
- Sicurezza:presta attenzione alla sicurezza quando chiami API esterne. Utilizza meccanismi di autenticazione e autorizzazione appropriati. Evita di esporre dati sensibili nelle chiamate alle funzioni.
- Limiti di token:le descrizioni e i parametri delle funzioni vengono conteggiati ai fini del limite di token di input. Se raggiungi i limiti di token, valuta la possibilità di limitare il numero di funzioni o la lunghezza delle descrizioni, suddividi le attività complesse in insiemi di funzioni più piccoli e mirati.
Note e limitazioni
- È supportato solo un sottoinsieme dello schema OpenAPI.
- I tipi di parametri supportati in Python sono limitati.
- La chiamata automatica delle funzioni è una funzionalità solo dell'SDK Python.