Gemini API में Managed Agents: एक हैंड्स-ऑन ट्यूटोरियल

Gemini API में Managed Agents की कीमत कितनी है?

Gemini Managed Agents की प्राइसिंग में कई घटक शामिल हैं, जिससे सटीक लागत का अनुमान देना मुश्किल हो सकता है। लागत चार मुख्य कारकों से प्रभावित होती है:

1. मॉडल उपयोग (Tokens): हमें आधारभूत Gemini मॉडल द्वारा प्रोसेस किए गए इनपुट और आउटपुट टोकन की संख्या के आधार पर चार्ज किया जाता है। ध्यान दें कि इसमें इंटरमीडिएट परिणामों में बने टोकन भी शामिल हैं। उदाहरण के लिए, यदि एजेंट रिपोर्ट बनाने के लिए एक Python स्क्रिप्ट जनरेट करता है, तो उस स्क्रिप्ट के लिए आवश्यक टोकन भी बिल किए जाते हैं।
2. इन्फ्रास्ट्रक्चर और प्लेटफ़ॉर्म शुल्क: Managed agents Google के एकीकृत वातावरण में चलते हैं, जिसमें एजेंट्स को मैनेज और डिप्लॉय करने के लिए प्लेटफ़ॉर्म टूल्स (जैसे Vertex AI Agent Builder) के उपयोग पर सेवा शुल्क शामिल है।
3. Context Caching: यदि एजेंट बार-बार एक ही डेटा का पुन: उपयोग करते हैं, तो managed agents context caching का उपयोग कर सकते हैं। यह आमतौर पर मानक टोकन प्राइसिंग की तुलना में महत्वपूर्ण लागत में कमी प्रदान करता है।
4. Grounding: यदि एजेंट Google Search या Google Maps जैसी Google ग्राउंड सेवाओं का उपयोग करता है, तो इनका बिल अलग से होता है—अक्सर कुछ मुफ्त अनुरोधों के कोटा के बाद प्रति 1,000 क्वेरी पर लागत (आमतौर पर लगभग $14/1,000 क्वेरी)। 

इस ट्यूटोरियल में, हम antigravity-preview-05-2026 एजेंट के ऊपर एक एजेंट बनाएंगे जो d द्वारा संचालित है Gemini 3.5 Flash। Token लागतें Gemini 3.5 Flash की निम्नलिखित हैं:

Gemini API में Managed Agents कैसे बनाएं

इस गाइड में, हम Gemini API और Python का उपयोग करके एक managed agent बनाएंगे। चूंकि managed agents हाल ही में जारी हुए हैं और वर्तमान में बीटा में हैं, ध्यान रखें कि कुछ इम्प्लीमेंटेशन विवरण बदल सकते हैं।

इस ट्यूटोरियल में लिखे गए सारे कोड इस GitHub रिपॉजिटरी में संग्रहीत हैं, जिसे हम डेटा एनालिस्ट एजेंट के साथ डेटा साझा करने के लिए भी उपयोग करेंगे।

API सेटअप

AI की बनाने के लिए, Google AI Studio पर जाएँ और ऊपर दाईं ओर “Create API Key” पर क्लिक करें।

API keys को किसी Google Cloud प्रोजेक्ट से जोड़ा जाना चाहिए। हम मौजूदा चुन सकते हैं या नया बना सकते हैं। यहाँ, मैंने gemini-managed-agents नाम का एक प्रोजेक्ट बनाया।

की बनाने के बाद, हम उसे कॉपी कर लेते हैं। फिर हम उस फ़ोल्डर में .env नाम की फाइल बनाते हैं जहाँ हम अपने एजेंट बनाएँगे, और उसे निम्न फ़ॉर्मैट में पेस्ट करते हैं:

GEMINI_API_KEY=<paste_your_api_key_here>

Google AI Studio बंद करने से पहले, हमें अभी बनाई गई API key पर बिलिंग सेटअप करनी होगी। इसके बिना, हमारे अनुरोध अस्वीकार कर दिए जाएँगे क्योंकि Google हमसे शुल्क नहीं ले पाएगा। बिलिंग सेटअप करने के लिए “Set up billing” बटन पर क्लिक करें।

