अगला ‘26 डेवलपर कीनोट: बड़े पैमाने पर एजेंटों को डीबग करना

1. परिचय

इस कोडलैब में, Google Cloud पर चल रहे एआई एजेंट को डीबग करने का तरीका बताया गया है. आपको Agent Runtime में सिम्युलेटर एजेंट को डिप्लॉय करना होगा. साथ ही, समस्याओं का पता लगाने के लिए Cloud Observability का इस्तेमाल करना होगा. इसके अलावा, गड़बड़ियों की असल वजह का पता लगाने और उन्हें रीयल टाइम में ठीक करने के लिए, Gemini Cloud Assist और Antigravity IDE का इस्तेमाल करना होगा.

आर्क

इस डेमो का मकसद यह है कि हमने सिम्युलेटर एजेंट में ADK EventCompaction को अभी-अभी जोड़ा है. इससे सिम्युलेटर, Gemini का इस्तेमाल करके अपने वर्कफ़्लो की खास जानकारी समय-समय पर दे पाता है. इससे हर बार मॉडल को भेजे जाने वाले कॉन्टेक्स्ट की कुल मात्रा कम हो जाती है. इस तरह, जवाब की क्वालिटी बेहतर होती है और कुल लागत कम हो जाती है. हालांकि, हमें पता चलेगा कि हमारे EventCompactionConfig में कोई बग है. इसकी वजह से, एजेंट में गड़बड़ियां हो रही हैं! इस कोडलैब में, इस तरह की समस्या का पता लगाने और उसे तुरंत ठीक करने का तरीका बताया गया है.

कंपैक्शन

आपको क्या करना होगा

  • Marathon Simulator Agent को Agent Runtime में डिप्लॉय करें.
  • एजेंट से जुड़ी गड़बड़ियों का पता लगाने के लिए, Cloud Monitoring Alert सेट अप करें.
  • Cloud Trace और Gemini Cloud Assist का इस्तेमाल करके, गड़बड़ियों की जांच करें.
  • Antigravity और एमसीपी का इस्तेमाल करके, एजेंट की समस्या की वजह का पता लगाएं और उसे ठीक करें.

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

  • कोई वेब ब्राउज़र, जैसे कि Chrome.
  • Google खाता
  • Antigravity (Mac, Linux, और Windows के साथ काम करता है)
  • Python 3.13+.
  • uv (Python पैकेज मैनेजर)

अनुमानित अवधि: 45 मिनट

अनुमानित लागत: 500 रुपये से कम

2. शुरू करने से पहले

Google Cloud प्रोजेक्ट बनाना

  1. Google Cloud Console में जाकर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
  2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो.

अपना एनवायरमेंट सेट अप करने का तरीका

Antigravity खोलें और साइन इन करें. इसके बाद, cmd-shift-P (या ctrl-shift-P) दबाकर टर्मिनल खोलें. इसके बाद, "Create New Terminal" टाइप करें.

टर्मिनल

  1. टर्मिनल से, Google Cloud से पुष्टि करें:
gcloud auth login
gcloud auth application-default login
  1. अपना प्रोजेक्ट आईडी सेट करें:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

एपीआई चालू करें

ज़रूरी Google Cloud API चालू करने के लिए, यह कमांड चलाएं:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. सिम्युलेटर एजेंट सेट अप करना

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

डेटा स्टोर करने की जगह का क्लोन बनाना

next-26-keynotes रिपॉज़िटरी को क्लोन करें और डेमो डायरेक्ट्री पर जाएं:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

एनवायरमेंट वैरिएबल कॉन्फ़िगर करना

सिम्युलेटर एजेंट, कॉन्फ़िगरेशन के लिए .env फ़ाइल का इस्तेमाल करता है.

Antigravity विंडो (Explorer) की बाईं ओर मौजूद sample.env फ़ाइल ढूंढें:

एक्सप्लोरर

sample.env खोलें और GCP_PROJECT_ID फ़ील्ड में अपना Google Cloud प्रोजेक्ट आईडी डालें. फ़ाइल कुछ ऐसी दिखनी चाहिए:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

4. सिम्युलेटर एजेंट को एजेंट रनटाइम में डिप्लॉय करना

अब Agent Development Kit (ADK) का इस्तेमाल करके, एजेंट को Agent Runtime पर डिप्लॉय करें.

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

uv sync

एजेंट रनटाइम में डिप्लॉय करना

  1. adk deploy कमांड चलाएं. इस चरण में, आपके एजेंट को पैकेज किया जाता है और Google Cloud (Agent Runtime) पर डिप्लॉय किया जाता है.
uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

इसे पूरा होने में पांच मिनट लग सकते हैं. इसके बाद, आपको इस तरह का आउटपुट दिखेगा:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...
  1. किसी वेब ब्राउज़र में, Agent Runtime console खोलें. आपको एजेंट रनटाइम पर simulator_agent चलता हुआ दिखेगा. साथ ही, टेलीमेट्री कलेक्शन चालू होगा.

img

5. सूचना पाने की नीति सेट अप करना

एजेंट रनटाइम की गड़बड़ियों का अपने-आप पता लगाने के लिए, Google Cloud Console में लॉग पर आधारित सूचना बनाई जाएगी.

  1. Cloud Monitoring - सूचनाएं कंसोल पर जाएं.

img

  1. सूचना के चैनलों में बदलाव करें पर क्लिक करें. नीचे की ओर स्क्रोल करके, ईमेल टाइप पर जाएं. इसके बाद, अपने निजी ईमेल पते पर सूचनाएं पाने के लिए, ईमेल सूचना चैनल बनाएं. सेव करें पर क्लिक करें.

img

  1. सूचना डैशबोर्ड पर वापस जाएं और नीति बनाएं पर क्लिक करें.
  2. स्क्रीन की दाईं ओर, लॉग पर आधारित सूचना बनाएं पर क्लिक करें.

img

  1. आपको Log Explorer पर रीडायरेक्ट कर दिया जाएगा. यहां दी गई लॉग क्वेरी को चिपकाएं और की जगह अपना प्रोजेक्ट आईडी डालें.
resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

img

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

img

  1. लॉग पर आधारित सूचना को कॉन्फ़िगर करें. सूचना को कोई भी नाम दें. इसके बाद, गंभीरता के लेवल को गड़बड़ी पर सेट करें.

img

  1. "सूचना पाने की फ़्रीक्वेंसी सेट करें" सेक्शन के लिए, आगे बढ़ें पर क्लिक करें (डिफ़ॉल्ट सेटिंग को बनाए रखें).

img

  1. किसे सूचना मिलनी चाहिए? के लिए, सूचना को उस ईमेल सूचना चैनल को ट्रिगर करने के लिए सेट करें जिसे आपने अभी सेट अप किया है. जैसे, My Email).
  2. सेव करें पर क्लिक करें.

6. समस्या की जानकारी को ट्रिगर करना

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

  1. Google Cloud Console में, Agent Runtime कंसोल पर जाएं.
  2. simulator_agent पर क्लिक करें.
  3. सबसे ऊपर मौजूद टूलबार में, Playground पर क्लिक करें. इससे ADK एजेंट के साथ एक नया सेशन शुरू होगा.

img

  1. सेशन की चैट विंडो में, Test Simulation टाइप करें और प्रॉम्प्ट भेजने के लिए enter दबाएं.

इससे मैराथन का सिम्युलेशन शुरू हो जाएगा. इसमें, प्लान किए गए रास्ते पर दौड़ने वाले हज़ारों लोगों को ट्रैक किया जाएगा. आपको get_runner_telemetry और analyze_medical_risk के लिए कई टूल कॉल दिखेंगे, क्योंकि सिम्युलेशन रेस के कई "ज़ोन" का आकलन करता है.

  1. एक मिनट के अंदर, आपको अपने इनबॉक्स में एक ईमेल मिलेगा. इसमें एजेंट में हुई नई घटना के बारे में सूचना दी जाएगी.

img

Cloud Monitoring कंसोल खोलने के लिए, View Incident पर क्लिक करें. Console में समस्या की जांच करने के लिए, अगले पेज पर जाएं.

7. Console में जाकर, समस्या की जांच करना

  1. Cloud Monitoring कंसोल में जाकर, घटना की जानकारी देखें. आपको सिम्युलेटर एजेंट से मिलने वाले गड़बड़ी के लॉग दिखेंगे.

img

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

  1. Agent Runtime कंसोल को फिर से खोलें. simulator_agent पर क्लिक करें. इसके बाद, ट्रेस टैब खोलें.

