पहले से मौजूद टूल और फ़ंक्शन कॉलिंग को एक साथ इस्तेमाल करना

Gemini में, पहले से मौजूद टूल (जैसे, google_search) और फ़ंक्शन कॉल ( इन्हें कस्टम टूल भी कहा जाता है) को एक ही इंटरैक्शन में इस्तेमाल किया जा सकता है. इसके लिए, टूल कॉल के कॉन्टेक्स्ट के इतिहास को सेव और दिखाया जाता है. पहले से मौजूद और कस्टम टूल के कॉम्बिनेशन की मदद से, एजेंटिक वर्कफ़्लो बनाए जा सकते हैं. इनमें, उदाहरण के लिए, मॉडल आपकी खास कारोबार की लॉजिक को कॉल करने से पहले, वेब पर मौजूद रीयल-टाइम डेटा के आधार पर खुद को ग्राउंड कर सकता है.

यहां एक उदाहरण दिया गया है. इसमें, पहले से मौजूद और कस्टम टूल के कॉम्बिनेशन को google_search और कस्टम फ़ंक्शन getWeather के साथ इस्तेमाल किया गया है:

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

getWeather = {
    "type": "function",
    "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"],
    },
}

# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"type": "google_search"},
        getWeather,
    ],
)

# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} with args: {step.arguments}")
        # In a real application, you would execute the function here
        # and provide the result back to the model.

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const getWeather = {
    type: "function",
    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"]
    }
};

// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { type: "google_search" },
        getWeather,
    ],
});

// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
    if (step.type === "function_call") {
        console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
        // In a real application, you would execute the function here
        // and provide the result back to the model.
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
  "model": "gemini-3.5-flash",
  "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
  "tools": [
    { "type": "google_search" },
    {
      "type": "function",
      "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"]
      }
    }
  ]
}'

यह कैसे काम करता है

Gemini 3 मॉडल, पहले से मौजूद और कस्टम टूल के कॉम्बिनेशन को इस्तेमाल करने के लिए, टूल कॉन्टेक्स्ट सर्कुलेशन का इस्तेमाल करते हैं. टूल कॉन्टेक्स्ट सर्कुलेशन की मदद से, पहले से मौजूद टूल के कॉन्टेक्स्ट को सेव और दिखाया जा सकता है. साथ ही, इसे एक ही इंटरैक्शन में कस्टम टूल के साथ शेयर किया जा सकता है.

टूल कॉम्बिनेशन की सुविधा चालू करना

  • कॉम्बिनेशन के व्यवहार को ट्रिगर करने के लिए, function_declarations को उन पहले से मौजूद टूल के साथ शामिल करें जिनका आपको इस्तेमाल करना है, along

एपीआई, चरण दिखाता है

इंटरैक्शन के जवाब में, एपीआई, पहले से मौजूद टूल कॉल और फ़ंक्शन (कस्टम टूल) कॉल के लिए अलग-अलग चरण दिखाता है:

  • पहले से मौजूद टूल के चरण: एपीआई इन्हें अपने-आप मैनेज करता है. साथ ही, यह हर चरण में कॉन्टेक्स्ट को सेव रखता है.
  • फ़ंक्शन कॉल के चरण: एपीआई, आपके कस्टम फ़ंक्शन के लिए function_call चरण दिखाता है. आपको फ़ंक्शन को लागू करना होता है और उसका नतीजा वापस देना होता है.

जवाब में मिले चरणों में ज़रूरी फ़ील्ड

जवाब में मिले चरणों में मौजूद कुछ फ़ील्ड, टूल के कॉन्टेक्स्ट को बनाए रखने और टूल के कॉम्बिनेशन को इस्तेमाल करने के लिए ज़रूरी होते हैं:

  • id: यह function_call और function_response चरणों में मौजूद होता है. यह एक यूनीक आइडेंटिफ़ायर होता है, जो किसी कॉल को उसके जवाब से मैप करता है.
  • signature: यह thought चरणों के साथ-साथ, Gemini 3 या इसके बाद के मॉडल के लिए, सभी टूल कॉल (जैसे, function_call) और नतीजे (जैसे, function_response) चरणों में मौजूद होता है. एनक्रिप्ट किया गया यह कॉन्टेक्स्ट, इंटरैक्शन के दौरान टूल कॉन्टेक्स्ट सर्कुलेशन की सुविधा चालू करता है.