Python वातावरण सेटअप

हम इस प्रोजेक्ट के लिए Python वातावरण सेट करने हेतु Anaconda का उपयोग करेंगे। Anaconda से वातावरण बनाने के लिए, यह कमांड उपयोग करें:

conda create --name gemini_agents python=3.12 -y

यह gemini_agents नाम का वातावरण बनाता है जो Python संस्करण 3.10 का उपयोग करता है। -y पैरामीटर वातावरण निर्माण के दौरान सभी प्रश्नों का उत्तर “हाँ” देने का शॉर्टकट है।

अगला कदम, हमें इसे सक्रिय करना है:

conda activate gemini_agents

अंत में, आवश्यक डिपेंडेंसियाँ इंस्टॉल करनी हैं। इस प्रकार:

pip install google-genai requests python-dotenv

Managed agent के साथ एक बुनियादी इंटरैक्शन बनाना

अब हमारे पास अपना पहला एजेंट चलाने के लिए सब कुछ सेट है। यह पहला एजेंट बहुत कुछ नहीं करेगा—यह केवल matplotlib इंस्टॉल करेगा और इंस्टॉल की गई वर्ज़न रिपोर्ट करेगा।

यहाँ स्टेप-बाय-स्टेप समझाया गया है कि हम एक managed agent के साथ कैसे इंटरैक्ट कर सकते हैं (पूरा कोड रिपॉजिटरी की simple_interaction.py स्क्रिप्ट में मौजूद है):

पहले, हम आवश्यक पैकेज इम्पोर्ट करते हैं और पहले बनाई गई .env फाइल से API key लोड करते हैं:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

इसके बाद, हम Gemini क्लाइंट को इनिशियलाइज़ करते हैं और बेस एजेंट, जिसका वर्तमान नाम antigravity-preview-05-2026 है, से matplotlib इंस्टॉल करने के लिए कहते हुए एक इंटरैक्शन बनाते हैं:

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

अंत में, हम status, environment_id और output_text प्रॉपर्टीज़ देखकर एजेंट का आउटपुट प्राप्त करते हैं:

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

परिणाम इस प्रकार है:

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

सैंडबॉक्स जीवनचक्र अवस्थाएँ

ऊपर के उदाहरण में, हमने managed agent इंटरैक्शन के वातावरण पहचानकर्ता को दिखाया:

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

यह मान महत्वपूर्ण है क्योंकि यह उस वातावरण का पहचानकर्ता दर्शाता है जहाँ एजेंट निष्पादित हुआ था। एजेंट इंटरैक्शन एक अल्पकालिक (ephemeral) वातावरण में संग्रहित होते हैं जिसे अंतिम गतिविधि के 7 दिनों तक बनाए रखा जाता है, उसके बाद हटा दिया जाता है।

नीचे का आरेख उस सैंडबॉक्स के जीवनचक्र को दर्शाता है जहाँ इंटरैक्शन के दौरान एजेंट निष्पादित होता है।

जब तक वातावरण डिलीट नहीं होता, हम उसके पहचानकर्ता का उपयोग करके उसे एक्सेस कर सकते हैं और आगे के इंटरैक्शन कर सकते हैं।

एकाधिक इंटरैक्शन करना

इस उदाहरण में, हम दिखाते हैं कि कई इंटरैक्शन कैसे किए जाएँ। पूरा कोड रिपॉजिटरी की multiple_interactions.py फाइल से लिया जा सकता है।

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

ध्यान दें कि दूसरे इंटरैक्शन में, हमने दो पैरामीटर जोड़े हैं:

• previous_interaction_id: पिछले इंटरैक्शन का पहचानकर्ता, ताकि एजेंट को वार्तालाप इतिहास का पता रहे।

• environment: वातावरण पहचानकर्ता ताकि एजेंट जान सके कि किस सैंडबॉक्स में निष्पादन करना है।

एजेंट के साथ फाइलें साझा करना

यदि हम एजेंट को डेटा की पहुंच नहीं दे सकते, तो हम डेटा एनालिस्ट एजेंट नहीं बना सकते। एजेंट के साथ डेटा साझा करने के कुछ तरीके हैं:

• Inline डेटा: फाइल की सामग्री को एक स्ट्रिंग में लोड करके इंटरैक्शन के दौरान भेजना।
• होस्टेड फाइल: डेटा को किसी पब्लिक URL पर होस्ट करना और एजेंट को डाउनलोड के लिए URL देना।
• GitHub रिपॉजिटरी: हम एजेंट को किसी पब्लिक GitHub रिपॉजिटरी का URL दे सकते हैं।
• Google Cloud Bucket: किसी Google Cloud Storage बकेट में फाइल होस्ट करना और प्रोजेक्ट को इस प्रकार कॉन्फ़िगर करना कि एजेंट को उस बकेट तक पहुंच हो।

हम इस लेख में सभी समाधान नहीं तलाशेंगे। हम दिखाएँगे कि लोकल फाइल को स्ट्रिंग में लोड करके inline डेटा कैसे भेजें और GitHub रिपॉजिटरी कैसे साझा करें। पहला तरीका छोटे लोकल फाइलों (प्रति फाइल 1 MB तक, और सभी फाइलों में कुल 2 MB की सीमा) के लिए आदर्श है, जबकि दूसरा बड़े फाइलों, जैसे डेटासेट्स, के लिए अधिक उपयुक्त है।

Inline डेटा साझा करना

यहाँ inline डेटा प्रदान करने का उदाहरण है (पूरा कोड inline_example.py में):

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

डेटा environment कॉन्फ़िगरेशन में sources पैरामीटर का उपयोग करके प्रदान किया जाता है। target यह परिभाषित करता है कि एजेंट के वातावरण में डेटा कहाँ सहेजा जाएगा। फाइलें workspace फोल्डर में होनी चाहिए। इस मामले में, यह number.txt नाम की फाइल होगी। 

content पैरामीटर फाइल की सामग्री देता है। inline सोर्स के लिए, यह केवल एक स्ट्रिंग होती है, जिसे यहाँ हम utils.py फाइल में मौजूद read_text_file() फ़ंक्शन से पढ़ते हैं।

GitHub रिपॉजिटरी साझा करना

बड़ी फाइलें साझा करने के लिए, हम GitHub रिपॉजिटरी URL दे सकते हैं। इस प्रकार:

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

ऊपर के उदाहरण में, URL https://github.com/fran-aubry/gemini-agents-tutorial वाली रिपॉजिटरी को एजेंट के कार्यक्षेत्र के अंदर repository नामक फोल्डर में क्लोन किया जाता है।

एजेंट के वातावरण को डाउनलोड करना

हमने पहले ही सीखा कि managed agents के साथ कैसे इंटरैक्ट करें और इन एजेंट्स को फाइलें कैसे दें। हमारा डेटा एनालिस्ट एजेंट बनाने के लिए, अंतिम बात जो सीखनी है, वह है एजेंट के वातावरण को कैसे डाउनलोड करें। यह आवश्यक है ताकि हम एजेंट द्वारा बनाए गए चार्ट्स और परिणामों तक पहुंच सकें।

प्रत्येक कार्यक्षेत्र निम्न URL से डाउनलोड किया जा सकता है:

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

जहाँ <env_id> को उस वातावरण के पहचानकर्ता से बदलना चाहिए जिसे हम डाउनलोड करना चाहते हैं।

यहाँ एक Python फ़ंक्शन है जो requests पैकेज का उपयोग करके पैकेज डाउनलोड करता है (यह फ़ंक्शन हमने बनाए utils.py फाइल का हिस्सा है):

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

एक डेटा एनालिस्ट एजेंट बनाना

इस खंड में, हम एक ऐसा एजेंट बनाना सीखेंगे जो डेटा विश्लेषण करता हो। एजेंट का परीक्षण करने के लिए, हम Kaggle से लिया गया यह Netflix डेटासेट उपयोग करेंगे, जो हमारी रिपॉजिटरी के data फोल्डर में भी संग्रहीत है।

