Thirrja e funksioneve të lejon të lidhësh modelet me veglat dhe API-të e jashtme. Në vend që të gjenerojë përgjigje me tekst, modeli përcakton se kur të telefonojë funksione specifike dhe ofron parametrat e nevojshëm për të ekzekutuar veprime në botën reale. Kjo e lejon modelin të veprojë si një urë mes gjuhës natyrale dhe veprimeve dhe të dhënave të botës reale. Thirrja e funksionit ka 3 raste kryesore përdorimi:
- Ndërmerr veprime: Ndërvepro me sistemet e jashtme duke përdorur API-të, si p.sh. planifikimi i takimeve, krijimi i faturave, dërgimi i email-eve ose kontrolli i pajisjeve të shtëpisë inteligjente.
- Përmirëso njohuritë: Qasu te informacionet nga burime të jashtme si bazat e të dhënave, API-të dhe bazat e njohurive.
- Zgjero aftësitë: Përdor vegla të jashtme për të kryer llogaritje dhe për të zgjeruar kufizimet e modelit, si p.sh. përdorimi i një kalkulatori ose krijimi i grafikëve.
Mund të shfletosh shembuj të këtyre rasteve të përdorimit më poshtë:
Planifiko takimin
Ky shembull tregon se si të përcaktosh një funksion që planifikon një takim me pjesëmarrësit në një kohë specifike, duke lejuar që modeli të analizojë kërkesat e përdoruesit dhe të kthejë argumente të strukturuara për të aktivizuar veprimet në sistemet e jashtme.
Python
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()
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-3.8-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"ID: {function_call.id}")
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)
JavaScript
import { GoogleGenAI, Type } from '@google/genai';
// Configure the client
const ai = new GoogleGenAI({});
// 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-3.8-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(`ID: ${functionCall.id}`);
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);
}
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Define the function declaration for the model
scheduleMeetingFunc := &genai.FunctionDeclaration{
Name: "schedule_meeting",
Description: "Schedules a meeting with specified attendees at a given time and date.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"attendees": {
Type: genai.TypeArray,
Items: &genai.Schema{Type: genai.TypeString},
Description: "List of people attending the meeting.",
},
"date": {
Type: genai.TypeString,
Description: "Date of the meeting (e.g., '2024-07-29')",
},
"time": {
Type: genai.TypeString,
Description: "Time of the meeting (e.g., '15:00')",
},
"topic": {
Type: genai.TypeString,
Description: "The subject or topic of the meeting.",
},
},
Required: []string{"attendees", "date", "time", "topic"},
},
}
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{scheduleMeetingFunc}},
},
}
// Send request with function declarations
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.8-flash",
genai.Text("Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about the Q3 planning."),
config,
)
if err != nil {
log.Fatal(err)
}
// Check for a function call
if len(response.FunctionCalls()) > 0 {
functionCall := response.FunctionCalls()[0]
fmt.Printf("Function to call: %s\n", functionCall.Name)
fmt.Printf("ID: %s\n", functionCall.ID)
fmt.Printf("Arguments: %v\n", functionCall.Args)
// In a real app, you would call your function here:
// result := scheduleMeeting(functionCall.Args)
} else {
fmt.Println("No function call found in the response.")
fmt.Println(response.Text())
}
}
QETËSI
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-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"]
}
}
]
}
]
}'
Merr motin
Ky shembull tregon se si të përcaktosh një funksion që merr të dhënat e temperaturës për një vendndodhje, duke i mundësuar modelit të thërrasë API-të e jashtme për t'iu përgjigjur pyetjeve që kërkojnë informacione në kohë reale ose të jashtme.
Python
from google import genai
from google.genai import types
# Define the function declaration for the model
weather_function = {
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco",
},
},
"required": ["location"],
},
}
# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[weather_function])
config = types.GenerateContentConfig(tools=[tools])
# Send request with function declarations
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="What's the temperature in London?",
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"ID: {function_call.id}")
print(f"Arguments: {function_call.args}")
# In a real app, you would call your function here:
# result = get_current_temperature(**function_call.args)
else:
print("No function call found in the response.")
print(response.text)
JavaScript
import { GoogleGenAI, Type } from '@google/genai';
// Configure the client
const ai = new GoogleGenAI({});
// Define the function declaration for the model
const weatherFunctionDeclaration = {
name: 'get_current_temperature',
description: 'Gets the current temperature for a given location.',
parameters: {
type: Type.OBJECT,
properties: {
location: {
type: Type.STRING,
description: 'The city name, e.g. San Francisco',
},
},
required: ['location'],
},
};
// Send request with function declarations
const response = await ai.models.generateContent({
model: 'gemini-3.8-flash',
contents: "What's the temperature in London?",
config: {
tools: [{
functionDeclarations: [weatherFunctionDeclaration]
}],
},
});
// 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(`ID: ${functionCall.id}`);
console.log(`Arguments: ${JSON.stringify(functionCall.args)}`);
// In a real app, you would call your actual function here:
// const result = await getCurrentTemperature(functionCall.args);
} else {
console.log("No function call found in the response.");
console.log(response.text);
}
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Define the function declaration for the model
weatherFunc := &genai.FunctionDeclaration{
Name: "get_current_temperature",
Description: "Gets the current temperature for a given location.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"location": {
Type: genai.TypeString,
Description: "The city name, e.g. San Francisco",
},
},
Required: []string{"location"},
},
}
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{weatherFunc}},
},
}
// Send request with function declarations
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.8-flash",
genai.Text("What's the temperature in London?"),
config,
)
if err != nil {
log.Fatal(err)
}
// Check for a function call
if len(response.FunctionCalls()) > 0 {
functionCall := response.FunctionCalls()[0]
fmt.Printf("Function to call: %s\n", functionCall.Name)
fmt.Printf("ID: %s\n", functionCall.ID)
fmt.Printf("Arguments: %v\n", functionCall.Args)
// In a real app, you would call your function here:
// result := getCurrentTemperature(functionCall.Args)
} else {
fmt.Println("No function call found in the response.")
fmt.Println(response.Text())
}
}
QETËSI
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "What'\''s the temperature in London?"
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco"
}
},
"required": ["location"]
}
}
]
}
]
}'
Krijo grafikun
Ky shembull tregon se si të përcaktosh një funksion që gjeneron një grafik me shufra nga të dhënat e strukturuara, duke demonstruar se si modeli mund të përdorë vegla të jashtme për të kryer llogaritje ose për të krijuar asete vizuale:
Python
import os
from google import genai
from google.genai import types
# Define the function declaration for the model
create_chart_function = {
"name": "create_bar_chart",
"description": "Creates a bar chart given a title, labels, and corresponding values.",
"parameters": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title for the chart.",
},
"labels": {
"type": "array",
"items": {"type": "string"},
"description": "List of labels for the data points (e.g., ['Q1', 'Q2', 'Q3']).",
},
"values": {
"type": "array",
"items": {"type": "number"},
"description": "List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000]).",
},
},
"required": ["title", "labels", "values"],
},
}
# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[create_chart_function])
config = types.GenerateContentConfig(tools=[tools])
# Send request with function declarations
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="Create a bar chart titled 'Quarterly Sales' with data: Q1: 50000, Q2: 75000, Q3: 60000.",
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"ID: {function_call.id}")
print(f"Arguments: {function_call.args}")
# In a real app, you would call your function here using a charting library:
# result = create_bar_chart(**function_call.args)
else:
print("No function call found in the response.")
print(response.text)
JavaScript
import { GoogleGenAI, Type } from '@google/genai';
// Configure the client
const ai = new GoogleGenAI({});
// Define the function declaration for the model
const createChartFunctionDeclaration = {
name: 'create_bar_chart',
description: 'Creates a bar chart given a title, labels, and corresponding values.',
parameters: {
type: Type.OBJECT,
properties: {
title: {
type: Type.STRING,
description: 'The title for the chart.',
},
labels: {
type: Type.ARRAY,
items: { type: Type.STRING },
description: 'List of labels for the data points (e.g., ["Q1", "Q2", "Q3"]).',
},
values: {
type: Type.ARRAY,
items: { type: Type.NUMBER },
description: 'List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000]).',
},
},
required: ['title', 'labels', 'values'],
},
};
// Send request with function declarations
const response = await ai.models.generateContent({
model: 'gemini-3.8-flash',
contents: "Create a bar chart titled 'Quarterly Sales' with data: Q1: 50000, Q2: 75000, Q3: 60000.",
config: {
tools: [{
functionDeclarations: [createChartFunctionDeclaration]
}],
},
});
// 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(`ID: ${functionCall.id}`);
console.log(`Arguments: ${JSON.stringify(functionCall.args)}`);
// In a real app, you would call your actual function here:
// const result = await createBarChart(functionCall.args);
} else {
console.log("No function call found in the response.");
console.log(response.text);
}
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Define the function declaration for the model
createChartFunc := &genai.FunctionDeclaration{
Name: "create_bar_chart",
Description: "Creates a bar chart given a title, labels, and corresponding values.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"title": {
Type: genai.TypeString,
Description: "The title for the chart.",
},
"labels": {
Type: genai.TypeArray,
Items: &genai.Schema{Type: genai.TypeString},
Description: "List of labels for the data points (e.g., ['Q1', 'Q2', 'Q3']).",
},
"values": {
Type: genai.TypeArray,
Items: &genai.Schema{Type: genai.TypeNumber},
Description: "List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000]).",
},
},
Required: []string{"title", "labels", "values"},
},
}
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{createChartFunc}},
},
}
// Send request with function declarations
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.8-flash",
genai.Text("Create a bar chart titled 'Quarterly Sales' with data: Q1: 50000, Q2: 75000, Q3: 60000."),
config,
)
if err != nil {
log.Fatal(err)
}
// Check for a function call
if len(response.FunctionCalls()) > 0 {
functionCall := response.FunctionCalls()[0]
fmt.Printf("Function to call: %s\n", functionCall.Name)
fmt.Printf("ID: %s\n", functionCall.ID)
fmt.Printf("Arguments: %v\n", functionCall.Args)
// In a real app, you would call your function here using a charting library:
// result := createBarChart(functionCall.Args)
} else {
fmt.Println("No function call found in the response.")
fmt.Println(response.Text())
}
}
QETËSI
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Create a bar chart titled ''Quarterly Sales'' with data: Q1: 50000, Q2: 75000, Q3: 60000."
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "create_bar_chart",
"description": "Creates a bar chart given a title, labels, and corresponding values.",
"parameters": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title for the chart."
},
"labels": {
"type": "array",
"items": {"type": "string"},
"description": "List of labels for the data points (e.g., [''Q1'', ''Q2'', ''Q3''])."
},
"values": {
"type": "array",
"items": {"type": "number"},
"description": "List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000])."
}
},
"required": ["title", "labels", "values"]
}
}
]
}
]
}'
Si funksionon thirrja e funksionit
Thirrja e funksionit përfshin një ndërveprim të strukturuar midis aplikacionit tënd, modelit dhe funksioneve të jashtme. Këtu është një detajim i procesit:
- Përkufizo deklaratën e funksionit: Përkufizo deklaratën e funksionit në kodin e aplikacionit. Deklaratat e funksioneve përshkruajnë emrin, parametrat dhe qëllimin e funksionit për modelin.
- Thirr API-në me deklaratat e funksioneve: Dërgo kërkesën e përdoruesit bashkë me deklaratat e funksioneve te modeli. Ai analizon kërkesën dhe përcakton nëse një thirrje funksioni do të ishte e dobishme. Nëse po, ai përgjigjet me një objekt të strukturuar JSON që përmban emrin e funksionit, argumentet dhe një
idunik (kyidtani kthehet gjithmonë nga API-ja për modelet e Gemini 3*). - Ekzekuto kodin e funksionit (përgjegjësia jote): Modeli nuk
e ekzekuton vetë funksionin. Është përgjegjësia e aplikacionit tënd që të
përpunojë përgjigjen dhe të kontrollojë për një thirrje funksioni. Nëse
- Po: Nxirr emrin, argumentet dhe
ide funksionit dhe ekzekuto funksionin përkatës në aplikacionin tënd. - Jo: Modeli ka dhënë një përgjigje të drejtpërdrejtë me tekst për kërkesën (ky rrjedhë është më pak i theksuar në shembull, por është një rezultat i mundshëm).
- Po: Nxirr emrin, argumentet dhe
- Krijo një përgjigje të përshtatshme për përdoruesin: Nëse është ekzekutuar një funksion, regjistro rezultatin dhe dërgoje përsëri te modeli, duke u siguruar që të përfshish
idqë përputhet, në një ndërveprim vijues të bisedës. Ai do ta përdorë rezultatin për të gjeneruar një përgjigje përfundimtare të lehtë për t'u përdorur që përfshin informacionet nga thirrja e funksionit.
Ky proces mund të përsëritet në disa kthesa, duke lejuar ndërveprime dhe flukse pune komplekse. Modeli mbështet gjithashtu thirrjen e disa funksioneve në një kthesë të vetme (thirrja paralele e funksionit), në sekuencë (thirrja e funksionit të përbërë), dhe me veglat e integruara të Gemini (përdorimi i shumë veglave).
* Identifikuesit e funksioneve të hartës gjithmonë: Gemini 3 tani kthen gjithmonë një id unik me çdo functionCall. Përfshi këtë id të saktë në functionResponse në mënyrë që modeli të mund ta lidhë me saktësi rezultatin tënd me kërkesën origjinale.
Hapi 1: Përcakto një deklaratë funksioni
Përcakto një funksion dhe deklaratën e tij brenda kodit të aplikacionit që i lejon përdoruesit të caktojnë vlerat e dritës dhe të bëjnë një kërkesë API. Ky funksion mund të telefonojë shërbime ose API të jashtme.
Python
# 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}
JavaScript
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
};
}
Go
package main
import "google.golang.org/genai"
// Define a function declaration that the model can call to control smart lights
var setLightValuesDeclaration = &genai.FunctionDeclaration{
Name: "set_light_values",
Description: "Sets the brightness and color temperature of a light.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"brightness": {
Type: genai.TypeInteger,
Description: "Light level from 0 to 100. Zero is off and 100 is full brightness",
},
"color_temp": {
Type: genai.TypeString,
Enum: []string{"daylight", "cool", "warm"},
Description: "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
},
},
Required: []string{"brightness", "color_temp"},
},
}
// This is the actual function that would be called based on the model's suggestion
func setLightValues(brightness int, colorTemp string) map[string]any {
return map[string]any{
"brightness": brightness,
"colorTemperature": colorTemp,
}
}
Hapi 2: Telefononi modelin me deklaratat e funksionit
Pasi të kesh përcaktuar deklaratat e funksioneve, mund t'i kërkosh modelit që t'i përdorë ato. Ai analizon kërkesën dhe deklaratat e funksioneve dhe vendos nëse do t'i përgjigjet drejtpërdrejt apo do të thërrasë një funksion. Nëse thirret një funksion, objekti i përgjigjes do të përfshijë një sugjerim për thirrjen e funksionit.
Python
from google.genai import types
# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])
# 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-3.8-flash",
contents=contents,
config=config,
)
print(response.candidates[0].content.parts[0].function_call)
JavaScript
import { GoogleGenAI } from '@google/genai';
// Generation config with function declaration
const config = {
tools: [{
functionDeclarations: [setLightValuesFunctionDeclaration]
}]
};
// Configure the client
const ai = new GoogleGenAI({});
// 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-3.8-flash',
contents: contents,
config: config
});
console.log(response.functionCalls[0]);
Go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Generation config with function declaration
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{setLightValuesDeclaration}},
},
}
// Define user prompt
contents := []*genai.Content{
genai.NewContentFromText("Turn the lights down to a romantic level", genai.RoleUser),
}
// Send request with function declarations
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.FunctionCalls()[0])
Më pas, modeli kthen një objekt functionCall në një skemë të përputhshme me OpenAPI që specifikon se si të thirret një ose më shumë nga funksionet e deklaruara për t'iu përgjigjur pyetjes së përdoruesit.
Python
id='8f2b1a3c' args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'
JavaScript
{
id: '8f2b1a3c',
name: 'set_light_values',
args: { brightness: 25, color_temp: 'warm' }
}
Go
&{ID:8f2b1a3c Args:map[brightness:25 color_temp:warm] Name:set_light_values}
Hapi 3: Ekzekuto kodin e funksionit set_light_values
Nxirr detajet e thirrjes së funksionit nga përgjigjja e modelit, analizo argumentet dhe ekzekuto funksionin set_light_values.
Python
# Extract tool call details, it may not be in the first part.
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}")
JavaScript
// 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)}`);
}
Go
// Extract tool call details
toolCall := response.FunctionCalls()[0]
var result map[string]any
if toolCall.Name == "set_light_values" {
brightness := int(toolCall.Args["brightness"].(float64))
colorTemp := toolCall.Args["color_temp"].(string)
result = setLightValues(brightness, colorTemp)
fmt.Printf("Function execution result: %v\n", result)
}
Hapi 4: Krijo përgjigje të përshtatshme për përdoruesit me rezultatin e funksionit dhe telefono përsëri modelin
Në fund, dërgoji përsëri modelit rezultatin e ekzekutimit të funksionit që ai të mund t'i përfshijë këto informacione në përgjigjen e tij përfundimtare për përdoruesin.
Python
from google import genai
from google.genai import types
# Create a function response part
function_response_part = types.Part.from_function_response(
name=tool_call.name,
response={"result": result},
id=tool_call.id,
)
# Append function call and result of the function execution to contents
contents.append(response.candidates[0].content) # Append the content from the model's response.
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response
client = genai.Client()
final_response = client.models.generate_content(
model="gemini-3.8-flash",
config=config,
contents=contents,
)
print(final_response.text)
JavaScript
// Create a function response part
const function_response_part = {
name: tool_call.name,
response: { result },
id: tool_call.id
}
// Append function call and result of the function execution to contents
contents.push(response.candidates[0].content);
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-3.8-flash',
contents: contents,
config: config
});
console.log(final_response.text);
Go
// Create a function response part
functionResponsePart := &genai.Part{
FunctionResponse: &genai.FunctionResponse{
ID: toolCall.ID,
Name: toolCall.Name,
Response: result,
},
}
// Append function call and result of the function execution to contents
contents = append(contents, response.Candidates[0].Content)
contents = append(contents, &genai.Content{
Role: genai.RoleUser,
Parts: []*genai.Part{functionResponsePart},
})
// Get the final response from the model
finalResponse, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
log.Fatal(err)
}
fmt.Println(finalResponse.Text())
Kjo përfundon rrjedhën e thirrjes së funksionit. Modeli përdori me sukses funksionin "set_light_values" për të kryer veprimin e kërkuar të përdoruesit.
Deklaratat e funksioneve
Kur zbaton thirrjen e funksionit në një kërkesë, ti krijon një objekt tools, i cili përmban një ose më shumë function declarations. Ti i përcakton funksionet duke përdorur JSON, në mënyrë specifike me një nëngrup të zgjedhur të formatit të skemës OpenAPI. Një
deklaratë e vetme funksioni mund të përfshijë parametrat e mëposhtëm:
name(vargu): Një emër unik për funksionin (get_weather_forecast,send_email). Përdor emra përshkrues pa hapësira ose karaktere speciale (përdor nënvizime ose camelCase).description(vargu): Një shpjegim i qartë dhe i detajuar i qëllimit dhe aftësive të funksionit. Kjo është thelbësore që modeli të kuptojë se kur të përdorë funksionin. Ji specifik dhe jep shembuj nëse është e dobishme ("Gjen teatrot bazuar në vendndodhje dhe opsionalisht titullin e filmit që po shfaqet aktualisht në teatër.").parameters(objekti): Përcakton parametrat e hyrjes që pret funksioni.type(varg): Specifikon llojin e përgjithshëm të të dhënave, si p.sh.object.properties(objekt): Liston parametrat individualë, secili me:type(vargu): Lloji i të dhënave i parametrit, si p.sh.string,integer,boolean, array.description(varg): Një përshkrim i qëllimit dhe formatit të parametrit. Jep shembuj dhe kufizime ("Qyteti dhe shteti, p.sh. 'San Francisco, CA' ose një kod ZIP, p.sh. '95616'.").enum(masiv, opsional): Nëse vlerat e parametrit janë nga një grup i fiksuar, përdor "enum" për të listuar vlerat e lejuara në vend që t'i përshkruash ato thjesht në përshkrim. Kjo përmirëson saktësinë ("enum": ["daylight", "cool", "warm"]).
required(matrica): Një matricë vargjesh që liston emrat e parametrave që janë të detyrueshëm për funksionin që të funksionojë.
Mund të krijosh gjithashtu FunctionDeclarations nga funksionet e Python drejtpërdrejt duke përdorur
types.FunctionDeclaration.from_callable(client=client, callable=your_function).
Thirrja e funksionit me modelet arsyetuese
Modelet e serisë Gemini 3 dhe 2.5 përdorin një proces të brendshëm "të menduarit" për të arsyetuar nëpërmjet kërkesave. Kjo përmirëson ndjeshëm performancën e thirrjes së funksioneve, duke e lejuar modelin të përcaktojë më mirë se kur të thërrasë një funksion dhe cilët parametra të përdorë. Për shkak se Gemini API është pa gjendje, modelet përdorin nënshkrimet e mendimeve për të ruajtur kontekstin në bisedat me shumë kthesa.
Ky seksion mbulon menaxhimin e përparuar të nënshkrimeve të mendimeve dhe është i nevojshëm vetëm nëse po ndërton manualisht kërkesa API (p.sh. nëpërmjet REST) ose po manipulon historikun e bisedave.
Nëse po përdor SDK-të e IA-së gjeneruese të Google (bibliotekat tona zyrtare), nuk ke nevojë ta menaxhosh këtë proces. SDK-të trajtojnë automatikisht hapat e nevojshëm, siç tregohet në shembullin e mëparshëm.
Menaxhimi manual i historikut të bisedave
Nëse e modifikon manualisht historikun e bisedës, në vend që të dërgosh përgjigjen e plotë të mëparshme, duhet të trajosh në mënyrë të saktë thought_signature të përfshirë në radhën e modelit.
Ndiq këto rregulla për t'u siguruar që konteksti i modelit të ruhet:
- Dërgo gjithmonë
thought_signaturepërsëri te modeli brendaPartorigjinale. - Përfshi gjithmonë
idtë saktë ngafunction_callnëfunction_responsenë mënyrë që API-ja të mund ta lidhë rezultatin me kërkesën e duhur. - Mos bashko një
Partqë përmban një nënshkrim me një që nuk e ka. Kjo prish kontekstin pozicional të mendimit. - Mos kombino dy
Partsqë përmbajnë nënshkrime, pasi vargjet e nënshkrimeve nuk mund të bashkohen.
Nënshkrimet e mendimit të Gemini 3
Në Gemini 3, çdo Part e një përgjigjeje të modelit
mund të përmbajë një nënshkrim mendimi.
Ndërkohë që në përgjithësi rekomandojmë kthimin e nënshkrimeve nga të gjitha llojet e Part,
kthimi i nënshkrimeve të mendimeve është i detyrueshëm për thirrjen e funksioneve. Nëse nuk po e manipulon manualisht historikun e bisedave, Google GenAI SDK do t'i menaxhojë automatikisht nënshkrimet e mendimeve.
Nëse po e manipulon manualisht historikun e bisedave, referoju faqes së Nënshkrimeve të mendimeve për udhëzime dhe detaje të plota për trajtimin e nënshkrimeve të mendimeve për Gemini 3.
Nënshkrimet e mendimeve po inspektohen
Megjithëse nuk është e nevojshme për zbatimin, mund të kontrollosh përgjigjen për të parë
thought_signature për qëllime korrigjimi ose edukative.
Python
import base64
# After receiving a response from a model with thinking enabled
# response = client.models.generate_content(...)
# The signature is attached to the response part containing the function call
part = response.candidates[0].content.parts[0]
if part.thought_signature:
print(base64.b64encode(part.thought_signature).decode("utf-8"))
JavaScript
// After receiving a response from a model with thinking enabled
// const response = await ai.models.generateContent(...)
// The signature is attached to the response part containing the function call
const part = response.candidates[0].content.parts[0];
if (part.thoughtSignature) {
console.log(part.thoughtSignature);
}
Go
// After receiving a response from a model with thinking enabled
// response, err := client.Models.GenerateContent(...)
// The signature is attached to the response part containing the function call
part := response.Candidates[0].Content.Parts[0]
if len(part.ThoughtSignature) > 0 {
fmt.Println(string(part.ThoughtSignature))
}
Mëso më shumë rreth kufizimeve dhe përdorimit të nënshkrimeve të mendimeve dhe rreth modeleve të të menduarit në përgjithësi në faqen Të menduarit.
Thirrja paralele e funksionit
Përveç thirrjes së funksionit me një kthesë të vetme, mund të thërrasësh gjithashtu disa funksione njëherësh. Thirrja paralele e funksioneve të lejon të ekzekutosh disa funksione njëherësh dhe përdoret kur funksionet nuk varen nga njëra-tjetra. Kjo është e dobishme në skenarë të tillë si mbledhja e të dhënave nga burime të pavarura të shumta, si p.sh. marrja e detajeve të klientëve nga baza të ndryshme të të dhënave ose kontrolli i niveleve të inventarit nëpër magazina të ndryshme ose kryerja e veprimeve të shumta si shndërrimi i apartamentit tënd në një disko.
Kur modeli nis disa thirrje funksioni në një kthesë të vetme, nuk është e nevojshme që t'i kthesh objektet function_result në të njëjtin rend që janë marrë objektet function_call. API-ja e Gemini i lidh përsëri çdo rezultat me thirrjen përkatëse duke përdorur id nga dalja e modelit. Kjo të lejon që të ekzekutosh funksionet e tua në mënyrë asinkrone dhe të shtosh rezultatet në listën tënde ndërsa ato përfundojnë.
Python
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"],
},
}
JavaScript
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']
}
};
Go
package main
import "google.golang.org/genai"
var powerDiscoBall = &genai.FunctionDeclaration{
Name: "power_disco_ball",
Description: "Powers the spinning disco ball.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"power": {
Type: genai.TypeBoolean,
Description: "Whether to turn the disco ball on or off.",
},
},
Required: []string{"power"},
},
}
var startMusic = &genai.FunctionDeclaration{
Name: "start_music",
Description: "Play some music matching the specified parameters.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"energetic": {
Type: genai.TypeBoolean,
Description: "Whether the music is energetic or not.",
},
"loud": {
Type: genai.TypeBoolean,
Description: "Whether the music is loud or not.",
},
},
Required: []string{"energetic", "loud"},
},
}
var dimLights = &genai.FunctionDeclaration{
Name: "dim_lights",
Description: "Dim the lights.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"brightness": {
Type: genai.TypeNumber,
Description: "The brightness of the lights, 0.0 is off, 1.0 is full.",
},
},
Required: []string{"brightness"},
},
}
Konfiguro modalitetin e thirrjes së funksionit për të lejuar përdorimin e të gjitha veglave të specifikuara. Për të mësuar më shumë, mund të lexosh rreth konfigurimit të telefonatave të funksioneve.
Python
from google import genai
from google.genai import types
# Configure the client and tools
client = genai.Client()
house_tools = [
types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]
config = types.GenerateContentConfig(
tools=house_tools,
automatic_function_calling=types.AutomaticFunctionCallingConfig(
disable=True
),
# Force the model to call 'any' function, instead of chatting.
tool_config=types.ToolConfig(
function_calling_config=types.FunctionCallingConfig(mode='ANY')
),
)
chat = client.chats.create(model="gemini-3.8-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}) - ID: {fn.id}")
JavaScript
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({});
// Create a chat session
const chat = ai.chats.create({
model: 'gemini-3.8-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}) - ID: ${fn.id}`);
}
Go
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
houseTools := []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{powerDiscoBall, startMusic, dimLights}},
}
config := &genai.GenerateContentConfig{
Tools: houseTools,
// Force the model to call 'any' function, instead of chatting.
ToolConfig: &genai.ToolConfig{
FunctionCallingConfig: &genai.FunctionCallingConfig{
Mode: genai.FunctionCallingConfigModeAny,
},
},
}
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.8-flash",
genai.Text("Turn this place into a party!"),
config,
)
if err != nil {
log.Fatal(err)
}
// Print out each of the function calls requested from this single call
fmt.Println("Example 1: Forced function calling")
for _, fn := range response.FunctionCalls() {
fmt.Printf("%s(%v) - ID: %s\n", fn.Name, fn.Args, fn.ID)
}
Secili nga rezultatet e printuara pasqyron një thirrje të vetme funksioni që ka kërkuar modeli. Për t'i dërguar përsëri rezultatet, përfshi përgjigjet në të njëjtin rend siç janë kërkuar.
SDK-ja e Python mbështet thirrjen automatike të funksionit, e cila i konverton automatikisht funksionet e Python në deklarata, si dhe menaxhon ciklin e ekzekutimit të thirrjes së funksionit dhe të përgjigjes për ty. Më poshtë është një shembull për rastin e përdorimit të diskotekës.
Python
from google import genai
from google.genai import types
# Actual function implementations
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}
# Configure the client
client = genai.Client()
config = types.GenerateContentConfig(
tools=[power_disco_ball_impl, start_music_impl, dim_lights_impl]
)
# Make the request
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="Do everything you need to this place into party!",
config=config,
)
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!
Thirrja e funksionit të kompozimit
Thirrja e funksionit përbërës ose vijues lejon që Gemini të lidhë së bashku disa thirrje funksioni për të përmbushur një kërkesë komplekse. Për shembull, për t'iu përgjigjur "Merr temperaturën në vendndodhjen time aktuale", Gemini API mund të thërrasë në fillim një funksion të get_current_location() dhe më pas një funksion të get_weather() që merr vendndodhjen si parametër.
Shembulli i mëposhtëm demonstron se si të zbatosh thirrjen e funksionit të përbërë duke përdorur SDK-në e Python dhe thirrjen automatike të funksionit.
Python
Ky shembull përdor veçorinë e thirrjes automatike të funksionit të
google-genai Python SDK. SDK-ja i konverton automatikisht funksionet e Python në skemën e kërkuar, ekzekuton thirrjet e funksioneve kur kërkohet nga modeli dhe i dërgon rezultatet përsëri te modeli për të përfunduar detyrën.
import os
from google import genai
from google.genai import types
# Example Functions
def get_weather_forecast(location: str) -> dict:
"""Gets the current weather temperature for a given location."""
print(f"Tool Call: get_weather_forecast(location={location})")
# TODO: Make API call
print("Tool Response: {'temperature': 25, 'unit': 'celsius'}")
return {"temperature": 25, "unit": "celsius"} # Dummy response
def set_thermostat_temperature(temperature: int) -> dict:
"""Sets the thermostat to a desired temperature."""
print(f"Tool Call: set_thermostat_temperature(temperature={temperature})")
# TODO: Interact with a thermostat API
print("Tool Response: {'status': 'success'}")
return {"status": "success"}
# Configure the client and model
client = genai.Client()
config = types.GenerateContentConfig(
tools=[get_weather_forecast, set_thermostat_temperature]
)
# Make the request
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.",
config=config,
)
# Print the final, user-facing response
print(response.text)
Rezultati i pritshëm
Kur të ekzekutosh kodin, do të shikosh SDK-në që organizon thirrjet e funksionit. Modeli telefonon në fillim get_weather_forecast, merr temperaturën dhe më pas telefonon set_thermostat_temperature me vlerën e saktë bazuar në logjikën në kërkesë.
Tool Call: get_weather_forecast(location=London)
Tool Response: {'temperature': 25, 'unit': 'celsius'}
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: {'status': 'success'}
OK. I've set the thermostat to 20°C.
JavaScript
Ky shembull tregon se si të përdorësh SDK-në e JavaScript/TypeScript për të kryer thirrjen e funksionit të përbërë duke përdorur një lak ekzekutimi manual.
import { GoogleGenAI, Type } from "@google/genai";
// Configure the client
const ai = new GoogleGenAI({});
// Example Functions
function get_weather_forecast({ location }) {
console.log(`Tool Call: get_weather_forecast(location=${location})`);
// TODO: Make API call
console.log("Tool Response: {'temperature': 25, 'unit': 'celsius'}");
return { temperature: 25, unit: "celsius" };
}
function set_thermostat_temperature({ temperature }) {
console.log(
`Tool Call: set_thermostat_temperature(temperature=${temperature})`,
);
// TODO: Make API call
console.log("Tool Response: {'status': 'success'}");
return { status: "success" };
}
const toolFunctions = {
get_weather_forecast,
set_thermostat_temperature,
};
const tools = [
{
functionDeclarations: [
{
name: "get_weather_forecast",
description:
"Gets the current weather temperature for a given location.",
parameters: {
type: Type.OBJECT,
properties: {
location: {
type: Type.STRING,
},
},
required: ["location"],
},
},
{
name: "set_thermostat_temperature",
description: "Sets the thermostat to a desired temperature.",
parameters: {
type: Type.OBJECT,
properties: {
temperature: {
type: Type.NUMBER,
},
},
required: ["temperature"],
},
},
],
},
];
// Prompt for the model
let contents = [
{
role: "user",
parts: [
{
text: "If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.",
},
],
},
];
// Loop until the model has no more function calls to make
while (true) {
const result = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents,
config: { tools },
});
if (result.functionCalls && result.functionCalls.length > 0) {
const functionCall = result.functionCalls[0];
const { name, args } = functionCall;
if (!toolFunctions[name]) {
throw new Error(`Unknown function call: ${name}`);
}
// Call the function and get the response.
const toolResponse = toolFunctions[name](args);
const functionResponsePart = {
name: functionCall.name,
response: {
result: toolResponse,
},
id: functionCall.id,
};
// Send the function response back to the model.
contents.push({
role: "model",
parts: [
{
functionCall: functionCall,
},
],
});
contents.push({
role: "user",
parts: [
{
functionResponse: functionResponsePart,
},
],
});
} else {
// No more function calls, break the loop.
console.log(result.text);
break;
}
}
Rezultati i pritshëm
Kur të ekzekutosh kodin, do të shikosh SDK-në që organizon thirrjet e funksionit. Modeli telefonon në fillim get_weather_forecast, merr temperaturën dhe më pas telefonon set_thermostat_temperature me vlerën e saktë bazuar në logjikën në kërkesë.
Tool Call: get_weather_forecast(location=London)
Tool Response: {'temperature': 25, 'unit': 'celsius'}
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: {'status': 'success'}
OK. It's 25°C in London, so I've set the thermostat to 20°C.
Go
Ky shembull tregon se si të përdorësh Go SDK për të kryer thirrjen e funksionit të përbërë duke përdorur një lak ekzekutimi manual.
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func getWeatherForecast(location string) map[string]any {
fmt.Printf("Tool Call: get_weather_forecast(location=%s)\n", location)
fmt.Println("Tool Response: map[temperature:25 unit:celsius]")
return map[string]any{"temperature": 25, "unit": "celsius"}
}
func setThermostatTemperature(temperature float64) map[string]any {
fmt.Printf("Tool Call: set_thermostat_temperature(temperature=%v)\n", temperature)
fmt.Println("Tool Response: map[status:success]")
return map[string]any{"status": "success"}
}
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
tools := []*genai.Tool{
{
FunctionDeclarations: []*genai.FunctionDeclaration{
{
Name: "get_weather_forecast",
Description: "Gets the current weather temperature for a given location.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"location": {Type: genai.TypeString},
},
Required: []string{"location"},
},
},
{
Name: "set_thermostat_temperature",
Description: "Sets the thermostat to a desired temperature.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"temperature": {Type: genai.TypeNumber},
},
Required: []string{"temperature"},
},
},
},
},
}
config := &genai.GenerateContentConfig{Tools: tools}
contents := []*genai.Content{
genai.NewContentFromText("If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.", genai.RoleUser),
}
for {
result, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
log.Fatal(err)
}
if len(result.FunctionCalls()) > 0 {
functionCall := result.FunctionCalls()[0]
var toolResponse map[string]any
switch functionCall.Name {
case "get_weather_forecast":
location := functionCall.Args["location"].(string)
toolResponse = getWeatherForecast(location)
case "set_thermostat_temperature":
temperature := functionCall.Args["temperature"].(float64)
toolResponse = setThermostatTemperature(temperature)
default:
log.Fatalf("Unknown function call: %s", functionCall.Name)
}
contents = append(contents, result.Candidates[0].Content)
contents = append(contents, &genai.Content{
Role: genai.RoleUser,
Parts: []*genai.Part{
{
FunctionResponse: &genai.FunctionResponse{
ID: functionCall.ID,
Name: functionCall.Name,
Response: toolResponse,
},
},
},
})
} else {
fmt.Println(result.Text())
break
}
}
}
Rezultati i pritshëm
Tool Call: get_weather_forecast(location=London)
Tool Response: map[temperature:25 unit:celsius]
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: map[status:success]
OK. It's 25°C in London, so I've set the thermostat to 20°C.
Thirrja e funksionit përbërës është një veçori e integruar e Live API. Kjo do të thotë që Live API mund të menaxhojë thirrjen e funksioneve në mënyrë të ngjashme me Python SDK.
Python
# 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")
JavaScript
// 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")
Modalitetet e thirrjes së funksionit
Gemini API të lejon të kontrollosh se si modeli përdor veglat e ofruara (deklaratat e funksioneve). Në mënyrë specifike, mund ta caktosh modalitetin brenda
function_calling_config.
VALIDATED: Modaliteti i parazgjedhur për kombinimin e veglave (kur aktivizohen edhe veglat e integruara ose daljet e strukturuara). Modeli është i kufizuar për të parashikuar ose thirrjet e funksioneve ose gjuhën natyrale dhe siguron respektimin e skemës së funksioneve. Nëseallowed_function_namesnuk ofrohet, modeli zgjedh nga të gjitha deklaratat e funksioneve të disponueshme. Nëse ofrohetallowed_function_names, modeli zgjedh nga grupi i funksioneve të lejuara. Ky modalitet zvogëlon thirrjet e funksioneve të keqformuara (në krahasim me modalitetin "AUTO").AUTO: Modaliteti i parazgjedhur kur është aktivizuar vetëm veglat e function_declarations. Modeli vendos nëse do të gjenerojë një përgjigje në gjuhë natyrale apo do të sugjerojë një thirrje funksioni bazuar në kërkesën dhe kontekstin.ANY: Modeli është i kufizuar që të parashikojë gjithmonë një thirrje funksioni dhe siguron respektimin e skemës së funksionit. Nëseallowed_function_namesnuk specifikohet, modeli mund të zgjedhë nga cilido prej deklarimeve të funksioneve të dhëna. Nëseallowed_function_namesofrohet si listë, modeli mund të zgjedhë vetëm nga funksionet në atë listë. Përdor këtë modalitet kur kërkon një përgjigje të thirrjes së funksionit për çdo kërkesë (nëse zbatohet).NONE: Modeli nuk lejohet të bëjë telefonata funksioni. Kjo është ekuivalente me dërgimin e një kërkese pa asnjë deklaratë funksioni. Përdore këtë për të çaktivizuar përkohësisht thirrjen e funksionit pa i hequr përkufizimet e veglave.
Python
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(
tools=[tools], # not defined here.
tool_config=tool_config,
)
JavaScript
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 = {
tools: tools, // not defined here.
toolConfig: toolConfig,
};
Go
// Configure function calling mode
toolConfig := &genai.ToolConfig{
FunctionCallingConfig: &genai.FunctionCallingConfig{
Mode: genai.FunctionCallingConfigModeAny,
AllowedFunctionNames: []string{"get_current_temperature"},
},
}
// Create the generation config
config := &genai.GenerateContentConfig{
Tools: tools, // not defined here.
ToolConfig: toolConfig,
}
Thirrja automatike e funksionit (vetëm në Python)
Kur përdor SDK-në e Python, mund të ofrosh funksionet e Python drejtpërdrejt si vegla. SDK-ja i konverton këto funksione në deklarata, menaxhon ekzekutimin e thirrjes së funksionit dhe menaxhon ciklin e përgjigjes për ty. Përkufizo funksionin tënd me sugjerime për llojin dhe një docstring. Për rezultate optimale, rekomandohet të përdorësh vargjet e dokumentimit në stilin e Google. SDK-ja më pas do të:
- Zbulo përgjigjet e thirrjeve të funksioneve nga modeli.
- Thirr funksionin përkatës në Python në kodin tënd.
- Dërgo përgjigjen e funksionit përsëri te modeli.
- Kthe përgjigjen përfundimtare me tekst të modelit.
SDK-ja aktualisht nuk i analizon përshkrimet e argumenteve në vendet e përshkrimit të pronës të deklaratës së funksionit të gjeneruar. Në vend të kësaj, ai dërgon të gjithë vargun e dokumentacionit si përshkrimin e funksionit të nivelit më të lartë.
Python
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
client = genai.Client()
config = types.GenerateContentConfig(
tools=[get_current_temperature]
) # Pass the function itself
# Make the request
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="What's the temperature in Boston?",
config=config,
)
print(response.text) # The SDK handles the function call and returns the final text
Mund ta çaktivizosh thirrjen automatike të funksionit me:
Python
config = types.GenerateContentConfig(
tools=[get_current_temperature],
automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)
Deklarata e skemës së funksionit automatik
API-ja mund të përshkruajë cilindo nga llojet e mëposhtme. Pydantic lloje lejohen, për sa kohë që fushat e përcaktuara në to përbëhen gjithashtu nga lloje të lejuara. Llojet e fjalorëve (si dict[str: int]) nuk mbështeten mirë këtu, mos i përdor ato.
Python
AllowedType = (
int | float | bool | str | list['AllowedType'] | pydantic.BaseModel)
Për të parë se si duket skema e përfunduar, mund ta konvertosh atë duke përdorur
from_callable:
Python
from google import genai
from google.genai import types
def multiply(a: float, b: float):
"""Returns a * b."""
return a * b
client = genai.Client()
fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)
# to_json_dict() provides a clean JSON representation.
print(fn_decl.to_json_dict())
Përdorimi i shumë veglave: Kombino veglat e integruara me thirrjen e funksionit
Mund të aktivizosh disa vegla, duke kombinuar veglat e integruara me thirrjen e funksioneve në të njëjtin kërkesë.
Modelet Gemini 3 mund të kombinojnë veglat e integruara me thirrjen e funksioneve që ofrohet menjëherë, falë veçorisë së qarkullimit të kontekstit të veglave. Lexo faqen për Kombinimin e veglave të integruara dhe telefonatës së funksionit për të mësuar më shumë.
Python
from google import genai
from google.genai import types
client = genai.Client()
getWeather = {
"name": "getWeather",
"description": "Gets the weather for a requested city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city and state, e.g. Utqiaġvik, Alaska",
},
},
"required": ["city"],
},
}
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="What is the northernmost city in the United States? What's the weather like there today?",
config=types.GenerateContentConfig(
tools=[
types.Tool(
google_search=types.ToolGoogleSearch(), # Built-in tool
function_declarations=[getWeather] # Custom tool
),
],
include_server_side_tool_invocations=True
),
)
history = [
types.Content(
role="user",
parts=[types.Part(text="What is the northernmost city in the United States? What's the weather like there today?")]
),
response.candidates[0].content,
types.Content(
role="user",
parts=[types.Part(
function_response=types.FunctionResponse(
name="getWeather",
response={"response": "Very cold. 22 degrees Fahrenheit."},
id=response.candidates[0].content.parts[2].function_call.id
)
)]
)
]
response_2 = client.models.generate_content(
model="gemini-3.8-flash",
contents=history,
config=types.GenerateContentConfig(
tools=[
types.Tool(
google_search=types.ToolGoogleSearch(),
function_declarations=[getWeather]
),
],
include_server_side_tool_invocations=True
),
)
JavaScript
import { GoogleGenAI} from '@google/genai';
const client = new GoogleGenAI({});
const getWeather = {
name: "getWeather",
description: "Get the weather in a given location",
parameters: {
type: "OBJECT",
properties: {
location: {
type: "STRING",
description: "The city and state, e.g. San Francisco, CA"
}
},
required: ["location"]
}
};
async function run() {
const tools = [
{ googleSearch: {} },
{ functionDeclarations: [getWeather] }
];
const toolConfig = { includeServerSideToolInvocations: true };
const response1 = await client.models.generateContent({
model: "gemini-3.8-flash",
contents: [{role: "user", parts: [{text: "What is the northernmost city in the United States? What's the weather like there today?"}]}],
config: {
tools: tools,
toolConfig: toolConfig,
},
});
const functionCallId = response1.candidates[0].content.parts.find(p => p.functionCall)?.functionCall?.id;
const history = [
{
role: "user",
parts:[{text: "What is the northernmost city in the United States? What's the weather like there today?"}]
},
response1.candidates[0].content,
{
role: "user",
parts: [{
functionResponse: {
name: "getWeather",
response: {response: "Very cold. 22 degrees Fahrenheit."},
id: functionCallId
}
}]
}
];
const response2 = await client.models.generateContent({
model: "gemini-3.8-flash",
contents: history,
config: {
tools: tools,
toolConfig: toolConfig,
},
});
}
run();
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
getWeather := &genai.FunctionDeclaration{
Name: "getWeather",
Description: "Get the weather in a given location",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"location": {
Type: genai.TypeString,
Description: "The city and state, e.g. San Francisco, CA",
},
},
Required: []string{"location"},
},
}
tools := []*genai.Tool{
{GoogleSearch: &genai.GoogleSearch{}},
{FunctionDeclarations: []*genai.FunctionDeclaration{getWeather}},
}
config := &genai.GenerateContentConfig{
Tools: tools,
}
prompt := "What is the northernmost city in the United States? What's the weather like there today?"
response1, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text(prompt), config)
if err != nil {
log.Fatal(err)
}
toolCall := response1.FunctionCalls()[0]
history := []*genai.Content{
genai.NewContentFromText(prompt, genai.RoleUser),
response1.Candidates[0].Content,
{
Role: genai.RoleUser,
Parts: []*genai.Part{
{
FunctionResponse: &genai.FunctionResponse{
ID: toolCall.ID,
Name: toolCall.Name,
Response: map[string]any{"response": "Very cold. 22 degrees Fahrenheit."},
},
},
},
},
}
response2, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", history, config)
if err != nil {
log.Fatal(err)
}
fmt.Println(response2.Text())
}
Për modelet para serisë Gemini 3, përdor API-në Live.
Përgjigjet e funksionit multimodal
Për modelet e serisë Gemini 3, mund të përfshish përmbajtje multimodale në pjesët e përgjigjes së funksionit që i dërgon modelit. Modeli mund t'i përpunojë këto përmbajtje shumëmodale në radhën e tij të radhës për të prodhuar një përgjigje me më shumë informacione. Llojet e mëposhtme MIME mbështeten për përmbajtjet multimodale në përgjigjet e funksionit:
- Imazhet:
image/png,image/jpeg,image/webp - Dokumentet:
application/pdf,text/plain
Për të përfshirë të dhëna multimodale në një përgjigje të funksionit, përfshije atë si një ose më shumë pjesë të folezuara brenda pjesës functionResponse. Çdo pjesë multimodale duhet të përfshijë inlineData. Nëse referon një pjesë shumëmodale nga
brenda fushës së strukturuar response, ajo duhet të përmbajë një displayName unik.
Mund t'i referohesh gjithashtu një pjese multimodale nga brenda fushës së strukturuar response
të pjesës functionResponse duke përdorur formatin e referencës JSON
{"$ref": "<displayName>"}. Modeli zëvendëson referencën me përmbajtjen
multimodale kur përpunon përgjigjen. Çdo displayName mund të referohet vetëm një herë në fushën e strukturuar response.
Shembulli i mëposhtëm tregon një mesazh që përmban një functionResponse për një
funksion të quajtur get_image dhe një pjesë të mbivendosur që përmban të dhëna imazhi me
displayName: "instrument.jpg". Fusha response e functionResponse i referohet kësaj pjese të imazhit:
Python
from google import genai
from google.genai import types
import requests
client = genai.Client()
# This is a manual, two turn multimodal function calling workflow:
# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
name="get_image",
description="Retrieves the image file reference for a specific order item.",
parameters={
"type": "object",
"properties": {
"item_name": {
"type": "string",
"description": "The name or description of the item ordered (e.g., 'instrument')."
}
},
"required": ["item_name"],
},
)
tool_config = types.Tool(function_declarations=[get_image_declaration])
# 2. Send a message that triggers the tool
prompt = "Show me the instrument I ordered last month."
response_1 = client.models.generate_content(
model="gemini-3.8-flash",
contents=[prompt],
config=types.GenerateContentConfig(
tools=[tool_config],
)
)
# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")
# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")
function_response_data = {
"image_ref": {"$ref": "instrument.jpg"},
}
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
function_response_multimodal_data = types.FunctionResponsePart(
inline_data=types.FunctionResponseBlob(
mime_type="image/jpeg",
display_name="instrument.jpg",
data=image_bytes,
)
)
# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
types.Content(role="user", parts=[types.Part(text=prompt)]),
response_1.candidates[0].content,
types.Content(
role="user",
parts=[
types.Part.from_function_response(
id=function_call.id,
name=function_call.name,
response=function_response_data,
parts=[function_response_multimodal_data]
)
],
)
]
response_2 = client.models.generate_content(
model="gemini-3.8-flash",
contents=history,
config=types.GenerateContentConfig(
tools=[tool_config],
thinking_config=types.ThinkingConfig(include_thoughts=True)
),
)
print(f"\nFinal model response: {response_2.text}")
JavaScript
import { GoogleGenAI, Type } from '@google/genai';
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// This is a manual, two turn multimodal function calling workflow:
// 1. Define the function tool
const getImageDeclaration = {
name: 'get_image',
description: 'Retrieves the image file reference for a specific order item.',
parameters: {
type: Type.OBJECT,
properties: {
item_name: {
type: Type.STRING,
description: "The name or description of the item ordered (e.g., 'instrument').",
},
},
required: ['item_name'],
},
};
const toolConfig = {
functionDeclarations: [getImageDeclaration],
};
// 2. Send a message that triggers the tool
const prompt = 'Show me the instrument I ordered last month.';
const response1 = await client.models.generateContent({
model: 'gemini-3.8-flash',
contents: prompt,
config: {
tools: [toolConfig],
},
});
// 3. Handle the function call
const functionCall = response1.functionCalls[0];
const requestedItem = functionCall.args.item_name;
console.log(`Model wants to call: ${functionCall.name}`);
// Execute your tool (e.g., call an API)
// (This is a mock response for the example)
console.log(`Calling external tool for: ${requestedItem}`);
const functionResponseData = {
image_ref: { $ref: 'instrument.jpg' },
};
const imageUrl = "https://goo.gle/instrument-img";
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');
const functionResponseMultimodalData = {
inlineData: {
mimeType: 'image/jpeg',
displayName: 'instrument.jpg',
data: base64ImageData,
},
};
// 4. Send the tool's result back
// Append this turn's messages to history for a final response.
const history = [
{ role: 'user', parts: [{ text: prompt }] },
response1.candidates[0].content,
{
role: 'user',
parts: [
{
functionResponse: {
id: functionCall.id,
name: functionCall.name,
response: functionResponseData,
parts: [functionResponseMultimodalData]
},
},
],
},
];
const response2 = await client.models.generateContent({
model: 'gemini-3.8-flash',
contents: history,
config: {
tools: [toolConfig],
thinkingConfig: { includeThoughts: true },
},
});
console.log(`\nFinal model response: ${response2.text}`);
Go
package main
import (
"context"
"fmt"
"io"
"log"
"net/http"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// 1. Define the function tool
getImageDeclaration := &genai.FunctionDeclaration{
Name: "get_image",
Description: "Retrieves the image file reference for a specific order item.",
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"item_name": {
Type: genai.TypeString,
Description: "The name or description of the item ordered (e.g., 'instrument').",
},
},
Required: []string{"item_name"},
},
}
tools := []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{getImageDeclaration}},
}
// 2. Send a message that triggers the tool
prompt := "Show me the instrument I ordered last month."
response1, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text(prompt), &genai.GenerateContentConfig{
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
// 3. Handle the function call
functionCall := response1.FunctionCalls()[0]
requestedItem := functionCall.Args["item_name"]
fmt.Printf("Model wants to call: %s\n", functionCall.Name)
fmt.Printf("Calling external tool for: %v\n", requestedItem)
resp, err := http.Get("https://goo.gle/instrument-img")
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
imageBytes, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
functionResponseData := map[string]any{
"image_ref": map[string]any{"$ref": "instrument.jpg"},
}
functionResponseMultimodalData := &genai.FunctionResponsePart{
InlineData: &genai.FunctionResponseBlob{
MIMEType: "image/jpeg",
DisplayName: "instrument.jpg",
Data: imageBytes,
},
}
// 4. Send the tool's result back
history := []*genai.Content{
genai.NewContentFromText(prompt, genai.RoleUser),
response1.Candidates[0].Content,
{
Role: genai.RoleUser,
Parts: []*genai.Part{
{
FunctionResponse: &genai.FunctionResponse{
ID: functionCall.ID,
Name: functionCall.Name,
Response: functionResponseData,
Parts: []*genai.FunctionResponsePart{functionResponseMultimodalData},
},
},
},
},
}
response2, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", history, &genai.GenerateContentConfig{
Tools: tools,
ThinkingConfig: &genai.ThinkingConfig{
IncludeThoughts: true,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("\nFinal model response: %s\n", response2.Text())
}
QETËSI
IMG_URL="https://goo.gle/instrument-img"
MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
MIME_TYPE="image/jpeg"
fi
# Check for macOS
if [[ "$(uname)" == "Darwin" ]]; then
IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
...,
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_image",
"id": "UNIQUE_CALL_ID_HERE",
"response": {
"image_ref": {
"$ref": "instrument.jpg"
}
},
"parts": [
{
"inlineData": {
"displayName": "instrument.jpg",
"mimeType":"'"$MIME_TYPE"'",
"data": "'"$IMAGE_B64"'"
}
}
]
}
}
]
}
]
}'
Thirrja e funksionit me daljen e strukturuar
Për modelet e serisë Gemini 3, mund të përdorësh thirrjen e funksioneve me dalje të strukturuar. Kjo e lejon modelin të parashikojë thirrjet e funksioneve ose daljet që respektojnë një skemë specifike. Si rezultat, ti merr përgjigje të formatuara në mënyrë konsekuente kur modeli nuk gjeneron thirrje funksionesh.
Model Context Protocol (MCP)
Model Context Protocol (MCP) është një standard i hapur për lidhjen e aplikacioneve të IA-së me veglat dhe të dhënat e jashtme. MCP-ja ofron një protokoll të zakonshëm për modelet për t'u qasur te konteksti, si p.sh. funksionet (veglat), burimet e të dhënave (burimet) ose kërkesat e paravendosura.
SDK-të e Gemini kanë mbështetje të integruar për MCP-në, duke zvogëluar kodin e përsëritur dhe duke ofruar thirrjen automatike të veglave për veglat e MCP-së. Kur modeli gjeneron një thirrje të veglës MCP, SDK-ja e klientit në Python dhe JavaScript mund të ekzekutojë automatikisht veglën MCP dhe t'ia dërgojë përgjigjen përsëri modelit në një kërkesë pasuese, duke vazhduar këtë cikël derisa të mos bëhen më thirrje të veglave nga modeli.
Këtu mund të gjesh një shembull se si të përdorësh një server lokal MCP me Gemini dhe
mcp SDK.
Python
Sigurohu që versioni më i fundit i
mcp SDK është instaluar në
platformën tënde të zgjedhur.
pip install mcp
import os
import asyncio
from datetime import datetime
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai
client = genai.Client()
# Create server parameters for stdio connection
server_params = StdioServerParameters(
command="npx", # Executable
args=["-y", "@philschmid/weather-mcp"], # 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()
# Send request to the model with MCP function declarations
response = await client.aio.models.generate_content(
model="gemini-3.8-flash",
contents=prompt,
config=genai.types.GenerateContentConfig(
temperature=0,
tools=[session], # uses the session, will automatically call the tool
# Uncomment if you **don't** want the SDK to automatically call the tool
# automatic_function_calling=genai.types.AutomaticFunctionCallingConfig(
# disable=True
# ),
),
)
print(response.text)
# Start the asyncio event loop and run the main function
asyncio.run(run())
JavaScript
Sigurohu që versioni më i fundit i SDK-së së mcp është i instaluar në platformën tënde
të zgjedhur.
npm install @modelcontextprotocol/sdk
import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai';
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
// Create server parameters for stdio connection
const serverParams = new StdioClientTransport({
command: "npx", // Executable
args: ["-y", "@philschmid/weather-mcp"] // MCP Server
});
const client = new Client(
{
name: "example-client",
version: "1.0.0"
}
);
// Configure the client
const ai = new GoogleGenAI({});
// Initialize the connection between client and server
await client.connect(serverParams);
// Send request to the model with MCP tools
const response = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`,
config: {
tools: [mcpToTool(client)], // uses the session, will automatically call the tool
// Uncomment if you **don't** want the sdk to automatically call the tool
// automaticFunctionCalling: {
// disable: true,
// },
},
});
console.log(response.text)
// Close the connection
await client.close();
Kufizimet me mbështetjen e integruar të MCP-së
Mbështetja e integruar e MCP-së është një veçori eksperimentale në SDK-të tona dhe ka kufizimet e mëposhtme:
- Mbështeten vetëm veglat, jo burimet apo kërkesat
- Ajo ofrohet për SDK-në e Python dhe JavaScript/TypeScript.
- Ndryshimet e mëdha mund të ndodhin në publikimet e ardhshme.
Integrimi manual i serverëve MCP është gjithmonë një opsion nëse këto kufizojnë atë që po ndërton.
Modelet e mbështetura
Ky seksion liston modelet dhe aftësitë e tyre për thirrjen e funksioneve. Modelet eksperimentale nuk përfshihen. Mund të gjesh një përmbledhje gjithëpërfshirëse të aftësive në faqen e përmbledhjes së modelit.
| Modeli | Thirrja e funksionit | Thirrja paralele e funksionit | Thirrja e funksionit të kompozimit |
|---|---|---|---|
| Gemini 3.8 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 3.6 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 3.5 Flash-Lite | ✔️ | ✔️ | ✔️ |
| Versioni paraprak i Gemini 3.1 Pro | ✔️ | ✔️ | ✔️ |
| Gemini 3.1 Flash-Lite | ✔️ | ✔️ | ✔️ |
| Gemini 2.5 Pro | ✔️ | ✔️ | ✔️ |
| Gemini 2.5 Flash | ✔️ | ✔️ | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ | ✔️ | ✔️ |
Praktikat më të mira
- Përshkrimet e funksioneve dhe parametrave: Bëhu shumë i qartë dhe specifik në përshkrimet e tua. Modeli mbështetet te këto për të zgjedhur funksionin e saktë dhe për të ofruar argumentet e duhura.
- Emërtimi: Përdor emra funksionesh përshkrues (pa hapësira, pika ose viza).
- Tipizimi i fortë: Përdor lloje specifike (numër i plotë, varg, enumerim) për parametrat për të zvogëluar gabimet. Nëse një parametër ka një grup të kufizuar vlerash të vlefshme, përdor një enum.
- Zgjedhja e veglës: Ndërkohë që modeli mund të përdorë një numër të çfarëdoshëm veglash, ofrimi i shumë veglave mund të rritë rrezikun e zgjedhjes së një vegle të pasaktë ose jooptimale. Për rezultatet më të mira, syno të japësh vetëm veglat e përshtatshme për kontekstin ose detyrën, duke e mbajtur në mënyrë ideale grupin aktiv në maksimum 10-20. Ki parasysh zgjedhjen dinamike të veglave bazuar në kontekstin e bisedës nëse ke një numër të madh total veglash.
- Inxhinieria e kërkesave:
- Jep kontekstin: Tregoji modelit rolin e tij (p.sh. "Je një asistent i dobishëm për motin").
- Jep udhëzime: Specifiko se si dhe kur të përdorësh funksionet (p.sh. "Mos i merr datat me mend; përdor gjithmonë një datë të ardhshme për parashikimet.").
- Nxite sqarimin: Udhëzo modelin që të bëjë pyetje sqaruese nëse është e nevojshme.
- Shiko Flukset e punës të agjentit për strategji të mëtejshme për hartimin e këtyre kërkesave. Këtu është një shembull i një udhëzimi të testuar të sistemit.
Temperatura: Përdor një temperaturë të ulët (p.sh. 0) për thirrje funksionesh më deterministe dhe të besueshme.
Verifikimi: Nëse një telefonatë funksioni ka pasoja të rëndësishme (p.sh. vendosja e një porosie), verifiko telefonatën me përdoruesin para se ta ekzekutosh atë.
Kontrollo arsyen e përfundimit: Kontrollo gjithmonë
finishReasonnë përgjigjen e modelit për të trajtuar rastet kur modeli nuk arriti të gjenerojë një thirrje të vlefshme funksioni.Trajtimi i gabimeve: Zbato trajtim të fuqishëm të gabimeve në funksionet e tua për të trajtuar me efikasitet hyrjet e papritura ose dështimet e API-së. Kthe mesazhe informuese gabimesh që modeli mund t'i përdorë për të gjeneruar përgjigje të dobishme për përdoruesin.
Siguria: Ki parasysh sigurinë kur telefonon API të jashtme. Përdor mekanizmat e duhur të vërtetimit dhe autorizimit. Shmang ekspozimin e të dhënave delikate në thirrjet e funksioneve.
Kufijtë e kodeve: Përshkrimet e funksioneve dhe parametrat llogariten për kufirin tënd të kodeve të hyrjes. Nëse po arrin kufijtë e kodeve, ki parasysh të kufizosh numrin e funksioneve ose gjatësinë e përshkrimeve, si dhe t'i ndash detyrat komplekse në grupe funksionesh më të vogla dhe më të përqendruara.
Kombinimi i bash dhe veglave të personalizuara Për ata që krijojnë me një kombinim të bash dhe veglave të personalizuara, Gemini 3.1 Pro Preview vjen me një pikë të veçantë përfundimtare që ofrohet nëpërmjet API-së të quajtur
gemini-3.1-pro-preview-customtools.
Zgjidhje për kërkesat e tekstit para veglës
Problem: Nëse kërkesa jote kërkon që modeli të nxjerrë tekst të strukturuar (XML, YAML, JSON etj.) (p.sh. <UPDATE>...</UPDATE>) menjëherë para se të bësh një thirrje të veglës, thirrja e veglës mund të dështojë herë pas here me Malformed_Function_Call.
Zgjidhjet: Zgjidhjet e mëposhtme e zgjidhin këtë problem:
- PREFEROHET: Udhëzo modelin që t'i vendosë shënimet e tij para veglës brenda një thirrjeje funksioni të dedikuar
update()në vend të tekstit të papërpunuar (detajet më poshtë). - Instrukto modelin që të shkruajë shënime si tituj të "Shënimit të formatit" (
# UPDATE,## PLAN) në vend të tekstit të strukturuar. - Mos kërko që modeli të nxjerrë tekst para thirrjeve të veglave.
Zgjidhja e preferuar: Mbështill shënimet e punës në një thirrje të dedikuar funksioni
Në vend të udhëzimit origjinal:
Before calling a tool, in every response you MUST first output a single `<UPDATE>` part as specified, don't skip this part or any of required sub-tags within `<UPDATE>`.
Përdor këtë udhëzim të përditësuar:
Before calling any other tool, in every response you MUST first call `update` with all required parameters (previous_step, plan, next_step, external).
Dhe përditëso të gjitha referencat në formatin e vjetër XML <UPDATE> në kërkesën e klientit. Më pas shto deklaratën përkatëse të funksionit për funksionin e përditësimit:
{
"name": "update",
"description": "Update working notes (previous step analysis, plan, next step, external note).",
"parameters": {
"type": "OBJECT",
"properties": {
"previous_step": {
"type": "STRING",
"description": "Key findings and outcomes since the previous step."
},
"plan": {
"type": "STRING",
"description": "The current status of the plan."
},
"next_step": {
"type": "STRING",
"description": "Brief explanation of the immediate next action according to the plan."
},
"external": {
"type": "STRING",
"description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
}
},
"required": [
"previous_step",
"plan",
"next_step",
"external"
]
}
}
Më pas, modeli do të bëjë dy thirrje në të njëjtin hap: thirrjen update() që zëvendëson XML-në e strukturuar dhe thirrjen aktuale të funksionit që dëshiron të bëjë.
Shënime dhe kufizime
- Pozicionimi i pjesëve të thirrjes së funksionit: Kur përdor deklarime të personalizuara të funksioneve së bashku me veglat e integruara (si p.sh. "Kërko në Google"), modeli mund të kthejë një përzierje të pjesëve të
functionCall,toolCalldhetoolResponsenë një kthesë të vetme. Për këtë arsye, mos supozo sefunctionCalldo të jetë gjithmonë artikulli i fundit në vargun e pjesëve. Nëse po e analizon manualisht përgjigjen JSON, përsërit gjithmonë nëpër vargun e pjesëve në vend që të mbështetesh te pozicioni. - Mbështetet vetëm një nëngrup i skemës së OpenAPI.
- Për modalitetin
ANY, API-ja mund të refuzojë skemat shumë të mëdha ose me nivel të thellë. Nëse has gabime, provo të thjeshtosh skemat e parametrave dhe përgjigjeve të funksionit duke shkurtuar emrat e karakteristikave, duke zvogëluar nivelin e strukturës ose duke kufizuar numrin e deklarimeve të funksionit. - Llojet e mbështetura të parametrave në Python janë të kufizuara.
- Thirrja automatike e funksioneve është një veçori vetëm e Python SDK.