img

  1. सूची में सबसे हाल के ट्रेस पर क्लिक करें. इसके बाद, सबसे ऊपर दाईं ओर मौजूद, टाइमलाइन पर क्लिक करें. आपको अलग-अलग "स्पैन" के साथ ट्रेस व्यू दिखेगा. एक स्पैन, एजेंट के वर्कफ़्लो में मॉडल या टूल कॉल को दिखाता है.

img

  1. ट्रेस व्यू में मौजूद, लास्ट स्पैन पर क्लिक करें. यह लाल रंग का होना चाहिए.
  2. स्टैकट्रेस पर क्लिक करें. आपको Gemini API मॉडल कॉल से जुड़े गड़बड़ी के लॉग दिखेंगे. खास तौर पर, 400: Invalid Argument गड़बड़ी. इससे पता चलता है कि अनुरोध के लेवल पर कोई समस्या है. यह समस्या, सिम्युलेटर एजेंट के Gemini API को भेजे गए पेलोड से जुड़ी है.

img

8. [ज़रूरी नहीं] डीबग करने के लिए, Cloud Assist Investigations का इस्तेमाल करना

  1. फ़ेल होने वाले स्पैन में, लॉग और इवेंट पर क्लिक करें. स्पार्कल बटन के बगल में मौजूद "अपवाद" लॉग ढूंढें. इसके बाद, लॉग की जांच करें पर क्लिक करें.

img

  1. इससे स्क्रीन की दाईं ओर मौजूद साइडबार में, Cloud Assist Investigation शुरू हो जाती है. इसे लोड होने में करीब तीन से पांच मिनट लगेंगे.

img

  1. यह प्रोसेस पूरी होने के बाद, जांच खोलें.

img

  1. जांच की खास जानकारी देखें.

img

  1. नीचे की ओर स्क्रोल करें और हाइपोथेसिस देखें. Gemini Cloud Assist को, सिम्युलेटर एजेंट की agent.py फ़ाइल की उस लाइन की पहचान करनी चाहिए जिसमें Gemini API 400 गड़बड़ी हो रही है.

img

आइए, हमारे एजेंट के सोर्स कोड को खोलकर इस समस्या के बारे में ज़्यादा जानकारी पाएं. साथ ही, समस्या की असल वजह का पता लगाने के लिए, Antigravity का इस्तेमाल करें. अगले पेज पर जाएं.

9. समस्या की जड़ तक पहुंचने और उसे ठीक करने के लिए, Antigravity का इस्तेमाल करना

  1. Antigravity को फिर से खोलें.
  2. स्क्रीन के सबसे ऊपर दाईं ओर मौजूद, Agent Manager खोलें.

img

  1. पक्का करें कि मॉडल को Gemini 3 Flash और प्लानिंग मोड पर सेट किया गया हो.

img

  1. यहां दिया गया प्रॉम्प्ट डालें और enter दबाएं.
Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.

आपको agent.py में Antigravity को कोड की जांच करते हुए दिखेगा. साथ ही, GitHub पर इससे जुड़ी समस्याओं को खोजते हुए दिखेगा:

Gemini API 400 गड़बड़ी की मुख्य वजह यह है कि हम Gemini 3 Flash के इनपुट कॉन्टेक्स्ट टोकन की सीमा (लगभग 10 लाख) से ज़्यादा टोकन का इस्तेमाल कर रहे हैं. ऐसा इसलिए हो रहा है, क्योंकि हम अक्सर EventCompaction को ट्रिगर नहीं कर रहे हैं, ताकि Simulator Agents टूल-कॉल से मिले बड़े रिस्पॉन्स को असरदार तरीके से छोटा किया जा सके.

इसे ठीक करने के लिए, Antigravity को token_threshold में token_threshold पैरामीटर जोड़ने का सुझाव देना चाहिए, ताकि टोकन की संख्या तय सीमा तक पहुंचने पर, हर इनवोकेशन के दौरान कॉन्टेक्स्ट को समय-समय पर कंप्रेस किया जा सके.EventsCompactionConfig

img

यह GitHub पर इस समस्या के लिए सुझाए गए समाधान के मुताबिक है.

agent.py. पर सुधार लागू करें

पुष्टि करें कि आपको कुछ ऐसा दिख रहा हो:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

10. बदलाव को फिर से लागू करना और उसकी पुष्टि करना