पिछले सभी उदाहरणों में, हमने हमेशा बेस एजेंट antigravity-preview-05-2026 के साथ इंटरैक्ट किया। यहाँ हम पहले client.agents.create() फ़ंक्शन का उपयोग करके एक एजेंट बनाएँगे।

एजेंट बनाना

हम एजेंट इस प्रकार बना सकते हैं:

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

आइए प्रत्येक पैरामीटर को समझें:

• id: यह एजेंट का नाम परिभाषित करता है, इस मामले में data-analyst। हम client.interactions.create() मेथड में अब तक उपयोग किए जा रहे antigravity-preview-05-2026 के बजाय इसी पहचानकर्ता का उपयोग करेंगे। 

• base_agent: उपयोग किया जाने वाला बेस एजेंट। इसका अर्थ है कि हम antigravity-preview-05-2026 एजेंट के ऊपर एक एजेंट बना रहे हैं।

• base_environment: पहले की तरह, यह हमें एजेंट को फाइलें प्रदान करने देता है। हमने दो विशेष फाइलें दीं: .agents/AGENTS.md और .agents/skills/csv-aggregator/SKILL.md। इन फाइलों में हमने एजेंट के व्यवहार को परिभाषित किया है। AGENTS.md फाइल एजेंट के सामान्य व्यवहार को परिभाषित करती है, जबकि SKILL.md एजेंट के लिए एक विशिष्ट स्किल परिभाषित करती है। हमने एजेंट को रिपॉजिटरी भी दी ताकि उसे उन डेटा फाइलों तक पहुंच हो जिन्हें हम विश्लेषित करना चाहते हैं।

AGENTS.md को समझना

इस फाइल को एक सिस्टम प्रॉम्प्ट के रूप में समझा जा सकता है। यह एजेंट के लिए हमारा प्रमुख निर्देश-पत्र है। हमें इसमें एजेंट की विशिष्ट भूमिका, उसके मुख्य लक्ष्य, और काम करते समय उसे पालन करने वाली सीमाएँ स्पष्ट रूप से परिभाषित करनी चाहिए। 

यह वह सर्वोत्तम स्थान भी है जहाँ हम किसी भी विशिष्ट टूल्स या डेटा सोर्स की सूची दें जिन तक एजेंट को पहुंच की अनुमति है, और यह भी बताएं कि हम उससे कैसे संचार करना या कार्यों को संभालना चाहते हैं—इसके उदाहरण शामिल करें। 

इन निर्देशों को सरल और सुव्यवस्थित रखकर, हम एजेंट को ठीक-ठीक समझने में मदद करते हैं कि उसे कैसे व्यवहार करना है और हम उससे किस प्रकार के परिणामों की अपेक्षा करते हैं।

एजेंट के वातावरण में फाइल का स्थान .agents/AGENTS.md होना चाहिए।

SKILL.md को समझना

स्किल फाइलें एजेंट को विशिष्ट कौशलों से लैस करने के लिए उपयोग की जाती हैं। एक एजेंट के पास कई स्किल हो सकती हैं, और हर स्किल का विवरण .agents/skills/<skill_name>/SKILL.md में स्थित SKILL.md फाइल में होना चाहिए, जहाँ <skill_name> को स्किल के नाम से बदलें।

एक स्किल फाइल की संरचना इस प्रकार होनी चाहिए:

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

इसे उदाहरण से समझाने के लिए, हमने data-analyst एजेंट को csv-aggregator नामक स्किल से लैस किया है, जिसे यहाँ परिभाषित किया गया है। यह स्किल तब उपयोग होती है जब हम किसी CSV की पंक्तियों को किसी कॉलम के आधार पर समूहित करना चाहते हैं और किसी अन्य कॉलम को जोड़ना चाहते हैं। 

Netflix डेटासेट के मामले में, यदि हम यह जानना चाहते हैं कि किन शैलियों (genres) के शोज़ सबसे अधिक देखे गए, तो हम पंक्तियों को Genre के आधार पर समूहित करना चाहेंगे और Viewership कॉलम के मानों को जोड़ना चाहेंगे। यह स्किल फाइल एजेंट को यह कार्य कैसे करना है, समझाती है।

