Gemini, बिल्ट-इन टूल (जैसे, google_search) और फ़ंक्शन कॉलिंग (जिसे कस्टम टूल भी कहा जाता है) को एक साथ इस्तेमाल करने की अनुमति देता है. इसके लिए, टूल कॉल के कॉन्टेक्स्ट के इतिहास को सेव किया जाता है और उसे दिखाया जाता है. बिल्ट-इन और कस्टम टूल के कॉम्बिनेशन की मदद से, एजेंटिक वर्कफ़्लो को आसानी से पूरा किया जा सकता है. उदाहरण के लिए, मॉडल आपकी खास कारोबार की लॉजिक को कॉल करने से पहले, रीयल-टाइम में वेब डेटा के आधार पर खुद को ग्राउंड कर सकता है.
यहां एक उदाहरण दिया गया है, जिसमें google_search और कस्टम फ़ंक्शन getWeather के साथ, बिल्ट-इन और कस्टम टूल के कॉम्बिनेशन का इस्तेमाल किया गया है:
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"],
},
}
# Turn 1: Initial request with Google Search (built-in) and getWeather (custom) tools enabled
response = client.models.generate_content(
model="gemini-3-flash-preview",
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
),
)
for part in response.candidates[0].content.parts:
if part.tool_call:
print(f"Tool call: {part.tool_call.tool_type} (ID: {part.tool_call.id})")
if part.tool_response:
print(f"Tool response: {part.tool_response.tool_type} (ID: {part.tool_response.id})")
if part.function_call:
print(f"Function call: {part.function_call.name} (ID: {part.function_call.id})")
# Turn 2: Manually build history to circulate both tool and function context
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 from Turn 1 includes tool_call, tool_response, and thought_signatures
response.candidates[0].content,
# Return the function_response
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 # Match the ID from the function_call
)
)]
)
]
response_2 = client.models.generate_content(
model="gemini-3-flash-preview",
contents=history,
config=types.GenerateContentConfig(
tools=[
types.Tool(
google_search=types.ToolGoogleSearch(),
function_declarations=[getWeather]
),
],
# This flag needs to be enabled for built-in tool context circulation and tool combination
include_server_side_tool_invocations=True
),
)
for part in response_2.candidates[0].content.parts:
if part.text:
print(part.text)
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 model = client.getGenerativeModel({
model: "gemini-3-flash-preview",
});
const tools = [
{ googleSearch: {} },
{ functionDeclarations: [getWeather] }
];
// This flag needs to be enabled for built-in tool context circulation and tool combination
const toolConfig = { includeServerSideToolInvocations: true };
// Turn 1: Initial request with Google Search (built-in) and getWeather (custom) tools enabled
const result1 = await model.generateContent({
contents: [{role: "user", parts: [{text: "What is the northernmost city in the United States? What's the weather like there today?"}]}],
tools: tools,
toolConfig: toolConfig,
});
const response1 = result1.response;
for (const part of response1.candidates[0].content.parts) {
if (part.toolCall) {
console.log(`Tool call: ${part.toolCall.toolType} (ID: ${part.toolCall.id})`);
}
if (part.toolResponse) {
console.log(`Tool response: ${part.toolResponse.toolType} (ID: ${part.toolResponse.id})`);
}
if (part.functionCall) {
console.log(`Function call: ${part.functionCall.name} (ID: ${part.functionCall.id})`);
}
}
const functionCallId = response1.candidates[0].content.parts.find(p => p.functionCall)?.functionCall?.id;
// Turn 2: Manually build history to circulate both tool and function context
const history = [
{
role: "user",
parts:[{text: "What is the northernmost city in the United States? What's the weather like there today?"}]
},
// Response from Turn 1 includes tool_call, tool_response, and thought_signatures
response1.candidates[0].content,
// Return the function_response
{
role: "user",
parts: [{
functionResponse: {
name: "getWeather",
response: {response: "Very cold. 22 degrees Fahrenheit."},
id: functionCallId // Match the ID from the function_call
}
}]
}
];
const result2 = await model.generateContent({
contents: history,
tools: tools,
toolConfig: toolConfig,
});
for (const part of result2.response.candidates[0].content.parts) {
if (part.text) {
console.log(part.text);
}
}
}
run();
ऐप पर जाएं
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/google/generative-ai-go/genai"
"google.golang.org/api/option"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GEMINI_API_KEY")))
if err != nil {
log.Exit(err)
}
defer client.Close()
getWeather := &genai.FunctionDeclaration{
Name: "getWeather",
Description: "Get the weather in a given location",
Parameters: &genai.Schema{
Type: genai.Object,
Properties: map[string]*genai.Schema{
"location": {
Type: genai.String,
Description: "The city and state, e.g. San Francisco, CA",
},
},
Required: []string{"location"},
},
}
model := client.GenerativeModel("gemini-3-flash-preview")
model.Tools = []*genai.Tool{
{GoogleSearch: &genai.GoogleSearch{}}, // Built-in tool
{FunctionDeclarations: []*genai.FunctionDeclaration{getWeather}}, // Custom tool
}
ist := true
model.ToolConfig = &genai.ToolConfig{
IncludeServerSideToolInvocations: &ist, // This flag needs to be enabled for built-in tool context circulation and tool combination
}
chat := model.StartChat()
// Turn 1: Initial request with Google Search (built-in) and getWeather (custom) tools enabled
prompt := genai.Text("What is the northernmost city in the United States? What's the weather like there today?")
resp1, err := chat.SendMessage(ctx, prompt)
if err != nil {
log.Exitf("SendMessage failed: %v", err)
}
if resp1 == nil || len(resp1.Candidates) == 0 || resp1.Candidates[0].Content == nil {
log.Exit("empty response from model")
}
var functionCallID string
for _, part := range resp1.Candidates[0].Content.Parts {
switch p := part.(type) {
case genai.FunctionCall:
fmt.Printf("Function call: %s (ID: %s)\n", p.Name, p.ID)
if p.Name == "getWeather" {
functionCallID = p.ID
}
case genai.ToolCallPart:
fmt.Printf("Tool call: %s (ID: %s)\n", p.ToolType, p.ID)
case genai.ToolResponsePart:
fmt.Printf("Tool response: %s (ID: %s)\n", p.ToolType, p.ID)
}
}
if functionCallID == "" {
log.Exit("no getWeather function call in response")
}
// Turn 2: Provide function result back to model.
// Chat history automatically includes tool_call, tool_response, and thought_signatures from Turn 1.
fr := genai.FunctionResponse{
Name: "getWeather",
ID: functionCallID,
Response: map[string]any{
"response": "Very cold. 22 degrees Fahrenheit.",
},
}
resp2, err := chat.SendMessage(ctx, fr)
if err != nil {
log.Exitf("SendMessage for turn 2 failed: %v", err)
}
if resp2 == nil || len(resp2.Candidates) == 0 || resp2.Candidates[0].Content == nil {
log.Exit("empty response from model in turn 2")
}
for _, part := range resp2.Candidates[0].Content.Parts {
if txt, ok := part.(genai.Text); ok {
fmt.Println(string(txt))
}
}
}
REST
# Turn 1: Initial request with Google Search (built-in) and getWeather (custom) tools enabled
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "What is the northernmost city in the United States? What'\''s the weather like there today?"
}]
}],
"tools": [{
"googleSearch": {}
}, {
"functionDeclarations": [{
"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"]
}
}]
}],
"toolConfig": {
"includeServerSideToolInvocations": true
}
}'
# Turn 2: Manually build history to circulate both tool and function context
# The following request assumes you have captured candidates[0].content from Turn 1 response,
# and extracted function_call.id for getWeather.
# Replace FUNCTION_CALL_ID and insert candidate content from turn 1.
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"contents": [
{
"role": "user",
"parts": [{"text": "What is the northernmost city in the United States? What'\''s the weather like there today?"}]
},
YOUR_CANDIDATE_CONTENT_FROM_TURN_1_RESPONSE,
{
"role": "user",
"parts": [{
"functionResponse": {
"name": "getWeather",
"id": "FUNCTION_CALL_ID",
"response": {"response": "Very cold. 22 degrees Fahrenheit."}
}
}]
}
],
"tools": [{
"googleSearch": {}
}, {
"functionDeclarations": [{
"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"]
}
}]
}],
"toolConfig": {
"includeServerSideToolInvocations": true
}
}'
यह कैसे काम करता है
Gemini 3 मॉडल, बिल्ट-इन और कस्टम टूल के कॉम्बिनेशन को इस्तेमाल करने के लिए, टूल कॉन्टेक्स्ट सर्कुलेशन का इस्तेमाल करते हैं. टूल कॉन्टेक्स्ट सर्कुलेशन की मदद से, बिल्ट-इन टूल के कॉन्टेक्स्ट को सेव किया जा सकता है और उसे दिखाया जा सकता है. साथ ही, इसे एक ही कॉल में, एक से दूसरी बारी में कस्टम टूल के साथ शेयर किया जा सकता है.
टूल कॉम्बिनेशन की सुविधा चालू करना
- टूल कॉन्टेक्स्ट सर्कुलेशन की सुविधा चालू करने के लिए, आपको
include_server_side_tool_invocationsफ़्लैग कोtrueपर सेट करना होगा. - कॉम्बिनेशन के व्यवहार को ट्रिगर करने के लिए,
function_declarationsको उन बिल्ट-इन टूल के साथ शामिल करें जिनका इस्तेमाल आपको करना है.- अगर आपने
function_declarationsको शामिल नहीं किया है, तब भी टूल कॉन्टेक्स्ट सर्कुलेशन, शामिल किए गए बिल्ट-इन टूल पर काम करेगा. हालांकि, इसके लिए फ़्लैग सेट होना चाहिए.
- अगर आपने
एपीआई, इन हिस्सों को दिखाता है
एक ही जवाब में, एपीआई, बिल्ट-इन टूल कॉल के लिए toolCall और toolResponse हिस्सों को दिखाता है. फ़ंक्शन (कस्टम टूल) कॉल के लिए, एपीआई, functionCall कॉल का हिस्सा दिखाता है. इसके जवाब में, उपयोगकर्ता अगली बारी में functionResponse का हिस्सा देता है.
toolCallऔरtoolResponse: एपीआई, इन हिस्सों को इसलिए दिखाता है, ताकि यह पता चल सके कि सर्वर साइड पर कौनसा टूल चल रहा है और अगली बारी के लिए, उसके नतीजे को सेव किया जा सके.functionCallऔरfunctionResponse: एपीआई, फ़ंक्शन कॉल को उपयोगकर्ता को भरने के लिए भेजता है. इसके बाद, उपयोगकर्ता, फ़ंक्शन के जवाब में नतीजा वापस भेजता है. ये हिस्से, Gemini API में सभी फ़ंक्शन कॉलिंग के लिए स्टैंडर्ड हैं. ये सिर्फ़ टूल कॉम्बिनेशन की सुविधा के लिए यूनीक नहीं हैं.- (सिर्फ़ कोड एक्ज़ीक्यूशन टूल)
executableCodeऔरcodeExecutionResult: कोड एक्ज़ीक्यूशन टूल का इस्तेमाल करते समय, एपीआई,functionCallऔरfunctionResponseके बजाय,executableCode(मॉडल से जनरेट किया गया कोड, जिसे एक्ज़ीक्यूट किया जाना है) औरcodeExecutionResult(एक्ज़ीक्यूटेबल कोड का नतीजा) दिखाता है.
कॉन्टेक्स्ट बनाए रखने और टूल कॉम्बिनेशन की सुविधा चालू करने के लिए, आपको हर बारी में मॉडल को सभी हिस्से वापस भेजने होंगे. इनमें शामिल सभी फ़ील्ड भी शामिल होने चाहिए.
दिखाए गए हिस्सों में ज़रूरी फ़ील्ड
एपीआई से दिखाए गए कुछ हिस्सों में, id,
tool_type, और thought_signature फ़ील्ड शामिल होंगे. ये फ़ील्ड, टूल कॉन्टेक्स्ट बनाए रखने के लिए ज़रूरी हैं. इसलिए, ये टूल कॉम्बिनेशन के लिए भी ज़रूरी हैं. आपको अपने अगले अनुरोधों में, जवाब में दिए गए सभी हिस्से वापस भेजने होंगे.
id: यह एक यूनीक आइडेंटिफ़ायर है, जो किसी कॉल को उसके जवाब से मैप करता है.idटूल कॉन्टेक्स्ट सर्कुलेशन के बावजूद, सभी फ़ंक्शन कॉल के जवाबों पर सेट होता है. आपको फ़ंक्शन के जवाब में वहीidदेना होगा जो एपीआई, फ़ंक्शन कॉल में देता है. बिल्ट-इन टूल, टूल कॉल और टूल रिस्पॉन्स के बीचidको अपने-आप शेयर करते हैं.- यह टूल से जुड़े सभी हिस्सों में मौजूद होता है:
toolCall,toolResponse,functionCall,functionResponse,executableCode,codeExecutionResult
- यह टूल से जुड़े सभी हिस्सों में मौजूद होता है:
tool_type: इससे यह पता चलता है कि कौनसा टूल इस्तेमाल किया जा रहा है. जैसे, बिल्ट-इन टूल या (उदाहरण के लिए,URL_CONTEXT) या फ़ंक्शन (उदाहरण के लिए,getWeather) का नाम.- यह
toolCallऔरtoolResponseहिस्सों में मौजूद होता है.
- यह
thought_signature: यह एपीआई से दिखाए गए हर हिस्से में एम्बेड किया गया, असल में एन्क्रिप्ट किया गया कॉन्टेक्स्ट होता है. थॉट सिग्नेचर के बिना, कॉन्टेक्स्ट को फिर से नहीं बनाया जा सकता. अगर आपने हर बारी में सभी हिस्सों के लिए थॉट सिग्नेचर नहीं दिखाए, तो मॉडल में गड़बड़ी होगी.- यह सभी हिस्सों में मौजूद होता है.
टूल के हिसाब से डेटा
कुछ बिल्ट-इन टूल, उपयोगकर्ता को दिखने वाले डेटा आर्ग्युमेंट दिखाते हैं. ये आर्ग्युमेंट, टूल के टाइप के हिसाब से अलग-अलग होते हैं.
| टूल | उपयोगकर्ता को दिखने वाले टूल कॉल आर्ग्युमेंट (अगर कोई हो) | उपयोगकर्ता को दिखने वाला टूल रिस्पॉन्स (अगर कोई हो) |
|---|---|---|
| GOOGLE_SEARCH | queries |
search_suggestions |
| GOOGLE_MAPS | queries |
placesgoogle_maps_widget_context_token |
| URL_CONTEXT | urlsवे यूआरएल जिन्हें ब्राउज़ किया जाना है |
urls_metadataretrieved_url: ब्राउज़ किए गए यूआरएलurl_retrieval_status: ब्राउज़ करने की स्थिति |
| FILE_SEARCH | कोई नहीं | कोई नहीं |
टूल कॉम्बिनेशन के अनुरोध के स्ट्रक्चर का उदाहरण
अनुरोध के इस स्ट्रक्चर में, प्रॉम्प्ट के अनुरोध का स्ट्रक्चर दिखाया गया है: "अमेरिका का सबसे उत्तरी शहर कौनसा है? वहां आज कैसा मौसम है?". इसमें तीन टूल को एक साथ इस्तेमाल किया गया है: Gemini के बिल्ट-इन टूल google_search और code_execution, और एक कस्टम फ़ंक्शन get_weather.
{
"model": "models/gemini-3-flash-preview",
"contents": [{
"parts": [{
"text": "What is the northernmost city in the United States? What's the weather like there today?"
}],
"role": "user"
}, {
"parts": [{
"thoughtSignature": "...",
"toolCall": {
"toolType": "GOOGLE_SEARCH_WEB",
"args": {
"queries": ["northernmost city in the United States"]
},
"id": "a7b3k9p2"
}
}, {
"thoughtSignature": "...",
"toolResponse": {
"toolType": "GOOGLE_SEARCH_WEB",
"response": {
"search_suggestions": "..."
},
"id": "a7b3k9p2"
}
}, {
"functionCall": {
"name": "getWeather",
"args": {
"city": "Utqiaġvik, Alaska"
},
"id": "m4q8z1v6"
},
"thoughtSignature": "..."
}],
"role": "model"
}, {
"parts": [{
"functionResponse": {
"name": "getWeather",
"response": {
"response": "Very cold. 22 degrees Fahrenheit."
},
"id": "m4q8z1v6"
}
}],
"role": "user"
}],
"tools": [{
"functionDeclarations": [{
"name": "getWeather"
}]
}, {
"googleSearch": {
}
}, {
"codeExecution": {
}
}],
"toolConfig": {
"includeServerSideToolInvocations": true
}
}
टोकन और कीमत
ध्यान दें कि अनुरोधों में toolCall और toolResponse हिस्सों को prompt_token_count में गिना जाता है. इंटरमीडिएट टूल के ये चरण अब दिखते हैं और आपको दिखाए जाते हैं. इसलिए, ये बातचीत के इतिहास का हिस्सा हैं. यह सिर्फ़
अनुरोधों के लिए लागू होता है, जवाबों के लिए नहीं.
Google Search टूल, इस नियम का अपवाद है. Google Search, क्वेरी के लेवल पर अपना कीमत मॉडल पहले से ही लागू करता है. इसलिए, टोकन के लिए दो बार शुल्क नहीं लिया जाता (कीमत वाला पेज देखें).
ज़्यादा जानकारी के लिए, टोकन वाला पेज पढ़ें.
सीमाएं
include_server_side_tool_invocationsफ़्लैग चालू होने पर, डिफ़ॉल्ट रूप सेVALIDATEDमोड (AUTOमोड काम नहीं करता) पर सेट होता हैgoogle_searchजैसे बिल्ट-इन टूल, जगह और मौजूदा समय की जानकारी पर निर्भर करते हैं. इसलिए, अगर आपकेsystem_instructionयाfunction_declaration.descriptionमें जगह और समय की जानकारी अलग-अलग है, तो टूल कॉम्बिनेशन की सुविधा शायद ठीक से काम न करे.
इन टूल पर पासकी का इस्तेमाल किया जा सकता है
सर्वर-साइड (बिल्ट-इन) टूल पर, टूल कॉन्टेक्स्ट सर्कुलेशन का स्टैंडर्ड तरीका लागू होता है. कोड एक्ज़ीक्यूशन भी सर्वर-साइड टूल है, लेकिन इसमें कॉन्टेक्स्ट सर्कुलेशन के लिए अपना बिल्ट-इन समाधान है. कंप्यूटर का इस्तेमाल और फ़ंक्शन कॉलिंग, क्लाइंट-साइड टूल हैं. इनमें भी कॉन्टेक्स्ट सर्कुलेशन के लिए बिल्ट-इन समाधान हैं.
| टूल | एक्ज़ीक्यूशन साइड | कॉन्टेक्स्ट सर्कुलेशन की सुविधा |
|---|---|---|
| Google Search | सर्वर-साइड | समर्थित |
| Google Maps | सर्वर-साइड | समर्थित |
| यूआरएल कॉन्टेक्स्ट | सर्वर-साइड | समर्थित |
| फ़ाइल सर्च | सर्वर-साइड | समर्थित |
| कोड एक्ज़ीक्यूशन | सर्वर-साइड | समर्थित (बिल्ट इन, executableCode और codeExecutionResult हिस्सों का इस्तेमाल करता है) |
| कंप्यूटर का इस्तेमाल | क्लाइंट-साइड | समर्थित (बिल्ट इन, functionCall और functionResponse हिस्सों का इस्तेमाल करता है) |
| कस्टम फ़ंक्शन | क्लाइंट-साइड | समर्थित (बिल्ट इन, functionCall और functionResponse हिस्सों का इस्तेमाल करता है) |
आगे क्या करना है
- Gemini API में फ़ंक्शन कॉलिंग के बारे में ज़्यादा जानें.
- इन टूल के बारे में जानें: