Gemini API की मदद से, एजेंट बनाने और मैनेज करने की सुविधा का इस्तेमाल करके, रोज़ाना टेक्नोलॉजी से जुड़ी जानकारी देने वाला एजेंट बनाना

1. खास जानकारी

एआई और टेक्नोलॉजी के क्षेत्र में, इतनी तेज़ी से बदलाव हो रहे हैं कि कोई भी व्यक्ति इन पर नज़र नहीं रख सकता. नए मॉडल, पेपर, और प्रॉडक्ट रोज़ाना रिलीज़ होते हैं. डाइजेस्ट एजेंट, आज की मुख्य खबरें फ़ेच करता है, कम शब्दों में जानकारी देता है, और हर सुबह एक PDF जनरेट करता है. इससे इस समस्या को हल किया जा सकता है. हालांकि, इसे बनाने के लिए एक फ़्रेमवर्क चुनना, Python में टूल तय करना, ऑर्केस्ट्रेशन लूप लिखना, कंटेनर को पैकेज करना, और Cloud Run पर डिप्लॉय करना पड़ता था. यह सब तब हुआ, जब एजेंट ने एक भी वेब का अनुरोध नहीं किया था.

Gemini API से एजेंट बनाने और मैनेज करने की सुविधा, इस समीकरण को बदल देती है. आपको दो मार्कडाउन कॉन्फ़िगरेशन फ़ाइलें और पहले से बनी रेंडरर स्क्रिप्ट लिखनी होती है. इसके बाद, एक एपीआई कॉल करना होता है. इससे Ubuntu का सैंडबॉक्स बूट होता है, वेब ब्राउज़ करता है, आपकी खास जानकारी लिखता है, और एक PDF जनरेट करता है. कोई कंटेनर नहीं. कोई डिप्लॉयमेंट नहीं है. ऑर्केस्ट्रेशन कोड नहीं होता.

इस कोडलैब में, आपको ठीक वैसा ही एजेंट बनाना है. इसमें, एक-एक करके हर कॉन्सेप्ट को समझाया गया है. जैसे, खाली फ़ंक्शन से लेकर रोज़ाना डाइजेस्ट करने वाले फ़ंक्शन तक.

आपको क्या बनाना है

• Linux सैंडबॉक्स में मैनेज किया गया पहला एजेंट बनाना और उसे चलाना
• एडिटोरियल वॉइस, वेब सोर्स, और PDF से जुड़ी स्किल के साथ एजेंट को पसंद के मुताबिक बनाएं
• डिस्ट्रक्टिव कमांड को चलने से पहले रोकने के लिए, सुरक्षा हुक जोड़ना
• एजेंट की जनरेट की गई PDF फ़ाइल डाउनलोड करना
• वेब से फिर से जानकारी लिए बिना, सिलसिलेवार बातचीत में डाइजेस्ट को बेहतर बनाना
• एजेंट कॉन्फ़िगरेशन को सेव करें और आने वाले समय में आईडी के ज़रिए इसे लागू करें
• Gmail API के ज़रिए, डाइजेस्ट को अपने इनबॉक्स में भेजें
• एजेंट को हर दिन अपने-आप चलने और रिपोर्ट भेजने के लिए शेड्यूल करना

आपको किन चीज़ों की ज़रूरत होगी

• Python 3.10+
• Gemini API पासकोड: aistudio.google.com/api-keys (इसमें मुफ़्त टियर शामिल है; बिना किसी रुकावट के इस्तेमाल करने के लिए, बिलिंग की सुविधा चालू करने का सुझाव दिया जाता है)

2. Gemini API पर मैनेज किए गए एजेंट क्या होते हैं?

एआई सिस्टम के तीन लेवल

कोड के बारे में जानने से पहले, यहां बताया गया है कि एजेंट बनाने और मैनेज करने की सुविधा, दो विकल्पों के मुकाबले कहां फ़िट होती है:

लेवल	यह क्या है	इन्फ़्रास्ट्रक्चर को कौन मैनेज करता है?
स्टैंडर्ड एलएलएम	आपके प्रॉम्प्ट के आधार पर, यह टेक्स्ट के रूप में जवाब देता है. कोई हाथ नहीं, कोई मेमोरी नहीं, कोई इंटरनेट नहीं.	लागू नहीं: यह खुद से कुछ नहीं कर सकता
सेल्फ़-होस्ट किया गया एजेंट	ADK/LangChain/AutoGen + Docker + टूल + मेमोरी को एक साथ जोड़ें.	आप: सभी (या Agent Engine जैसे मैनेज किए गए प्लैटफ़ॉर्म)
मैनेज किया गया एजेंट	आपको इसे एक लक्ष्य देना होता है. Google, एक सुरक्षित सैंडबॉक्स उपलब्ध कराता है. यह एजेंट, कोड लिखता है, उसे चलाता है, गड़बड़ियां पढ़ता है, वेब पर खोज करता है, और अपने-आप बग ठीक करता है.	Google: सभी

यह कोडलैब, तीसरी लाइन के बारे में है. आपको टास्क और कॉन्फ़िगरेशन फ़ाइलें देनी होंगी. बाकी का काम Google करता है.

ADK + Cloud Run की मदद से क्या बनाया जा सकता है

वेब ब्राउज़ करने, Python चलाने, और PDF जनरेट करने वाला न्यूज़ डाइजेस्ट एजेंट बनाने के लिए, आपको ADK + Cloud Run के साथ इन सभी चीज़ों की ज़रूरत होगी:

# agent.py: define tools and wire up the agent
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution

agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,          # your editorial voice and rules
    tools=[google_search, built_in_code_execution],
)

# app.py: serve the agent over HTTP
from google.adk.runners import FastApiRunner
runner = FastApiRunner(agent=agent)
app = runner.app

# pdf_tool.py: custom tool, install reportlab, render PDF
# scraper.py: custom tool, fetch each news source
# streaming.py: wire agent events to your SSE endpoint

# Dockerfile: package everything
FROM python:3.12
COPY . /app
RUN pip install google-adk reportlab requests
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

# Deploy to Cloud Run
gcloud run deploy digest-agent \
  --image gcr.io/your-project/digest-agent \
  --set-secrets GEMINI_API_KEY=gemini-key:latest \
  --memory 2Gi

ऐसा तब होता है, जब एजेंट को पहली बार चलाया जाता है. आपके पास अब भी सैंडबॉक्स आइसोलेशन का मालिकाना हक है. इसलिए, एजेंट आपके सर्वर को नुकसान नहीं पहुंचा सकता. साथ ही, आपके पास पैकेज इंस्टॉल करने, टूल कॉल के बीच स्टेट मैनेजमेंट करने, और क्लाइंट को इवेंट भेजने के लिए स्ट्रीमिंग इन्फ़्रास्ट्रक्चर का मालिकाना हक है.

एजेंट बनाने और मैनेज करने की सुविधा, इसे किस सुविधा से बदलती है

from google import genai
client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Generate the digest.",
    stream=True,
    environment={
        "type": "remote",
        "sources": [          # your config files, mounted at startup
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

ADK + Cloud Run के लिए ज़रूरी शर्तें	एजेंट बनाने और मैनेज करने की सुविधा आपके लिए क्या-क्या करती है
कंटेनर इमेज + Dockerfile + CI/CD	पूरी तरह से मैनेज किया गया Ubuntu सैंडबॉक्स (Python 3.12, Node 22, 4 सीपीयू / 16 जीबी रैम)
Cloud Run डिप्लॉयमेंट + स्केलिंग	हर इंटरैक्शन के लिए उपलब्ध कराया जाता है. सात दिनों तक कोई गतिविधि न होने पर, यह अपने-आप खत्म हो जाता है
सैंडबॉक्स आइसोलेशन	हर इंटरैक्शन के लिए अलग-अलग
PDF टूल को पसंद के मुताबिक बनाएं + pip install	एजेंट, सैंडबॉक्स में पैकेज इंस्टॉल करता है
एसएसई स्ट्रीमिंग इन्फ़्रास्ट्रक्चर	stream=True, इवेंट का इटरेबल ऑब्जेक्ट दिखाता है
Python में टूल की परिभाषाएं	इन टूल को पहले से ही शामिल किया गया है: वेब ब्राउज़ करना, कोड एक्ज़ीक्यूट करना, फ़ाइल सिस्टम
टूल कॉल के बीच स्टेट मैनेजमेंट	इसे एजेंट के लॉजिक वाले लूप में शामिल किया गया है

कॉन्फ़िगरेशन फ़ाइलें (AGENTS.md, SKILL.md, पहले से बनी स्क्रिप्ट) लिखी जाती हैं और एक एपीआई कॉल किया जाता है. बाकी का काम Google करता है.

सैंडबॉक्स कैसे काम करता है

interactions.create() call
        │
        ▼
Google provisions Ubuntu sandbox (Python 3.12, Node 22, 4 CPU / 16 GB RAM)
        │
        ▼
Agent reasoning loop:
  plan → fetch URLs → run Python → write files → reason → repeat
        │
        ▼
Events stream back in real time: tool calls, text chunks, completion
        │
        ▼
interaction.completed → environment_id + interaction_id

सैंडबॉक्स, सात दिनों तक इस्तेमाल न किए जाने पर भी बना रहता है. environment_id की मदद से, इसे फिर से शुरू किया जा सकता है. इससे आउटपुट को बेहतर बनाया जा सकता है, फ़ॉलो-अप टास्क पूरे किए जा सकते हैं या इसे सेव किए गए नाम वाले एजेंट में फ़ोर्क किया जा सकता है.

3. सेट करें

पहला विकल्प: Cloud Shell (सुझाया गया)

इस कोडलैब को Google Cloud Shell में खोलने के लिए, यहां दिए गए बटन पर क्लिक करें. सभी डिपेंडेंसी पहले से इंस्टॉल हैं.

Cloud Shell में खोलें

विकल्प B: लोकल सेटअप

git clone https://github.com/Saoussen-CH/tech-digest-managed-agent.git
cd tech-digest-managed-agent

अगर ज़रूरी हो, तो uv इंस्टॉल करें:

curl -LsSf https://astral.sh/uv/install.sh | sh

एपीआई पासकोड कॉन्फ़िगर करना

cp .env.example .env
cloudshell edit .env

अपनी कुंजी सेट करें:

GEMINI_API_KEY=your-key-here

डिपेंडेंसी इंस्टॉल करना

uv sync

4. एजेंट से अपनी पहली कॉल करना

स्टार्टर फ़ाइल खोलें

cloudshell edit run_digest.py

लोकल सेटअप: अपनी पसंद के एडिटर में run_digest.py खोलें.

run_digest() को अभी एक TODO भरना है और अगले चरण के लिए तीन और TODO भरने हैं. ऊपर दो मददगारों की जानकारी पहले से भरी गई है:

• load_source(path): स्क्रिप्ट के हिसाब से, .agents/ से फ़ाइल पढ़ता है. इसका इस्तेमाल अगले चरण में, संपादकीय नज़रिया, PDF प्लेबुक, और रेंडरर को सैंडबॉक्स में माउंट करने के लिए किया जाएगा.
• run_stream(stream): यह इवेंट स्ट्रीम को प्रोसेस करता है और (environment_id, interaction_id) दिखाता है. आपको इवेंट लूप खुद लिखने की ज़रूरत नहीं है.

क्या जोड़ना है

TODO 1: pass को इससे बदलें (अभी TODO 3 और 4 को अनदेखा करें; ये अगले चरण के लिए हैं):

    from google import genai
    client = genai.Client()

    stream = client.interactions.create(
        agent=BASE_AGENT,
        agent_config={"type": "antigravity", "model": "gemini-3.7-flash"},
        input="Fetch the Hacker News front page and list the top 5 stories.",
        stream=True,
        environment="remote",
    )

    environment_id, interaction_id = run_stream(stream)
    print(f"\nDone. environment_id={environment_id}")

हर हिस्से का क्या काम है

genai.Client() एनवायरमेंट से GEMINI_API_KEY पढ़ता है. बाकी सभी काम इस क्लाइंट के ज़रिए किए जाते हैं.

interactions.create() मुख्य कॉल है. ये चार पैरामीटर, इस सुविधा को काम करने में मदद करते हैं:

• agent=BASE_AGENT: यह Antigravity एजेंट (antigravity-preview-05-2026) को चुनता है. यह अलग-अलग कामों के लिए इस्तेमाल की जाने वाली मशीन है जिसे डिफ़ॉल्ट रूप से Gemini 3.7 Flash की मदद से मैनेज किया जाता है. agent_config (विकल्प: gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite) का इस्तेमाल करके, मॉडल को कॉन्फ़िगर किया जा सकता है. इसमें तीन टूल पहले से मौजूद होते हैं. ये डिफ़ॉल्ट रूप से चालू होते हैं: code_execution (Bash, Python, Node.js चलाएं), google_search, और url_context (वेब पेज फ़ेच और पढ़ें). environment पैरामीटर पास करने पर, फ़ाइल सिस्टम टूल (read_file, write_file, list_files) अपने-आप चालू हो जाते हैं. एक कॉल, पूरी तरह से मैनेज किए गए Ubuntu एनवायरमेंट को उपलब्ध कराता है. इसमें Python 3.12, Node.js 22, git, pip, और curl पहले से इंस्टॉल होते हैं. बनाने के लिए कोई कंटेनर नहीं है और चलाने के लिए कोई डिप्लॉयमेंट नहीं है.
• input: इस रन के लिए टास्क. इस वीडियो में दिखाया गया है कि एजेंट, Hacker News को ब्राउज़ करता है और नतीजों के बारे में जानकारी देता है.
• environment="remote": इस इंटरैक्शन के लिए, नया क्लाउड सैंडबॉक्स उपलब्ध कराता है.
• stream=True: यह ब्लॉक करने के बजाय, इवेंट का एक इटरेबल दिखाता है. इसके बिना, कॉल 30 से 90 सेकंड तक इंतज़ार करता है और सभी आउटपुट को एक साथ interaction.output_text के तौर पर दिखाता है. स्ट्रीमिंग की सुविधा की मदद से, एजेंट के जवाब की वजह देखी जा सकती है और जवाब मिलते ही कार्रवाई की जा सकती है. यहां स्ट्रीमिंग कोई ऐडवांस सुविधा नहीं है: यह सही डिफ़ॉल्ट है, क्योंकि 90 सेकंड का ब्लैक बॉक्स आपको यह सिग्नल नहीं देता कि एजेंट काम कर रहा है या अटक गया है.

environment_id, सैंडबॉक्स का हैंडल है. interaction.completed के बाद, सैंडबॉक्स बंद नहीं होता है. यह सात दिनों तक चालू रहता है. environment_id पर क्लिक करके, आपको वापस उसी पेज पर ले जाया जाएगा. इसे दूसरे interactions.create() कॉल पर पास करें. इसके बाद, एजेंट उसी फ़ाइल सिस्टम पर काम करना जारी रखता है. साथ ही, उसके पास वही फ़ाइलें और इंस्टॉल किए गए पैकेज होते हैं जो पहले थे. अगले चरण में, इसका इस्तेमाल एजेंट को फिर से चलाए बिना PDF डाउनलोड करने के लिए किया जाता है. इसके बाद वाले चरण में, इसका इस्तेमाल बातचीत जारी रखने के लिए किया जाता है.

interaction_id, बातचीत के उस टर्न का हैंडल है जो अभी पूरा हुआ है. इसे अगली कॉल में previous_interaction_id के तौर पर पास करें. इससे एजेंट को यह याद रहेगा कि इस बातचीत में क्या कहा गया और क्या किया गया.

पुष्टि करें

uv run python run_digest.py

एजेंट के काम करने के दौरान, आपको लाइव आउटपुट दिखेगा:

[agent started]
  [tool] run_code
Here are the top 5 stories currently on the Hacker News front page, retrieved via the official Hacker News API:

1. **Qwen 3.6 27B is the sweet spot for local development** (471 points)
2. **.self: A new top-level domain designed to support self-hosting** (116 points)
...
Done. environment_id=e3de58774073f75a6ef42924c6ce2e88

एपीआई, environment="remote" के साथ भी असली environment_id दिखाता है. सैंडबॉक्स चल गया. इसमें कॉन्फ़िगरेशन मौजूद नहीं है: न तो आवाज़ है, न कोई स्किल है, और न ही कोई PDF जनरेटर है. एजेंट ने सिर्फ़ कहानियों को टेक्स्ट के तौर पर प्रिंट किया और बंद कर दिया. अगले चरण में, उन्हें जोड़ा जाता है.

आउटपुट की हर लाइन, run_stream() के किसी इवेंट से मेल खाती है:

step.type	यह क्या है	run_stream() प्रिंट क्या करता है
"url_context_call"	यूआरएल फ़ेच करने वाला एजेंट	[tool] url_context (https://...)
"code_execution_call"	सैंडबॉक्स में कोड चलाने वाला एजेंट	[tool] run_code
"google_search_call"	एजेंट वेब पर खोज कर रहा है	[tool] google_search
"function_call"	फ़ाइल टूल और अन्य	[tool] read_file (/workspace/...)
step.delta कहां delta.type == "text"	एजेंट का जवाब टाइप करना	को सीधे तौर पर stdout पर स्ट्रीम किया जाता है

5. एजेंट को पसंद के मुताबिक बनाना

एजेंट को कोई निर्देश नहीं दिया गया था: न तो आवाज़, न कोई स्किल, और न ही PDF जनरेट करने की सुविधा. इस चरण में, .agents/ से कॉन्फ़िगरेशन फ़ाइलें लोड की जाती हैं और उन्हें सैंडबॉक्स में माउंट किया जाता है.

कस्टम एजेंट बनाने का यह सबसे तेज़ तरीका है. आपने इस रन के लिए, Antigravity एजेंट को पसंद के मुताबिक बनाया है. हालांकि, आपने कुछ भी रजिस्टर नहीं किया है. अगले चरण में, इस कॉन्फ़िगरेशन को किसी नाम वाले एजेंट में हमेशा के लिए शामिल करने का तरीका बताया गया है, ताकि आपको सोर्स को फिर से पास न करना पड़े.

क्या बदलाव करना है

run_digest.py में चार बदलाव करें:

TODO 2: load_source() के नीचे, मॉड्यूल-लेवल के तीन कॉन्स्टेंट जोड़ें. ये run_digest() के बाहर, फ़ाइल में सबसे ऊपर मौजूद होते हैं:

AGENTS_MD       = load_source(".agents/AGENTS.md")
SKILL_MD        = load_source(".agents/skills/digest-pdf/SKILL.md")
GENERATE_PDF_PY = load_source(".agents/skills/digest-pdf/scripts/generate_pdf.py")

लोड की जा रही हर फ़ाइल को खोलकर देखें: AGENTS.md संपादकीय नज़रिया और वर्कफ़्लो के नियम तय करता है; SKILL.md, सिलसिलेवार निर्देशों वाली PDF प्लेबुक है; generate_pdf.py, पहले से बनाया गया रेंडरर है, जिसे एजेंट चलाएगा.

system_instruction के बजाय AGENTS.md क्यों ? Interactions API, system_instruction स्ट्रिंग पैरामीटर को सीधे तौर पर भी स्वीकार करता है. दोनों तरीके काम करते हैं और एक साथ इस्तेमाल करने पर, ज़्यादा असरदार होते हैं. AGENTS.md यहां बेहतर विकल्प है, क्योंकि यह आपके कोड के साथ रिपॉज़िटरी में मौजूद होता है. साथ ही, इसे प्रोजेक्ट के बाकी हिस्से के साथ वर्शन कंट्रोल किया जाता है. इसके अलावा, यह पहले टोकन से ही एजेंट के कॉन्टेक्स्ट में होता है. हर कॉल के हिसाब से बदलाव करने के लिए, system_instruction का इस्तेमाल करें. लंबी अवधि के लिए पर्सोना की परिभाषाएं और दिशा-निर्देश तय करने के लिए, AGENTS.md का इस्तेमाल करें.

अब run_digest() में दो और बदलाव करें:

TODO 3: environment को "remote" से बदलकर sources dict में डालें. साथ ही, input को "Generate the digest." पर सेट करें:

        environment={
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": ".agents/AGENTS.md",
                    "content": AGENTS_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/SKILL.md",
                    "content": SKILL_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                    "content": GENERATE_PDF_PY,
                },
            ],
        },

TODO 4: इस लाइन को print(f"\nDone. environment_id={environment_id}") के ठीक बाद जोड़ें:

    save_env(ENVIRONMENT_ID=environment_id, INTERACTION_ID=interaction_id)

save_env को run_digest.py में पहले ही तय किया जा चुका है. यह दोनों आईडी को .env में लिखता है, ताकि अगले चरण में एजेंट को फिर से चलाए बिना PDF डाउनलोड किया जा सके.

हर सोर्स क्या करता है

हर सोर्स एक ऐसी फ़ाइल होती है जिसे एजेंट के चलने से पहले, स्टार्टअप के समय सैंडबॉक्स फ़ाइल सिस्टम में माउंट किया जाता है. target पाथ, Antigravity के हार्नेस के हिसाब से सही जगह पर हैं:

.agents/
├── AGENTS.md                              ← auto-loaded as global instructions
└── skills/
    └── digest-pdf/
        ├── SKILL.md                       ← auto-discovered and registered as a skill
        └── scripts/
            └── generate_pdf.py            ← pre-built renderer the agent can run

target पाथ	वैरिएबल	हार्नेस इसका इस्तेमाल कैसे करता है
.agents/AGENTS.md	AGENTS_MD	लगातार दिखने वाले निर्देशों के तौर पर अपने-आप लोड हो जाते हैं: संपादकीय नज़रिया, वर्कफ़्लो, एक्ज़ीक्यूशन के नियम
.agents/skills/digest-pdf/SKILL.md	SKILL_MD	नाम वाली स्किल के तौर पर अपने-आप खोजी गई और रजिस्टर की गई; एजेंट इसे नाम से शुरू करता है
.agents/skills/digest-pdf/scripts/generate_pdf.py	GENERATE_PDF_PY	पहले से बनाया गया PDF रेंडरर; एजेंट summaries.json लिखता है और फिर इस स्क्रिप्ट को चलाता है

स्किल, क्रॉस-प्लैटफ़ॉर्म स्टैंडर्ड होती हैं (agentskills.io). ये एजेंट को प्रक्रियात्मक मेमोरी देते हैं: न सिर्फ़ यह कि क्या जानना है, बल्कि यह भी कि किसी खास टास्क को चरण दर चरण कैसे पूरा करना है. SKILL.md का मुख्य हिस्सा सिर्फ़ तब लोड होता है, जब स्किल ट्रिगर होती है. मेटाडेटा (नाम + ब्यौरा) हमेशा कॉन्टेक्स्ट में रहता है. इसे प्रोग्रेसिव डिसक्लोज़र कहा जाता है. इससे कॉन्टेक्स्ट विंडो साफ़ रहती है.

यहां दो बातों पर ध्यान दें:

• Skill vs AGENTS.md: AGENTS.md पहले टोकन से ही एजेंट के कॉन्टेक्स्ट में होता है: आवाज़, वर्कफ़्लो के नियम, और एक्ज़ीक्यूशन की पाबंदियां. SKILL.md मांग पर सिर्फ़ तब लोड होता है, जब एजेंट को लगता है कि टास्क के लिए इस स्किल की ज़रूरत है. AGENTS.md को छोटा रखना चाहिए. हमारा सुझाव है कि आप सबसे नीचे एक छोटा कैटलॉग शामिल करें. इसमें उपलब्ध स्किल की सूची दी गई हो, ताकि एजेंट को पता चल सके कि उसे क्या ढूंढना है. .agents/AGENTS.md में मौजूद ## Skills टेबल ठीक यही काम करती है: यह एजेंट को बताती है कि digest-pdf मौजूद है, ताकि टास्क के लिए ज़रूरी होने पर हार्नेस, इसका पूरा SKILL.md लोड कर सके.
• एजेंट बनाने और मैनेज करने की सुविधा बनाम ADK: ADK, प्रोग्रामैटिक रूट का इस्तेमाल करता है: Python कोड में load_skill_from_dir("skills/digest-pdf") और फिर SkillToolset(skills=[skill]). एजेंट बनाने और मैनेज करने की सुविधा के साथ, इनलाइन रूट का इस्तेमाल किया जाता है: environment.sources के ज़रिए फ़ाइल को माउंट करें. इसके बाद, हार्नेस इसे .agents/skills/*/SKILL.md से अपने-आप ढूंढ लेता है. कोई रजिस्ट्रेशन कोड नहीं है.

पुष्टि करें

uv run python run_digest.py

अब इसमें एक से तीन मिनट लगते हैं. आपको एजेंट को कॉन्फ़िगरेशन फ़ाइलें पढ़ते हुए, जवाब लिखते हुए, और PDF सेव करते हुए दिखना चाहिए:

[agent started]
  [tool] read_file (/.agents/skills/digest-pdf/SKILL.md)
  [tool] list_files (/.agents/skills/digest-pdf/scripts)
  [tool] read_file (/.agents/skills/digest-pdf/scripts/generate_pdf.py)
  [tool] run_code
  [tool] write_file (/workspace/summaries.json)
  [tool] run_code
  [tool] delete_file (/tmp/test_scrape.py)
I have successfully generated today's tech news digest and saved the formatted document to /workspace/digest.pdf.
Done. environment_id=4129ffd75574e308748e9425d7ec828f

environment_id अब एक असल वैल्यू है: सैंडबॉक्स, आपकी कॉन्फ़िगरेशन फ़ाइलों के साथ चला और एजेंट ने digest.pdf बनाया. अगले चरण में, डाउनलोड करने से पहले एक सुरक्षा हुक जोड़ा जाता है.

6. सेफ़्टी हुक जोड़ना

हुक की मदद से, हर टूल कॉल के पहले या बाद सैंडबॉक्स में स्क्रिप्ट चलाई जा सकती है. डाइजेस्ट एजेंट, Python स्क्रिप्ट को चलाने के लिए code_execution का इस्तेमाल करता है. इसलिए, pre_tool_execution हुक उन कॉल को इंटरसेप्ट कर सकता है और शेल कमांड को नुकसान पहुंचाने से पहले उन्हें ब्लॉक कर सकता है.

रनटाइम, सैंडबॉक्स से .agents/hooks.json को पढ़ता है. मैचिंग टूल को कॉल करने से पहले, यह stdin पर कॉल की जानकारी को आपकी गेट स्क्रिप्ट में पाइप करता है. यह स्क्रिप्ट, {"decision": "allow"} या {"decision": "deny", "reason": "..."} को stdout पर प्रिंट करती है. 'मना करें' विकल्प चुनने पर, टूल कॉल रद्द हो जाता है. साथ ही, एजेंट को आपकी वजह दिखती है और वह खुद ही गड़बड़ी ठीक कर लेता है.

क्या जोड़ना है

TODO 5: run_digest.py में, इन दो कॉन्स्टेंट को सबसे ऊपर जोड़ें. इन्हें मौजूदा load_source कॉल के बाद जोड़ें:

import json

HOOKS_JSON = json.dumps({
    "safety-gate": {
        "pre_tool_execution": [
            {
                "matcher": "code_execution",
                "hooks": [
                    {
                        "type": "command",
                        "command": "python3 /.agents/hooks-scripts/gate.py",
                        "timeout": 10,
                    }
                ],
            }
        ]
    }
}, indent=2)

GATE_PY = """\
#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
cmd = str(data.get("tool_call", {}).get("args", {}))
if "rm -rf" in cmd:
    print(json.dumps({"decision": "deny", "reason": "Destructive command blocked by safety gate."}))
else:
    print(json.dumps({"decision": "allow"}))
"""

TODO 6: interactions.create() में मौजूद sources सूची में दो और एंट्री जोड़ें:

{"type": "inline", "target": ".agents/hooks.json",            "content": HOOKS_JSON},
{"type": "inline", "target": ".agents/hooks-scripts/gate.py", "content": GATE_PY},

command फ़ील्ड में हुक स्क्रिप्ट का पाथ /.agents/ (पूरा पाथ) से शुरू होता है. हालांकि, sources में मौजूद target, मिलते-जुलते पाथ (agents/hooks-scripts/gate.py) का इस्तेमाल करता है. दोनों, सैंडबॉक्स में मौजूद एक ही फ़ाइल को रेफ़र करते हैं.

डाइजेस्ट रन में हुक कैसे ट्रिगर होते हैं

जब भी एजेंट, Python स्क्रिप्ट या शेल कमांड चलाने के लिए code_execution को कॉल करता है, तो रनटाइम, कॉल से जुड़ी जानकारी को सबसे पहले gate.py पर पाइप करता है. अगर कमांड में rm -rf शामिल है, तो हुक deny दिखाता है. साथ ही, एजेंट को अनुरोध अस्वीकार होने की वजह मिलती है और वह सुरक्षित विकल्प के साथ फिर से कोशिश करता है. कोड एक्ज़ीक्यूशन के लिए किए गए अन्य सभी कॉल में कोई बदलाव नहीं होता.

पुष्टि करें

uv run python run_digest.py

आउटपुट पहले जैसा ही है: सुरक्षा गेट, PDF जनरेट करने के सभी सामान्य निर्देशों को अनुमति देता है. हुक के चालू होने की पुष्टि करने के लिए, एजेंट के इनपुट को कुछ समय के लिए बदलें. इसके बाद, उससे rm -rf /tmp/test चलाने के लिए कहें. आपको एजेंट की रिपोर्ट में दिखेगा कि कमांड को ब्लॉक कर दिया गया है. इसके बाद, कोई दूसरा विकल्प चुनें.

7. PDF डाउनलोड करें

एजेंट ने सैंडबॉक्स में digest.pdf से /workspace/digest.pdf तक लिखा. एनवायरमेंट स्नैपशॉट, Gemini Files API के ज़रिए टार आर्काइव के तौर पर उपलब्ध है.

असली प्रोजेक्ट में, इवेंट लूप के ठीक बाद डाउनलोड, run_digest() में मौजूद होगा. यह उसी रन और उसी environment_id में होगा. इसके लिए, कोई अलग फ़ाइल नहीं होगी. इस कोडलैब में यह download_pdf.py में मौजूद है, ताकि एजेंट को फिर से चलाए बिना इसे फिर से डाउनलोड किया जा सके. पिछले चरण में जोड़े गए save_env() कॉल से, दोनों आईडी .env में अपने-आप सेव हो जाते हैं. इसलिए, यह फ़ाइल उन्हें तुरंत पढ़ सकती है.

अगर ज़रूरी हो, तो requests इंस्टॉल करें:

uv pip install requests

क्या जानकारी भरनी है

download_pdf.py खोलें. इसमें दो काम की सूची हैं.

TODO 1: requests.get() कॉल के बारे में जानकारी भरो:

    r = requests.get(
        f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download",
        params={"alt": "media"},
        headers={"x-goog-api-key": api_key},
        allow_redirects=True,
    )
    r.raise_for_status()

यूआरएल, सैंडबॉक्स के स्नैपशॉट के बारे में बताता है. params={"alt": "media"} मेटाडेटा के बजाय रॉ बाइट दिखाता है. आपका मौजूदा GEMINI_API_KEY, Files API की पुष्टि भी करता है.

TODO 2: tar फ़ाइल से PDF ढूंढें और उसे एक्सट्रैक्ट करें:

            member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
            tar.extract(member, path=tmp, filter="data")

टार पाथ प्रीफ़िक्स, अलग-अलग रन के हिसाब से अलग-अलग होता है. इसलिए, सटीक पाथ को हार्डकोड करने के बजाय, प्रत्यय के हिसाब से खोजें. filter="data" असुरक्षित tar फ़ाइल निकालने के बारे में, Python 3.13 की चेतावनियों को बंद कर देता है.

पुष्टि करें

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

digest.pdf को उसी डायरेक्ट्री में खोलें. इसमें लाइव वेब पेजों से एजेंट के जनरेट किए गए फ़ॉर्मैट किए गए डाइजेस्ट शामिल होते हैं.

8. बातचीत जारी रखना

आपके पास पहले से ही digest.pdf है. अगर आपको सिर्फ़ फ़ाइल चाहिए थी, तो आपका काम हो गया. यह चरण किसी दूसरी चीज़ के बारे में है: एजेंट से वेब को फिर से फ़ेच किए बिना डाइजेस्ट को बदलने के लिए कहना.

सैंडबॉक्स अब भी चालू है. एजेंट के पास अब भी /workspace/digest.pdf है और उसे उन सभी कहानियों के बारे में याद है जिन्हें उसने छोटा करके बताया था. दूसरी बार interactions.create() कॉल करने पर, उसी सैंडबॉक्स में फ़ॉलो-अप मैसेज भेजा जाता है. यहां, हर कहानी के नीचे "यह क्यों ज़रूरी है" नोट जोड़ने के लिए कहा गया है. इसके बाद, यह PDF को अपडेट कर देता है. इसके लिए, न तो इसे फिर से फ़ेच करने की ज़रूरत पड़ती है और न ही फिर से खास जानकारी तैयार करने की.

क्या जानकारी भरनी है

refine_digest.py खोलें. इसमें तीन काम की सूची हैं.

TODO 1 और 2: interactions.create() में मौजूद, सिलसिलेवार बातचीत के दो पैरामीटर की वैल्यू भरें:

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id, फ़ाइलों और पैकेज के साथ उसी सैंडबॉक्स को फिर से शुरू करता है. previous_interaction_id=interaction_id एजेंट को बातचीत का इतिहास देता है. पहले कॉल के बाद, कोई और बदलाव नहीं किया जाता.

TODO 3: इवेंट लूप के बाद, नए interaction_id को .env में सेव करें:

save_env(INTERACTION_ID=interaction_id)

हर interactions.create() कॉल से एक नया interaction_id जनरेट होता है. इसे वापस लिखने का मतलब है कि अगली बार यह रिफ़ाइनमेंट previous_interaction_id के तौर पर पास हो जाएगा और चेन सही तरीके से काम करेगी. सैंडबॉक्स आईडी कभी नहीं बदलता. इसलिए, ENVIRONMENT_ID को अपडेट करने की ज़रूरत नहीं होती.

दो पैरामीटर, जिनकी वजह से सिलसिलेवार बातचीत काम करती है

आईडी	यह कुकी क्या जानकारी सेव करती है	उपमा
environment=environment_id	फ़ाइलें, इंस्टॉल किए गए पैकेज, सिस्टम की स्थिति: Linux फ़ाइल सिस्टम पर मौजूद हर चीज़	मीटिंग के बीच एक ही ऑफ़िस डेस्क का इस्तेमाल करना
previous_interaction_id=interaction_id	बातचीत का इतिहास: एजेंट ने पिछले टर्न में क्या कहा और क्या किया	पिछली मीटिंग में हुई चर्चा को याद रखना

इनमें से किसी भी आईडी को अलग-अलग पास किया जा सकता है:

• environment_id के लिए: फ़ाइलों और पैकेज का फिर से इस्तेमाल करें, लेकिन नई बातचीत शुरू करें. यह एक ही फ़ाइल फ़ोल्डर में नए टास्क के लिए काम का है.
• previous_interaction_id सिर्फ़: बातचीत के कॉन्टेक्स्ट को जारी रखें, लेकिन नए सैंडबॉक्स में (फ़ाइलें मिट जाती हैं).
• दोनों: पूरी तरह से जारी रखना. इस चरण में इसी का इस्तेमाल किया जाता है.

environment_id के बिना: खाली सैंडबॉक्स, कोई PDF नहीं. previous_interaction_id के बिना: कोई कॉन्टेक्स्ट नहीं है. एजेंट किसी खास सेक्शन को बेहतर नहीं बना सकता.

यह ADK + Cloud Run के साथ लिखे जाने वाले सेशन मैनेजमेंट की जगह लेता है. ADK की मदद से, बातचीत के इतिहास को डेटाबेस में सेव किया जाता है और हर अनुरोध में इसे शामिल किया जाता है. एजेंट बनाने और मैनेज करने की सुविधा की मदद से, दो आईडी पास किए जाते हैं. बाकी का काम प्लैटफ़ॉर्म करता है.

पुष्टि करें

uv run python refine_digest.py

स्ट्रीमिंग तुरंत शुरू होनी चाहिए. एजेंट को कोई भी जानकारी दोबारा नहीं लानी चाहिए. यह प्रोसेस पूरी होने के बाद:

Refinement done.
Saved digest_v2.pdf (52,418 bytes)

digest_v2.pdf खोलें और इसकी तुलना digest.pdf से करें. अब हर स्टोरी में, "यह क्यों अहम है" लाइन जोड़ी जानी चाहिए.

9. मैनेज किए जा रहे एजेंट के कॉन्फ़िगरेशन को सेव करना

अब तक के सभी कॉल में, AGENTS.md, SKILL.md, और generate_pdf.py की सुविधा चालू है. यह काम करता है, लेकिन हर बार कॉल करने पर, आपके कॉलिंग कोड में पूरी फ़ाइल का कॉन्टेंट शामिल होता है. agents.create(), कॉन्फ़िगरेशन को Google के सर्वर पर सेव किए गए एजेंट में शामिल करता है. अगले इनवोकेशन में सिर्फ़ एजेंट आईडी पास किया जाता है:

Inline calls:   send sources on every call
Named agent:    bake once → invoke by ID, no sources

क्या जानकारी भरनी है

save_agent.py खोलें. इसमें एक काम की सूची (TODO 1) है.

AGENTS_MD, SKILL_MD, और GENERATE_PDF_PY को run_digest.py से इंपोर्ट किया जाता है. पक्का करें कि आपने पसंद के मुताबिक बनाने का चरण पूरा कर लिया हो और इस फ़ाइल को चलाने से पहले, उन तीन लोडिंग लाइनों को जोड़ लिया हो.

ध्यान दें कि कॉन्स्टेंट को सीधे तौर पर run_digest.py से इंपोर्ट किया जाता है (कोई डुप्लीकेट नहीं):

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

TODO 1: agents.create() कॉल के बारे में जानकारी भरो:

agent = client.agents.create(
    id="my-digest",
    base_agent=BASE_AGENT,
    agent_config={
        "type": "antigravity",
        "model": "gemini-3.7-flash",
    },
    description="Daily tech digest with editorial voice and PDF generation.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

agent_config, बुनियादी मॉडल सेट करता है. gemini-3.7-flash इस वर्कफ़्लो के लिए डिफ़ॉल्ट और सबसे अच्छा विकल्प है. अगर आपको कम संसाधनों का इस्तेमाल करना है या कम लागत में काम करना है, तो gemini-3.6-flash, gemini-3.5-flash, और gemini-3.5-flash-lite का इस्तेमाल किया जा सकता है.

base_environment (environment नहीं) पिछले चरण में मौजूद इनलाइन कॉल से अलग है: सोर्स, Google के सर्वर पर सेव किए जाते हैं और आने वाले समय में हर कॉल के लिए अपने-आप माउंट हो जाते हैं. इसे एक बार चलाएं, न कि हर डाइजेस्ट रन पर.

पुष्टि करें: एजेंट को सेव करें

uv run python save_agent.py

Saved: my-digest
my-digest: Daily tech digest with editorial voice and PDF generation.

409 Conflict? my-digest नाम का एक एजेंट, पिछली बार के रन से पहले से मौजूद है. स्टार्टर फ़ाइल, नई फ़ाइल बनाने से पहले इसे अपने-आप मिटा देती है. इसलिए, इसे फिर से चलाने पर कोई खतरा नहीं होता.

सेव किए गए एजेंट को चालू करना

invoke_agent.py खोलें. यह सेव किए गए एजेंट को बिना किसी सोर्स के आईडी से कॉल करता है:

stream = client.interactions.create(
    agent="my-digest",
    input="Generate the digest.",
    stream=True,
    environment="remote",
)

इसकी तुलना इनलाइन कॉल से करें: agent=BASE_AGENT को "my-digest" से बदल दिया गया है. साथ ही, तीन इनलाइन सोर्स वाले पूरे environment ब्लॉक को environment="remote" से बदल दिया गया है. यह कॉन्फ़िगरेशन, Google के सर्वर पर पहले से ही मौजूद है.

पुष्टि करें: सेव किए गए एजेंट को चालू करें

uv run python invoke_agent.py

आपको इनलाइन रन के तौर पर वही लाइव स्ट्रीम दिखेगी, लेकिन कॉल में सोर्स फ़ाइलें नहीं होंगी. जांच पूरी होने के बाद, .env में मौजूद ENVIRONMENT_ID और INTERACTION_ID अपडेट हो जाते हैं. इससे, refine_digest.py का इस्तेमाल पहले की तरह किया जा सकता है.

[agent started]
  [tool] read_file
  [tool] write_file
  [tool] run_code
I have successfully created today's tech news digest.
Done. environment_id=9a1c3e02-...

10. Gmail से भेजें

एजेंट ने डाइजेस्ट जनरेट कर दिया है और उसे /workspace/digest.pdf में सेव कर दिया है. आपने इसे अब तक सिर्फ़ लोकल तौर पर डाउनलोड किया है. इस चरण में, एजेंट सैंडबॉक्स से Gmail REST API को कॉल करता है. इससे, यह सीधे आपके इनबॉक्स में पहुंच जाता है.

तरीका: आपको OAuth 2.0 ऐक्सेस टोकन स्थानीय तौर पर मिलता है. इसके बाद, आपको इसे input प्रॉम्प्ट में एजेंट को पास करना होता है. एजेंट, code_execution का इस्तेमाल करके, PDF अटैच किया हुआ MIME ईमेल बनाता है. इसके बाद, उसे Gmail API पर पोस्ट करता है. कस्टम टूल नहीं, एमसीपी सर्वर का रजिस्ट्रेशन नहीं.

ज़रूरी शर्तें

अपने GCP प्रोजेक्ट में Gmail API चालू करें और OAuth 2.0 क्लाइंट आईडी बनाएं:

1. console.cloud.google.com/apis/library/gmail.googleapis.com पर जाएं और Gmail API चालू करें.
2. एपीआई और सेवाएं > क्रेडेंशियल > क्रेडेंशियल बनाएं > OAuth 2.0 क्लाइंट आईडी पर जाएं.
3. ऐप्लिकेशन का टाइप: डेस्कटॉप ऐप्लिकेशन. JSON फ़ाइल डाउनलोड करें और उसे प्रोजेक्ट के रूट में credentials.json के तौर पर सेव करें.

.env में, ईमेल पाने वाले का ईमेल पता जोड़ें:

RECIPIENT_EMAIL=[e-mail]

अगर ज़रूरी हो, तो पुष्टि करने वाली लाइब्रेरी इंस्टॉल करें:

uv sync

क्या जानकारी भरनी है

send_digest.py खोलें. इसमें दो काम की सूची हैं.

TODO 1: OAuth 2.0 ऐक्सेस टोकन लोड या रीफ़्रेश करें:

creds = None
if TOKEN_FILE.exists():
    creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)
if not creds or not creds.valid:
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
        TOKEN_FILE.write_text(creds.to_json())
    else:
        flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
        creds = flow.run_local_server(port=8080, open_browser=False)
        TOKEN_FILE.write_text(creds.to_json())

raise NotImplementedError लाइन जोड़ने के बाद, उसे हटा दें. पहली बार चलाने पर, यह OAuth की सहमति वाली स्क्रीन के लिए ब्राउज़र खोलता है. टोकन को .gmail_token.json में कैश मेमोरी में सेव किया जाता है, ताकि आने वाले समय में इसका इस्तेमाल किया जा सके.

Cloud Shell का इस्तेमाल करने वाले लोग: run_local_server ब्राउज़र टैब खोलता है. OAuth फ़्लो पूरा करने के लिए, Cloud Shell में पोर्ट 8080 पर वेब प्रीव्यू का इस्तेमाल करें या इस चरण के लिए, send_digest.py को स्थानीय तौर पर चलाएं.

TODO 2: input="" की जगह ईमेल से जुड़े निर्देश डालें. टोकन, creds.token के तौर पर पहले से ही स्कोप में है:

    input=(
        "Use the Gmail REST API to send an email:\n"
        f"  To: {recipient}\n"
        "  Subject: Tech Digest - <today's date in YYYY-MM-DD format>\n"
        "  Attachment: /workspace/digest.pdf attached as digest.pdf\n\n"
        "For the body, read /workspace/summaries.json and format it as a "
        "human-readable newsletter, NOT raw JSON. Use this structure:\n"
        "  Tech Digest - <date>\n\n"
        "  === <source name> ===\n"
        "  1. <title>\n"
        "     <summary>\n\n"
        "Steps:\n"
        "1. Parse /workspace/summaries.json and build the formatted body text above.\n"
        "2. Read /workspace/digest.pdf as bytes.\n"
        "3. Build a MIME multipart message using Python's email library.\n"
        "4. Base64url-encode the raw message.\n"
        "5. POST to https://gmail.googleapis.com/gmail/v1/users/me/messages/send "
        "with Authorization header using this token: "
        f"{creds.token}"
    ),

हर हिस्से का क्या काम है

बातचीत उसी सैंडबॉक्स में फिर से शुरू होती है जहां एजेंट ने पहले ही digest.pdf और summaries.json जनरेट कर लिया था. previous_interaction_id एजेंट को बातचीत का इतिहास देता है.

ऐक्सेस टोकन को input स्ट्रिंग में पास किया जाता है. एजेंट, इसे प्रॉम्प्ट से पढ़ता है और Gmail API को कॉल करते समय, इसका इस्तेमाल Authorization: Bearer हेडर में करता है. यह कभी भी आपकी लोकल मशीन या फ़ाइल सिस्टम को ऐक्सेस नहीं करता.

यह एजेंट, सैंडबॉक्स में Python स्क्रिप्ट लिखने और उसे चलाने के लिए code_execution का इस्तेमाल करता है: यह summaries.json को पढ़ता है, उसे न्यूज़लेटर के तौर पर फ़ॉर्मैट करता है, digest.pdf को पढ़ता है, MIME मल्टीपार्ट मैसेज बनाता है, उसे base64url-एन्कोड करता है, और https://gmail.googleapis.com/gmail/v1/users/me/messages/send पर पोस्ट करता है.

पुष्टि करें

uv run python send_digest.py

Sending digest...
[agent started]
  [tool] read_file (/workspace/summaries.json)
  [tool] run_code
  [tool] run_code
Email sent successfully.
Email sent. Check your inbox.

अपना इनबॉक्स देखें. ईमेल, न्यूज़लेटर के फ़ॉर्मैट में मौजूद मुख्य हिस्से और digest.pdf के साथ मिलता है.

11. रोज़ाना के रन शेड्यूल करना

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

Manual:     python run_digest.py     → runs once, now
Trigger:    client.triggers.create() → runs every morning, automatically

क्या जानकारी भरनी है

create_trigger.py खोलें. इसमें एक काम की सूची है.

TODO 1: triggers.create() कॉल की जानकारी भरें. ट्रिगर हर दिन पूरे वर्कफ़्लो को चलाता है: ब्यौरा जनरेट करता है और उसे आपके इनबॉक्स में भेजता है. ऐक्सेस टोकन एक घंटे में खत्म हो जाते हैं. इसलिए, यह .gmail_token.json से रिफ़्रेश टोकन को इनलाइन सोर्स के तौर पर इंजेक्ट करता है, ताकि एजेंट हर बार इसे नए टोकन के लिए बदल सके.

trigger = client.triggers.create(
    schedule="0 9 * * *",
    time_zone="UTC",
    display_name="daily-tech-digest",
    max_consecutive_failures=3,
    execution_timeout_seconds=600,
    interaction={
        "agent": "my-digest",
        "input": (
            f"Generate the daily tech digest following AGENTS.md instructions. "
            f"Then send an email to {recipient}:\n"
            "- Subject: Tech Digest - <today's date in YYYY-MM-DD format>\n"
            "- Body: the content of /workspace/summaries.json formatted as a readable "
            "newsletter (NOT raw JSON).\n"
            "- Attachment: /workspace/digest.pdf\n\n"
            "For Gmail auth: read /workspace/.gmail_creds.json, POST to "
            "https://oauth2.googleapis.com/token with grant_type=refresh_token "
            "and the client_id, client_secret, refresh_token from the file to get an "
            "access_token. Then POST to "
            "https://gmail.googleapis.com/gmail/v1/users/me/messages/send "
            "with Authorization: Bearer <access_token>."
        ),
        "environment": {
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": "/workspace/.gmail_creds.json",
                    "content": gmail_creds,
                }
            ],
        },
    },
)

schedule एक स्टैंडर्ड क्रॉन एक्सप्रेशन है. "0 9 * * *" का मतलब है कि हर दिन सुबह 9:00 बजे. time_zone (आईएएनए फ़ॉर्मैट, जैसे कि "America/New_York", "Europe/Paris") का इस्तेमाल करके, इसे अपने टाइमज़ोन के हिसाब से बदलें.

execution_timeout_seconds=600 डिफ़ॉल्ट टाइम आउट है. max_consecutive_failures=3 लगातार तीन बार ट्रिगर होने में गड़बड़ी होने पर, ट्रिगर अपने-आप रुक जाता है. एपीआई के लिए डिफ़ॉल्ट रूप से यह संख्या पांच होती है. हालांकि, वर्कशॉप के लिए तीन बार गड़बड़ी होने पर ट्रिगर रुक जाना बेहतर होता है.

sources सूची, सैंडबॉक्स में /workspace/.gmail_creds.json पर .gmail_creds.json को इंजेक्ट करती है. एजेंट इसे पढ़ता है और रीफ़्रेश टोकन को नए ऐक्सेस टोकन के लिए बदलता है. इसके बाद, Gmail API को कॉल करता है. रीफ़्रेश टोकन की समयसीमा खत्म नहीं होती. इसलिए, यह हर शेड्यूल किए गए रन पर काम करता है. इसके लिए, टोकन को मैन्युअल तरीके से रीफ़्रेश करने की ज़रूरत नहीं होती.

कॉल जोड़ने के बाद, raise NotImplementedError लाइन हटाएं.

पुष्टि करें

uv run python create_trigger.py

Trigger created: trig_abc123
Next run:        2026-07-23T09:00:00Z

create_trigger.py, ट्रिगर आईडी को .env में अपने-आप सेव करता है.

प्रोग्राम चलाने के बाद, उसके इतिहास की जांच करने के लिए:

uv run python check_trigger.py

शेड्यूल किए गए अगले समय का इंतज़ार किए बिना, ट्रिगर को तुरंत फ़ायर करने के लिए:

uv run python fire_trigger.py

ट्रिगर को रोकने या मिटाने के लिए:

uv run python pause_trigger.py

ट्रिगर पहले से ही ईमेल भेजता है. create_trigger.py स्टार्टर, पूरे फ़्लो को मैनेज करता है: डाइजेस्ट जनरेट करना और फिर उसे Gmail के ज़रिए भेजना. इनलाइन सोर्स, रीफ़्रेश टोकन डालता है. एजेंट, हर बार रन होने पर इसे नए ऐक्सेस टोकन के लिए बदलता है.

12. स्टोरेज में जगह बनाएं

सैंडबॉक्स का इस्तेमाल न करने पर, यह सात दिनों के बाद अपने-आप बंद हो जाता है. बंद करने के लिए कोई सर्वर नहीं है. मिटाने के लिए कोई कंटेनर नहीं है.

अगर आपने एजेंट कॉन्फ़िगरेशन सेव किया है, तो उसे मिटाएं:

uv run python delete_agent.py

13. खास जानकारी

आपने मैनेज किया गया एजेंट शुरू से बनाया है. इसमें एक-एक करके सभी कॉन्सेप्ट शामिल किए गए हैं. यहां बताया गया है कि हर कसरत से क्या सीखा जा सकता है:

कसरत	सिद्धांत	Key API
पहला कॉल करना	असली Linux सैंडबॉक्स उपलब्ध कराना और उसके इवेंट को लाइव स्ट्रीम करना	interactions.create(agent, input, environment, stream=True), event.event_type
एजेंट को पसंद के मुताबिक बनाना	कॉन्फ़िगरेशन फ़ाइलों को माउंट करें; एक ही रन में आईडी को .env पर बनाए रखें	environment.sources, save_env
सेफ़्टी हुक जोड़ना	टूल कॉल को एक्ज़ीक्यूट होने से पहले रोकना; नुकसान पहुंचाने वाले निर्देशों को अस्वीकार करना	hooks.json, pre_tool_execution, gate.py
PDF डाउनलोड करें	एजेंट को फिर से चलाए बिना PDF डाउनलोड करना	download_pdf.py में Gemini Files API :download
Assistant से बातचीत जारी रखना	वेब से फिर से जानकारी लिए बिना बातचीत जारी रखें	environment=environment_id, previous_interaction_id=interaction_id
एजेंट के कॉन्फ़िगरेशन को सेव रखना	एजेंट कॉन्फ़िगरेशन को सेव करता है; आईडी से शुरू करता है, इसके लिए सोर्स की ज़रूरत नहीं होती	agents.create(), agents.list()
Gmail से भेजें	OAuth टोकन को स्थानीय तौर पर हासिल करें. इसे एजेंट को पास करें, जो code_execution के ज़रिए Gmail REST API को कॉल करता है	OAuth 2.0, client.interactions.create(input=...)
रोज़ाना के हिसाब से शेड्यूल करना	क्रॉन शेड्यूल के हिसाब से एजेंट को अपने-आप चलने की अनुमति देना	client.triggers.create(schedule, time_zone, interaction)

मुख्य पैटर्न

1. एक कॉल, एक सैंडबॉक्स: interactions.create() सभी इन्फ़्रास्ट्रक्चर को मैनेज करता है. इसके लिए, न तो कंटेनर डिप्लॉय करने होते हैं और न ही पैकेज को स्थानीय तौर पर इंस्टॉल करना होता है
2. प्रोग्रेसिव स्ट्रीमिंग: stream=True इस सुविधा की मदद से, 90 सेकंड के ब्लैक बॉक्स को टूल कॉल और टेक्स्ट के हिस्सों के लाइव फ़ीड में बदला जा सकता है
3. इनलाइन सोर्स: अपलोड या डिप्लॉयमेंट के किसी भी चरण के बिना, सैंडबॉक्स में AGENTS.md, SKILL.md, और पहले से बनी स्क्रिप्ट को माउंट करें
4. अपने-आप फ़ाइलें ढूंढने की सुविधा का इस्तेमाल करें: .agents/ में रखी गई फ़ाइलें अपने-आप चुन ली जाती हैं. इसके लिए, एसडीके कॉन्फ़िगरेशन की ज़रूरत नहीं होती
5. दो डाइमेंशन वाली स्थिति: environment_id फ़ाइलों और पैकेज को ट्रैक करता है; previous_interaction_id बातचीत के कॉन्टेक्स्ट को ट्रैक करता है; दोनों को अलग-अलग पास किया जा सकता है
6. स्नैपशॉट डाउनलोड करें: एनवायरमेंट एक फ़ुल फ़ाइल सिस्टम टार है. इसे Gemini Files API के ज़रिए ऐक्सेस किया जा सकता है
7. नाम वाले एजेंट: agents.create() कॉन्फ़िगरेशन को हमेशा के लिए सेव करता है; आने वाले समय में होने वाली कॉल में, सिर्फ़ एजेंट आईडी और environment="remote" पास किया जाता है. इसमें कोई सोर्स नहीं होता
8. हुक: hooks.json + गेट स्क्रिप्ट, कॉल को एक्ज़ीक्यूट करने से पहले उन्हें इंटरसेप्ट करती है; deny जवाब से कॉल रद्द हो जाता है और एजेंट खुद ही गड़बड़ी ठीक कर लेता है
9. बाहरी एपीआई कॉल: input प्रॉम्प्ट में क्रेडेंशियल पास करें; एजेंट, सैंडबॉक्स में इंटिग्रेशन कोड लिखता है और उसे code_execution के ज़रिए चलाता है
10. ट्रिगर: client.triggers.create() की मदद से, क्रॉन एक्सप्रेशन पर एजेंट को शेड्यूल करें; एनवायरमेंट, सभी एक्ज़ीक्यूशन में बना रहता है

ADK + Cloud Run बनाम एजेंट बनाने और मैनेज करने की सुविधा: एक नज़र में अंतर

अनुमति	ADK + Cloud Run	Gemini API से एजेंट बनाने और मैनेज करने की सुविधा
सैंडबॉक्स उपलब्ध कराना	docker build + gcloud run deploy	interactions.create()
टूल तय करना	Python फ़ंक्शन, जो एजेंट के साथ रजिस्टर किए गए हैं	पहले से मौजूद सुविधाएं: वेब ब्राउज़ करना, कोड एक्ज़ीक्यूट करना, फ़ाइल सिस्टम
पैकेज इंस्टॉल करना	Dockerfile में pip install	एजेंट, सैंडबॉक्स में pip install को चलाता है
इवेंट स्ट्रीम करना	पसंद के मुताबिक बनाया गया SSE इंफ़्रास्ट्रक्चर	stream=True
सेशन जारी रखना	सेशन का डेटाबेस + कॉन्टेक्स्ट इंजेक्शन	environment_id + previous_interaction_id
कॉन्फ़िगरेशन फ़ाइलें	एजेंट में हार्ड-कोड किया गया हो या स्टार्टअप के समय इंजेक्ट किया गया हो	environment.sources के ज़रिए माउंट किया गया
मैनेज करने के लिए इंफ़्रास्ट्रक्चर	कंटेनर, Cloud Run, IAM, सीक्रेट	कोई नहीं

अगले चरण

• Gemini API से एजेंट बनाने और मैनेज करने की सुविधा से जुड़ा दस्तावेज़ पढ़ें