एजेंट लोड करना

क्योंकि एजेंट पर्सिस्टेंट होते हैं, यदि हम एजेंट निर्माण दोबारा चलाने की कोशिश करेंगे, तो हमें एक त्रुटि मिलेगी। इसी कारण, हमने utils.py फाइल में load_or_create_agent() फ़ंक्शन बनाया। यह फ़ंक्शन एजेंट बनाने की कोशिश करेगा और यदि वह मौजूद है, तो client.agents.load() फ़ंक्शन का उपयोग करके उसे लोड करेगा।

सब कुछ साथ लाना

अब जब हमारे पास एक डेटा एनालिस्ट एजेंट है, तो समय है कि Netflix के genres का विश्लेषण करने के लिए इसे परखा जाए। 

हम पहले की तरह लाइब्रेरी इम्पोर्ट करके, API key लोड करके और क्लाइंट को इनिशियलाइज़ करके शुरू करते हैं:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

फिर हम utils.load_or_create_agent() फ़ंक्शन का उपयोग करके data-analyst एजेंट बनाते (या यदि यह पहली बार नहीं है, तो लोड करते) हैं:

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

इसके बाद हम पहले की तरह एजेंट के साथ इंटरैक्ट कर सकते हैं। केवल अंतर यह है कि अब agent पैरामीटर में हम antigravity-preview-05-2026 के बजाय अपने एजेंट को प्रदान करते हैं।

हम एजेंट से matplotlib पैकेज इंस्टॉल करने के लिए कहना शुरू करते हैं:

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

ध्यान दें कि चूँकि वातावरण पहले से एजेंट स्तर पर कॉन्फ़िगर किया गया था, अब हमें फाइलें प्रदान करने की आवश्यकता नहीं है, इसलिए हम केवल स्ट्रिंग ”remote” देते हैं।

अगले चरण में, हम इसे csv-aggregator टूल का उपयोग करके Netflix डेटा को genres के अनुसार विश्लेषित करने के लिए कहते हैं ताकि यह देखा जा सके कि सबसे अधिक देखे जाने वाले genres कौन से हैं:

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

ध्यान दें कि हम पिछले इंटरैक्शन के वातावरण के पहचानकर्ता को प्रदान करते हैं ताकि एजेंट उसी पर आगे काम कर सके।

अंत में, हम एजेंट से genres.py स्क्रिप्ट चलाकर डेटा को प्लॉट करने के लिए कहते हैं, जो पिछले चरण में बनाई गई थी (SKILL.md फाइल एजेंट को यह स्क्रिप्ट बनाने का निर्देश देती है):

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

इस इंटरैक्शन के बाद, प्लॉट बन जाना चाहिए। हम वातावरण डाउनलोड करके इसे लोकली प्राप्त कर सकते हैं:

utils.download_env(inter3.environment_id)

परिणाम इस प्रकार है:

एजेंट इंटरैक्शन का पूरा कोड analyze_netflix_genres.py में पाया जा सकता है।

निष्कर्ष

एक ही API कॉल से जटिल एजेंट बनाना, बिना सैंडबॉक्स तैयार करने हेतु जटिल क्लाउड कंप्यूट इन्फ्रास्ट्रक्चर पर निर्भर हुए, अत्यंत शक्तिशाली है। यह क्षमता ऐसे सशक्त एजेंट बनाना बहुत आसान कर देती है, जिनके निष्पादन वातावरण की चिंता करने की ज़रूरत नहीं पड़ती।

इस ट्यूटोरियल में, हमने Gemini Managed Agents की बुनियादी बातें कवर कीं, लेकिन वास्तव में बहुत जटिल एजेंट नहीं बनाए। मैं आपको प्रोत्साहित करता हूँ कि आप और गहराई में जाएँ और इस नींव पर आगे निर्माण करते रहें ताकि आप अपनी कौशल को निखार सकें।