हमने ADK एजेंट के EventCompactionConfig में token_threshold ठीक कर दिया है. अब हम सिम्युलेटर एजेंट को एजेंट रनटाइम में फिर से डिप्लॉय कर सकते हैं.

  1. Antigravity –> New Terminal खोलें.
  2. एनवायरमेंट वैरिएबल सेट करें. AGENT_RUNTIME_ID, आपके simulator_agent का पूरा संसाधन का नाम होना चाहिए. यह एजेंट रनटाइम कंसोल में एजेंट की सूची में देखा जा सकता है.
export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"
  1. एजेंट को फिर से डिप्लॉय करें:
uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

इसे पूरा होने में कुछ मिनट लगेंगे. पुष्टि हो जाने के बाद, आपको यह दिखेगा:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...
  1. एजेंट रनटाइम कंसोल खोलें. simulator_agent को फिर से खोलें. प्लेग्राउंड पर क्लिक करें
  2. वही प्रॉम्प्ट डालें: Test Simulation - इसके बाद, Enter दबाएं.
  3. बैकएंड पर Marathon सिमुलेशन को पूरा होने में कुछ मिनट लगते हैं. आपको कई टूल कॉल दिखेंगे. आखिर में, आपको इस तरह का जवाब दिखेगा:

img

इससे पता चलता है कि सिम्युलेटर ठीक से काम कर रहा है! ✅

  1. उस ADK सेशन के लिए, ट्रेस व्यू खोलें.
  2. आपको सभी "नीले" स्पैन दिखने चाहिए. साथ ही, कोई भी लाल रंग की गड़बड़ी नहीं दिखनी चाहिए. ध्यान दें कि सेशन के कुल टोकन की संख्या, Gemini API के 10 लाख कॉन्टेक्स्ट टोकन की सीमा से ज़्यादा है. कोई बात नहीं, क्योंकि अब EventCompaction को हर इनवोकेशन में काफ़ी बार चलाया जा रहा है, ताकि मॉडल के हर कॉल के लिए कॉन्टेक्स्ट की कुल सीमा को पार न किया जा सके.

img

🎊 बधाई हो! हमने सिम्युलेटर एजेंट में मौजूद गड़बड़ी को ठीक कर दिया है!

11. व्यवस्थित करें

अपने Google Cloud खाते पर शुल्क लगने से बचने के लिए, इस कोडलैब के दौरान बनाए गए संसाधनों को मिटा दें.

एजेंट रनटाइम ऐप्लिकेशन मिटाना

आपके पास कंसोल के ज़रिए या gcloud कमांड का इस्तेमाल करके, Reasoning Engine इंस्टेंस को मिटाने का विकल्प होता है. हालांकि, इसके लिए आपके पास संसाधन का नाम होना चाहिए. आसानी से समझने के लिए, कंसोल का इस्तेमाल करें:

  1. एजेंट रनटाइम पेज पर जाएं.
  2. simulator_agent चुनें –> दाईं ओर मौजूद तीन बिंदु वाले बटन पर क्लिक करें.
  3. मिटाएं पर क्लिक करें.

img

Cloud Monitoring की नीति मिटाना

  1. Cloud Monitoring कंसोल -> सूचनाएं पर जाएं.
  2. नीचे की ओर स्क्रोल करके नीतियां पर जाएं. इसके बाद, तीन बिंदु वाले बटन पर क्लिक करके नीति को मिटाएं.

img

12. 🎊 बधाई हो!

बधाई हो! आपने Google Cloud पर एआई एजेंट को डीबग कर लिया है.

आपको क्या सीखने को मिला

  • एजेंटों को Agent Runtime में डिप्लॉय करने का तरीका.
  • Cloud Monitoring की सूचनाओं का इस्तेमाल करके गड़बड़ियों का पता लगाने का तरीका.
  • Cloud Logging और एजेंट के रनटाइम के ट्रेस व्यू का इस्तेमाल करके, चालू समस्याओं के बारे में ज़्यादा जानें.
  • Gemini Cloud Assist का इस्तेमाल करके, गड़बड़ियों की जांच करने का तरीका.
  • एजेंट के बग की जड़ तक पहुंचने और उन्हें ठीक करने के लिए, Antigravity का इस्तेमाल कैसे करें.
  • लंबे समय तक चलने वाले और टूल का ज़्यादा इस्तेमाल करने वाले एजेंट के टर्न को मैनेज करने के लिए, ADK इवेंट कंपैक्शन को बेहतर बनाने का तरीका.

अगले चरण