इन फ़ील्ड को मैनेज करना:

  • स्टेटफ़ुल मोड (सुझाया गया): previous_interaction_id का इस्तेमाल करने पर, सर्वर, id और signature दोनों फ़ील्ड को अपने-आप हैंडल करता है.
  • स्टेटलेस मोड: बातचीत के इतिहास को मैन्युअल तरीके से मैनेज करते समय, आपको यह पक्का करना होगा कि असली होने की पुष्टि करने और कॉन्टेक्स्ट को बनाए रखने के लिए, बाद के अनुरोधों में मॉडल को id और signature दोनों फ़ील्ड पास किए जाएं. अगर आपने जवाब के पूरे ऑब्जेक्ट को इतिहास में पास किया है, तो आधिकारिक SDK, इसे अपने-आप हैंडल करते हैं.

टूल के हिसाब से डेटा

कुछ पहले से मौजूद टूल, उपयोगकर्ता को दिखने वाले डेटा आर्ग्युमेंट दिखाते हैं. ये आर्ग्युमेंट, टूल के टाइप के हिसाब से अलग-अलग होते हैं.

टूल उपयोगकर्ता को दिखने वाले टूल कॉल आर्ग्युमेंट (अगर कोई हो) उपयोगकर्ता को दिखने वाला टूल रिस्पॉन्स (अगर कोई हो)
google_search queries search_suggestions
google_maps queries places
google_maps_widget_context_token
url_context urls
URLs to be browsed		 status: Browse status
retrieved_url: URLs browsed
file_search कोई नहीं कोई नहीं

टोकन और कीमत

ध्यान दें कि अनुरोधों में, पहले से मौजूद टूल कॉल के हिस्सों को prompt_token_count में गिना जाता है. इंटरमीडिएट टूल के ये चरण अब आपको दिखते हैं और आपको वापस मिलते हैं. इसलिए, ये बातचीत के इतिहास का हिस्सा होते हैं. यह सिर्फ़ अनुरोधों के लिए लागू होता है, जवाबों के लिए नहीं.

Google Search टूल, इस नियम का अपवाद है. Google Search, क्वेरी के लेवल पर अपना कीमत मॉडल पहले से ही लागू करता है. इसलिए, टोकन के लिए दो बार शुल्क नहीं लिया जाता (कीमत वाला पेज देखें).

ज़्यादा जानकारी के लिए, टोकन वाला पेज पढ़ें.

सीमाएं

  • टूल कॉन्टेक्स्ट सर्कुलेशन की सुविधा चालू होने पर, डिफ़ॉल्ट रूप से validated मोड का इस्तेमाल किया जाता है. auto मोड मौजूद नहीं है.
  • google_search जैसे पहले से मौजूद टूल, जगह और मौजूदा समय की जानकारी पर निर्भर करते हैं. इसलिए, अगर आपके system_instruction या function_declaration.description में जगह और समय की जानकारी में कोई अंतर है, तो टूल कॉम्बिनेशन की सुविधा शायद ठीक से काम न करे.

इन टूल पर पासकी का इस्तेमाल किया जा सकता है

सर्वर-साइड (पहले से मौजूद) टूल पर, टूल कॉन्टेक्स्ट सर्कुलेशन का स्टैंडर्ड तरीका लागू होता है. Code Execution भी एक सर्वर-साइड टूल है. हालांकि, इसमें कॉन्टेक्स्ट सर्कुलेशन के लिए, पहले से मौजूद अपना समाधान है. Computer Use और फ़ंक्शन कॉल, क्लाइंट-साइड टूल हैं. इनमें भी कॉन्टेक्स्ट सर्कुलेशन के लिए, पहले से मौजूद समाधान हैं.

टूल निष्पादन साइड कॉन्टेक्स्ट सर्कुलेशन की सुविधा
Google Search सर्वर-साइड समर्थित
Google Maps सर्वर-साइड समर्थित
URL Context सर्वर-साइड समर्थित
File Search सर्वर-साइड समर्थित
Code Execution सर्वर-साइड समर्थित (पहले से मौजूद, code_execution और code_execution_result चरणों का इस्तेमाल करता है)
Computer Use क्लाइंट-साइड समर्थित (पहले से मौजूद, function_call और function_response चरणों का इस्तेमाल करता है)
पसंद के मुताबिक फ़ंक्शन क्लाइंट-साइड समर्थित (पहले से मौजूद, function_call और function_response चरणों का इस्तेमाल करता है)

आगे क्या करना है