Google ADK और AP2 की मदद से, भरोसेमंद चैरिटी एजेंट बनाना

1. भरोसा जीतकर, दान पाने की संभावना बढ़ाना

बैनर

नए वीडियो का आइडिया

आपका फ़ोन वाइब्रेट होता है. आपको एक ऐसी खबर दिखती है जिसमें बताया गया है कि शिक्षा से जुड़े एक प्रोग्राम की मदद से, उन समुदायों के बच्चों को पढ़ना सिखाया जा रहा है जहां शिक्षा के लिए ज़रूरी संसाधन उपलब्ध नहीं हैं. आपको योगदान देने की इच्छा हो. आपने ब्राउज़र खोला और "बच्चों की शिक्षा के लिए दान" खोजा.

Google Search

सैकड़ों नतीजे दिखते हैं.

आपने पहले लिंक पर क्लिक किया. वेबसाइट प्रोफ़ेशनल दिखती हो. नीचे की ओर स्क्रोल करके, उनकी वित्तीय जानकारी पर जाएं. "प्रशासनिक लागत: 28%." रोकें. आपके दिए गए हर डॉलर में से, सिर्फ़ 72 सेंट का इस्तेमाल प्रोग्राम के लिए किया जाएगा. क्या यह सही है? आपको पक्के तौर पर नहीं पता.

किसी दूसरे संगठन से संपर्क करें. आपने इनके बारे में कभी नहीं सुना. क्या वे मान्य हैं? तेज़ी से की गई खोज से, आपको काफ़ी जानकारी मिल जाती है. आपको दो साल पहले का एक Reddit थ्रेड मिलता है. इसमें एक व्यक्ति ने दावा किया है कि "यह एक घोटाला है, मेरा दान कभी किसी काम नहीं आया." वहीं, एक अन्य व्यक्ति उनका बचाव करते हुए कहता है, "वे ज़मीन पर काम कर रहे हैं!" अस्पष्टता की वजह से, कुछ भी समझ नहीं आ रहा है.

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

यह आपकी निजी गलती नहीं है, बल्कि सिस्टम की गड़बड़ी है

यह सुविधा सभी के लिए उपलब्ध है. तोहफ़े देने की इच्छा तो बहुत होती है, लेकिन इस प्रोसेस में कई तरह की समस्याएं आती हैं. इस वजह से, लोग तोहफ़े देने से हिचकिचाते हैं और उन्हें शक होता है:

  • ❌ रिसर्च में मुश्किल होना: हर चैरिटी के लिए, अलग से जांच करनी पड़ती है.
  • ❌ भरोसे की पुष्टि करना: यह पता लगाना मुश्किल है कि कौनसे संगठन बहुत अच्छा काम कर रहे हैं और कौनसे संगठन ठीक से काम नहीं कर रहे हैं. यह भी पता लगाना मुश्किल है कि कौनसे संगठन धोखाधड़ी कर रहे हैं.
  • ❌ विश्लेषण की वजह से फ़ैसला न ले पाना: बहुत ज़्यादा विकल्प होने की वजह से, फ़ैसला लेने में परेशानी होती है.
  • ❌ मोमेंटम में कमी: लॉजिस्टिकल काम बढ़ने की वजह से, दान करने की भावना कम हो जाती है.

इस मुश्किल प्रोसेस की वजह से, असल दुनिया में काफ़ी नुकसान होता है. अमेरिका में, लोग दान देने में सबसे आगे हैं. Giving USA 2024 के मुताबिक, साल 2023 में लोगों ने करीब 374 अरब डॉलर का दान दिया. हालांकि, रिसर्च से पता चलता है कि दान करने में आने वाली समस्याओं की वजह से, दान की जाने वाली रकम में काफ़ी कमी आ जाती है. जैसे, दान करने के लिए सही विकल्प खोजने में लगने वाला समय, दान करने में होने वाली मानसिक परेशानी, और समय की कमी. लाखों दानियों पर की गई स्टडी से पता चला है कि ऑनलाइन दान करने की प्रोसेस में थोड़ी भी मुश्किल आने पर, लोग दान नहीं करते.

इससे पता चलता है कि दान के तौर पर मिलने वाले अरबों डॉलर, उन मकसद तक नहीं पहुंच पाते जिनके लिए उन्हें दिया गया था.

The Vision

किसी दूसरे अनुभव के बारे में सोचें. 30 मिनट के रिसर्च सेशन के बजाय, बस यह कहें:

"मुझे बच्चों के लिए साक्षरता कार्यक्रम को 50 डॉलर दान करने हैं. मेरे लिए, ज़्यादा रेटिंग वाली, भरोसेमंद, और पुष्टि की गई कोई चैरिटी ढूंढो."

इसके बाद, आपको कुछ ही सेकंड में ऐसा जवाब मिलता है जिससे आपको भरोसा हो जाता है:

चैरिटी के नतीजों का कार्ड

एआई गिविंग एजेंट का यही वादा है. हालांकि, इस विज़न को पूरा करने के लिए, हमें एक बुनियादी चुनौती का समाधान करना होगा: जब कोई ऑटोनॉमस एआई एजेंट पैसों का लेन-देन करता है, तो उस पर भरोसा करना ज़रूरी होता है. यह भरोसे पर ही टिका होता है.

  • हम यह कैसे साबित कर सकते हैं कि उपयोगकर्ता ने किस चीज़ के लिए अनुमति दी है?
  • अगर कोई गलती होती है, तो उसकी ज़िम्मेदारी किसकी होगी?
  • हम दान देने वाले लोगों, चैरिटी, और पेमेंट नेटवर्क को इस प्रोग्राम में शामिल होने के लिए कैसे भरोसा दिलाते हैं?

आज का आपका मिशन

इस वर्कशॉप में, दो बेहतरीन टेक्नोलॉजी को मिलाकर, भरोसेमंद एजेंट बनाया जाएगा:

Google Agent Development Kit (ADK)

Agent Payments Protocol (AP2)

Role

एआई एजेंट बनाने के लिए फ़ैक्ट्री

एआई की मदद से किए जाने वाले लेन-देन में भरोसे के लिए आर्किटेक्चरल ब्लूप्रिंट

इससे क्या-क्या फ़ायदे मिलते हैं

• कई एजेंट को मैनेज करने के लिए फ़्रेमवर्क
• टूल की पुष्टि करने जैसी सुरक्षा से जुड़ी सुविधाएं पहले से मौजूद हैं
• प्रोडक्शन के लिए तैयार ऑब्ज़र्वेबिलिटी और ट्रेसिंग
• एजेंट के जटिल व्यवहारों के लिए आसान Python इंटरफ़ेस

• भूमिका के आधार पर सुरक्षा सीमाएं
• पुष्टि किए जा सकने वाले डिजिटल क्रेडेंशियल (ज़रूरी शर्तें)
• सहमति का क्रिप्टोग्राफ़िक सबूत
• जवाबदेही के लिए पूरी ऑडिट ट्रेल

ज़्यादा जानें

ADK से जुड़े दस्तावेज़

AP2 प्रोटोकॉल

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

वास्तुकला

इस वर्कशॉप के आखिर तक, आपने ये बना लिए होंगे:

✅ खास भूमिकाओं वाला मल्टी-एजेंट सिस्टम:

  • एक शॉपिंग एजेंट, जो पुष्टि की गई चैरिटी ढूंढता है
  • कारोबारी या कंपनी का ऐसा एजेंट जो दान से जुड़े ऑफ़र बनाता है
  • क्रेडेंशियल देने वाली ऐसी कंपनी जो सुरक्षित तरीके से पेमेंट प्रोसेस करती है
  • पूरे फ़्लो को मैनेज करने वाला Orchestrator

✅ पुष्टि किए जा सकने वाले तीन तरह के क्रेडेंशियल:

  • IntentMandate: "मेरे लिए शिक्षा के क्षेत्र में काम करने वाली कोई चैरिटी ढूंढो"
  • CartMandate: "कारोबारी या कंपनी ने Room to Read को 5, 000 रुपये का दान किया"
  • PaymentMandate: "Process via simulated payment"

✅ हर लेयर पर सुरक्षा:

  • भूमिका के आधार पर ट्रस्ट बाउंड्री
  • उपयोगकर्ता की साफ़ तौर पर दी गई सहमति

✅ पूरी ऑडिट ट्रेल:

  • हर फ़ैसले को ट्रैक किया जा सकता है
  • सहमति से जुड़ी हर रिकॉर्डिंग
  • हर हैंडऑफ़ दिखे

🔒 अहम जानकारी: यह सुरक्षित लर्निंग एनवायरमेंट है

क्या आप भरोसा जीतने के लिए तैयार हैं?

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

सबसे पहले, समस्या को समझते हैं.

2. आपका Workspace खाता तैयार किया जा रहा है

भरोसेमंद एजेंटों के लिए संस्था

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

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

Cloud Shell ऐक्सेस करना

सबसे पहले, हम Cloud Shell खोलेंगे. यह ब्राउज़र पर आधारित एक टर्मिनल है. इसमें Google Cloud SDK और अन्य ज़रूरी टूल पहले से इंस्टॉल होते हैं.

क्या आपको Google Cloud क्रेडिट चाहिए?

Google Cloud Console में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें. यह सबसे ऊपर दाएं कोने में मौजूद नेविगेशन बार में टर्मिनल आइकॉन होता है.

Cloud Shell

अपना Google Cloud प्रोजेक्ट आईडी ढूंढें:

  • Google Cloud Console खोलें: https://console.cloud.google.com
  • पेज पर सबसे ऊपर मौजूद प्रोजेक्ट ड्रॉपडाउन से, वह प्रोजेक्ट चुनें जिसका इस्तेमाल आपको इस वर्कशॉप के लिए करना है.
  • आपका प्रोजेक्ट आईडी, डैशबोर्ड पर मौजूद प्रोजेक्ट की जानकारी देने वाले कार्ड में दिखता है प्रोजेक्ट आईडी

Cloud Shell खुलने के बाद, पुष्टि करें कि आपने पुष्टि की है:

# Check that you are logged in
gcloud auth list

आपको अपना खाता (ACTIVE) के तौर पर दिखेगा.

अपना प्रोजेक्ट कॉन्फ़िगर करना

अब हम Google Cloud प्रोजेक्ट को सेट अप करेंगे और ज़रूरी एपीआई चालू करेंगे.

प्रोजेक्ट आईडी सेट करना

# Set your project using the auto-detected environment variable in Cloud Shell
gcloud config set project $GOOGLE_CLOUD_PROJECT

# Verify the project has been set
echo "Your active Google Cloud project is: $(gcloud config get-value project)"

ज़रूरी एपीआई चालू करना

आपके एजेंट को Google Cloud की इन सेवाओं का ऐक्सेस चाहिए:

gcloud services enable \
    aiplatform.googleapis.com \
    secretmanager.googleapis.com \
    cloudtrace.googleapis.com

इसमें एक से दो मिनट लग सकते हैं. आपको ये चीज़ें दिखेंगी:

Operation "operations/..." finished successfully.

ये एपीआई क्या उपलब्ध कराते हैं:

  • aiplatform.googleapis.com: एजेंट के तर्क के लिए Gemini मॉडल को ऐक्सेस करने की सुविधा
  • secretmanager.googleapis.com: एपीआई पासकोड को सुरक्षित तरीके से सेव करने के लिए (प्रोडक्शन का सबसे सही तरीका)
  • cloudtrace.googleapis.com: जवाबदेही के लिए, हम इस कुकी का इस्तेमाल करते हैं

स्टार्टर कोड का क्लोन बनाना

सभी टेंप्लेट कोड और संसाधनों के साथ वर्कशॉप रिपॉज़िटरी पाएं:

git clone https://github.com/ayoisio/adk-ap2-charity-agents
cd adk-ap2-charity-agents
git checkout codelab

आइए, पुष्टि करें कि हमारे पास क्या है:

ls -la

आपको यह दिखना चाहिए:

  • charity_advisor/ - यहां हम अपने एजेंट और टूल बनाएंगे
  • scripts/ - टेस्टिंग और पुष्टि के लिए हेल्पर स्क्रिप्ट
  • deploy.sh - डिप्लॉयमेंट के लिए हेल्पर स्क्रिप्ट
  • setup.py - मॉड्यूल इंस्टॉल करने के लिए हेल्पर स्क्रिप्ट
  • .env.template - एनवायरमेंट वैरिएबल फ़ाइल

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

अब हम अपने प्रोजेक्ट के लिए, अलग से Python एनवायरमेंट बनाएंगे.

वर्चुअल एनवायरमेंट बनाना और उसे चालू करना

# Create the virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

✅ पुष्टि: अब आपके प्रॉम्प्ट में (venv) प्रीफ़िक्स दिखना चाहिए.

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

pip install -r charity_advisor/requirements.txt
pip install -e .

इससे ये इंस्टॉल होते हैं:

  • google-adk: एजेंट डेवलपमेंट किट फ़्रेमवर्क
  • google-cloud-aiplatform: Vertex AI और Gemini इंटिग्रेशन
  • ap2: Agent Payments Protocol SDK (GitHub से)
  • python-dotenv: एनवायरमेंट वैरिएबल मैनेज करना

-e फ़्लैग की मदद से, adk_ap2_charity_agents मॉड्यूल को कहीं से भी इंपोर्ट किया जा सकता है.

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

टेंप्लेट से अपना कॉन्फ़िगरेशन बनाएं:

# Copy the template
cp .env.template .env

# Get your current Project ID
PROJECT_ID=$(gcloud config get-value project)

# Replace the placeholder with your actual project ID
sed -i "s/your-project-id/$PROJECT_ID/g" .env

# Verify the replacement worked
grep GOOGLE_CLOUD_PROJECT .env

आपको यह दिखना चाहिए:

GOOGLE_CLOUD_PROJECT=your-actual-project-id

पुष्टि

पुष्टि करने वाली स्क्रिप्ट चलाएं, ताकि यह पक्का किया जा सके कि सब कुछ सही तरीके से कॉन्फ़िगर किया गया है:

python scripts/verify_setup.py

आपको हरे रंग के सही के सभी निशान दिखने चाहिए:

======================================================================
SETUP VERIFICATION
======================================================================

✓ Python version: 3.11.x
✓ google-adk: 1.17.0
✓ google-cloud-aiplatform: 1.111.0+
✓ ap2: 0.1.0
✓ python-dotenv: 1.0.0+
✓ .env file found and contains project ID
✓ Google Cloud project configured: your-project-id

✓ Mock charity database found
✓ Agent templates ready
✓ All directories present

======================================================================
✓ Setup complete! You are ready to build trustworthy agents.
======================================================================

समस्या का हल

अगला चरण?

आपका एनवायरमेंट अब पूरी तरह से तैयार है! आपके पास:

  • ✅ Google Cloud प्रोजेक्ट कॉन्फ़िगर किया गया
  • ✅ ज़रूरी एपीआई चालू किए गए हैं
  • ✅ ADK और AP2 लाइब्रेरी इंस्टॉल की गई हैं
  • ✅ टेंप्लेट कोड में बदलाव करने के लिए तैयार है

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

3. आपका पहला एजेंट और भरोसे की कमी का पता लगाना

बैनर

आइडिया से लेकर इंटरैक्शन तक

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

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

पहला चरण: स्टार्टर एजेंट की जांच करना

सबसे पहले, हम अपने पहले एजेंट के लिए टेंप्लेट देखते हैं. इसमें एक बेसिक स्ट्रक्चर होता है. इसमें प्लेसहोल्डर होते हैं, जिन्हें हम अगले चरणों में पूरा करेंगे.

👉 फ़ाइल खोलें

charity_advisor/simple_agent/agent.py

में दिखती हैं.

आपको ये चीज़ें दिखेंगी:

"""
A simple agent that can research charities using Google Search.
"""

# MODULE_3_STEP_2_IMPORT_COMPONENTS


simple_agent = Agent(
    name="SimpleAgent",
    model="gemini-2.5-flash",
    
    # MODULE_3_STEP_3_WRITE_INSTRUCTION
    instruction="""""",
    
    # MODULE_3_STEP_4_ADD_TOOLS
    tools=[]
)

ध्यान दें कि प्लेसहोल्डर टिप्पणियां एक पैटर्न को फ़ॉलो करती हैं: MODULE_3_STEP_X_DESCRIPTION. हम इन मार्कर को बदल देंगे, ताकि अपने एजेंट को बेहतर बनाया जा सके.

दूसरा चरण: ज़रूरी कॉम्पोनेंट इंपोर्ट करना

Agent क्लास को इंस्टैंशिएट करने या google_search टूल का इस्तेमाल करने से पहले, हमें उन्हें अपनी फ़ाइल में इंपोर्ट करना होगा.

👉 ढूंढें:

# MODULE_3_STEP_2_IMPORT_COMPONENTS

👉 उस एक लाइन को इससे बदलें:

from google.adk.agents import Agent
from google.adk.tools import google_search

अब हमारी फ़ाइल में Agent क्लास और google_search टूल उपलब्ध हैं.

तीसरा चरण: एजेंट के लिए निर्देश लिखना

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

👉 ढूंढें:

# MODULE_3_STEP_3_WRITE_INSTRUCTION
instruction="""""",

👉 उन दो लाइनों को इससे बदलें:

instruction="""You are a helpful research assistant. When a user asks you to find information about charities,
use the google_search tool to find the most relevant and up-to-date results from the web.
Synthesize the search results into a helpful summary.""",

चौथा चरण: खोज टूल जोड़ना

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

👉 ढूंढें:

# MODULE_3_STEP_4_ADD_TOOLS
tools=[]

👉 उन दो लाइनों को इससे बदलें:

tools=[google_search]

पांचवां चरण: अपने एजेंट की पूरी तरह से पुष्टि करना

टेस्ट करने से पहले, आइए पुष्टि कर लें कि सभी ज़रूरी चीज़ें मौजूद हैं.

👉 आपका पूरा

charity_advisor/simple_agent/agent.py

फ़ाइल अब ऐसी दिखनी चाहिए:

"""
A simple agent that can research charities using Google Search.
"""

from google.adk.agents import Agent
from google.adk.tools import google_search


simple_agent = Agent(
    name="SimpleAgent",
    model="gemini-2.5-flash",
    instruction="""You are a helpful research assistant. When a user asks you to find information about charities,
use the google_search tool to find the most relevant and up-to-date results from the web.
Synthesize the search results into a helpful summary.""",
    tools=[google_search]
)

छठा चरण: एजेंट को टेस्ट करना - भरोसे से जुड़ी कमियों का पता लगाना

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

पहला टेस्ट: डिस्कवरी से जुड़ी समस्या

👉 अपने Cloud Shell टर्मिनल में, यह कमांड चलाएं:

adk run charity_advisor/simple_agent

आपको इस तरह का आउटपुट दिखेगा:

INFO:google.adk.agents:Loading agent from charity_advisor/simple_agent
INFO:google.adk.agents:Agent 'SimpleAgent' ready

[user]:

[user]: प्रॉम्प्ट अब आपके इनपुट का इंतज़ार कर रहा है.

👉 [user]: प्रॉम्प्ट पर, यह टाइप करें:

Can you find me a verified, highly-rated charity for children's literacy?

👉 Enter दबाएं और जवाब देखें.

कुछ समय बाद, एजेंट खोज के नतीजों को इस तरह के जवाब में बदल देगा:

वेब पर की गई खोज के आधार पर, बच्चों को पढ़ना-लिखना सिखाने के लिए काम करने वाली कुछ जानी-मानी चैरिटी रीडिंग इज़ फ़ंडामेंटल और रूम टू रीड हैं. इनकी स्थिति और रेटिंग की पुष्टि करने के लिए, अक्सर Charity Navigator और GuideStar जैसे सोर्स का सुझाव दिया जाता है. मुझे Reddit जैसे फ़ोरम पर कई ऑनलाइन चर्चाएं भी मिलीं. इनमें लोग, साक्षरता से जुड़े छोटे-छोटे स्थानीय प्रोग्राम के साथ अपने निजी अनुभव शेयर करते हैं.

आइए, इसका विश्लेषण करते हैं. क्या एजेंट ने हमारी समस्या हल कर दी है?

❌ नहीं. इसमें, मॉड्यूल 1 में बताए गए इंसानों के अनुभव को पूरी तरह से दोहराया गया है. इसने "Googling it" की प्रोसेस को अपने-आप पूरा कर दिया है. साथ ही, "analysis paralysis" की समस्या को हमें वापस सौंप दिया है.

इससे भरोसे से जुड़ी पहली समस्या का पता चलता है: भरोसेमंद डेटा की कमी.

एजेंट, ओपन वेब पर खोज कर रहा है. इसका मतलब है कि:

  • ✅ इसने नतीजे तुरंत दिखाए (उपयोगकर्ता अनुभव को बेहतर बनाया गया है)
  • ❌ इसमें ज़्यादा रेटिंग वाले संगठनों के साथ-साथ Reddit पर हुई चर्चाओं (भरोसेमंद स्रोत नहीं) को भी शामिल किया गया है
  • ❌ यह जांच की गई और संभावित धोखाधड़ी वाली चैरिटी के बीच अंतर नहीं कर सकता (पुष्टि नहीं की गई)
  • ❌ इसमें हमसे, अभी दी गई जानकारी की पुष्टि करने के लिए कहा जा रहा है (ज़िम्मेदारी वापस सौंपना)

दूसरा टेस्ट: लागू करने से जुड़ी समस्या

अब दूसरा ज़रूरी टेस्ट. [user]: प्रॉम्प्ट पर, दान देने की कोशिश करें:

Okay, please donate $50 to Room to Read for me.

एजेंट, माफ़ी मांगते हुए जवाब देगा और अपनी सीमाओं के बारे में बताएगा:

हम समझते हैं कि आपको दान करना है. यह बहुत अच्छी बात है! हालांकि, हम एक रिसर्च असिस्टेंट हैं और हमारे पास वित्तीय लेन-देन को मैनेज करने या पेमेंट प्रोसेस करने की सुविधा नहीं है. दान करने के लिए, आपको सीधे Room to Read की आधिकारिक वेबसाइट पर जाना होगा.

यह दूसरा और उतना ही अहम "अहा!" पल होता है.

एजेंट पर न सिर्फ़ सही चैरिटी खोजने के लिए भरोसा नहीं किया जा सकता, बल्कि दान करने के लिए भी भरोसा नहीं किया जा सकता.

👉 दबाएं

Ctrl+C

पर क्लिक करें.

दो अंतरों को विज़ुअलाइज़ किया गया

भरोसे से जुड़ी समस्या

आपने अभी क्या सीखा

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

मास्टर किए गए मुख्य कॉन्सेप्ट

✅ एजेंट क्लास:

  • ADK का मुख्य बिल्डिंग ब्लॉक
  • इसमें एलएलएम की तर्क क्षमता (दिमाग) को टूल (हाथ) के साथ जोड़ा जाता है
  • मॉडल, निर्देश, और टूल के साथ कॉन्फ़िगर किया गया

✅ फ़ोल्डर के हिसाब से स्ट्रक्चर:

  • हर एजेंट अपने फ़ोल्डर में होता है
  • ADK, agent_folder/agent.py को ढूंढता है
  • adk run agent_folder के साथ चलें

✅ टूल की सूची:

  • एजेंट की क्षमताओं के बारे में बताता है
  • एलएलएम यह तय करता है कि टूल का इस्तेमाल कब और कैसे करना है
  • इसमें अलग-अलग कार्रवाइयों के लिए कई टूल शामिल हो सकते हैं

✅ निर्देश वाला प्रॉम्प्ट:

  • यह एजेंट के व्यवहार को नौकरी की जानकारी की तरह गाइड करता है
  • भूमिका, ट्रिगर, कार्रवाइयां, और आउटपुट फ़ॉर्मैट के बारे में बताता है
  • टूल का सही तरीके से इस्तेमाल करने के लिए ज़रूरी है

✅ भरोसे से जुड़ी समस्या:

  • खोज के नतीजे में अंतर: बिना जांच किए गए सोर्स, अलग-अलग क्वालिटी
  • लागू करने में अंतर: सुरक्षित सुविधाएं उपलब्ध नहीं हैं, सहमति नहीं ली गई है, ऑडिट ट्रेल नहीं है

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

अगले मॉड्यूल में, हम AP2 के भूमिका के आधार पर तय किए गए आर्किटेक्चर को लागू करके, समाधान बनाना शुरू करेंगे.

आइए, पहला एजेंट बनाएं और भूमिकाओं को अलग-अलग करने की सुविधा का इस्तेमाल करें.

4. शॉपिंग एजेंट बनाना - भूमिका के आधार पर खोज करना

बैनर

भरोसे की बुनियाद: भूमिकाओं का बंटवारा

पिछले मॉड्यूल में, आपने देखा कि सामान्य कामों के लिए इस्तेमाल किया जाने वाला एक एजेंट, दो मामलों में काम नहीं कर पाता: यह भरोसेमंद जानकारी नहीं दे पाता और सुरक्षित लेन-देन नहीं कर पाता. अब हम इन समस्याओं को हल करना शुरू करेंगे. इसके लिए, हम एजेंट पेमेंट्स प्रोटोकॉल के पहले सिद्धांत, भूमिका के आधार पर आर्किटेक्चर को लागू करेंगे.

कोई भी कोड लिखने से पहले, आइए समझते हैं कि यह सिद्धांत क्यों ज़रूरी है.

AP2 सिद्धांत: भूमिकाओं का बंटवारा

"हर काम करने वाले" एजेंट से जुड़ी समस्या

मान लें कि आपने एक व्यक्ति को अपना वित्तीय सलाहकार, अकाउंटेंट, और निवेश ब्रोकर नियुक्त किया है. क्या यह सुविधाजनक है? हाँ. क्या यह सुरक्षित है? बिलकुल नहीं। इनमें ये शामिल हो सकते हैं:

  • निवेश के लक्ष्य (सलाहकार की भूमिका)
  • आपके खातों का ऐक्सेस (लेखाकार की भूमिका)
  • आपके पैसे ट्रांसफ़र करने का अधिकार (ब्रोकर की भूमिका)

अगर इस व्यक्ति के खाते से कोई समझौता किया जाता है या उससे कोई गलती होती है, तो सब कुछ जोखिम में पड़ जाता है.

AP2 का समाधान: एक एजेंट, एक काम

AP2, ट्रस्ट बाउंड्री बनाने के लिए, समस्याओं को बांटने के सिद्धांत का पालन करता है:

वास्तुकला

यह ज़रूरी क्यों है:

  • ✅ सुरक्षित दायरा: अगर Shopping Agent से छेड़छाड़ की जाती है, तो हमलावर पेमेंट के क्रेडेंशियल ऐक्सेस नहीं कर सकता
  • ✅ निजता: क्रेडेंशियल प्रोवाइडर को, खरीदारी से जुड़ी आपकी बातचीत कभी नहीं दिखती
  • ✅ अनुपालन: पेमेंट डेटा को अलग रखने पर, पीसीआई-डीएसएस की ज़रूरी शर्तों को पूरा करना आसान हो जाता है
  • ✅ ज़िम्मेदारी: हर चरण के लिए ज़िम्मेदारी तय करना

एजेंट आपस में कैसे कम्यूनिकेट करते हैं: स्टेट को शेयर किए गए नोटपैड के तौर पर इस्तेमाल करना

एजेंट एक-दूसरे के डेटा को सीधे तौर पर ऐक्सेस नहीं कर सकते. इसलिए, वे शेयर किए गए स्टेट के ज़रिए कम्यूनिकेट करते हैं. इसे एक व्हाइटबोर्ड की तरह समझें, जिस पर सभी एजेंट लिख सकते हैं और पढ़ सकते हैं:

# Shopping Agent writes:
state["intent_mandate"] = {
    "natural_language_description": "Donate $50 to Room to Read",
    "merchants": ["Room to Read"],
    "intent_expiry": "2024-11-07T15:32:16Z",
    "amount": 50.0
}

# Merchant Agent reads:
intent = state["intent_mandate"]
charity_name = intent["merchants"][0]
amount = intent["amount"]
# Creates CartMandate based on IntentMandate...

# Credentials Provider reads:
cart_mandate = state["cart_mandate"]
# Processes payment...

इस तरह, हम मिलकर काम करने की सुविधा देते हुए, भरोसे की सीमाओं को बनाए रखते हैं.

हमारा पहला एजेंट: शॉपिंग एजेंट

Shopping Agent की ज़िम्मेदारी आसान और खास होती है:

  1. हमारे भरोसेमंद डेटाबेस से क्वेरी करने के लिए, find_charities टूल का इस्तेमाल करें
  2. उपयोगकर्ता को विकल्प दिखाना
  3. IntentMandate बनाने और उसे सेव करने के लिए, save_user_choice टूल का इस्तेमाल करें
  4. अगले एजेंट (कारोबारी या कंपनी) को सौंपना

हो गया. इसमें पेमेंट की प्रोसेस और कार्ट बनाने की सुविधा नहीं होती. इसमें सिर्फ़ प्रॉडक्ट खोजने और उन्हें किसी दूसरे प्लैटफ़ॉर्म पर भेजने की सुविधा होती है.

आइए, इसे सिलसिलेवार तरीके से बनाते हैं.

पहला चरण: इनपुट की पुष्टि करने वाला हेल्पर जोड़ना

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

👉 खोलें

charity_advisor/tools/charity_tools.py

आपको सबसे ऊपर find_charities फ़ंक्शन (पहले से पूरा हो चुका है) दिखेगा. नीचे की ओर स्क्रोल करके, ये विकल्प ढूंढें:

# MODULE_4_STEP_1_ADD_VALIDATION_HELPER

👉 उस एक लाइन को इससे बदलें:

def _validate_charity_data(charity_name: str, charity_ein: str, amount: float) -> tuple[bool, str]:
    """
    Validates charity selection data before saving to state.
    
    This helper function performs basic validation to ensure data quality
    before it gets passed to other agents in the pipeline.
    
    Args:
        charity_name: Name of the selected charity
        charity_ein: Employer Identification Number (should be format: XX-XXXXXXX)
        amount: Donation amount in USD
        
    Returns:
        (is_valid, error_message): Tuple where is_valid is True if all checks pass,
                                    and error_message contains details if validation fails
    """
    # Validate charity name
    if not charity_name or not charity_name.strip():
        return False, "Charity name cannot be empty"
    
    # Validate EIN format (should be XX-XXXXXXX)
    if not charity_ein or len(charity_ein) != 10 or charity_ein[2] != '-':
        return False, f"Invalid EIN format: {charity_ein}. Expected format: XX-XXXXXXX"
    
    # Validate amount
    if amount <= 0:
        return False, f"Donation amount must be positive, got: ${amount}"
    
    if amount > 1_000_000:
        return False, f"Donation amount exceeds maximum of $1,000,000: ${amount}"
    
    # All checks passed
    return True, ""

दूसरा चरण: IntentMandate Creation Helper जोड़ना

अब हम AP2 IntentMandate स्ट्रक्चर बनाने वाले हेल्पर को बनाते हैं. यह AP2 में पुष्टि किए जा सकने वाले तीन क्रेडेंशियल में से एक है.

👉 उसी फ़ाइल में, ये ढूंढें:

# MODULE_4_STEP_2_ADD_INTENTMANDATE_CREATION_HELPER

👉 उस एक लाइन को इससे बदलें:

def _create_intent_mandate(charity_name: str, charity_ein: str, amount: float) -> dict:
    """
    Creates an IntentMandate - AP2's verifiable credential for user intent.
    
    This function uses the official Pydantic model from the `ap2` package
    to create a validated IntentMandate object before converting it to a dictionary.
    
    Args:
        charity_name: Name of the selected charity
        charity_ein: Employer Identification Number
        amount: Donation amount in USD
        
    Returns:
        Dictionary containing the IntentMandate structure per AP2 specification
    """
    from datetime import datetime, timedelta, timezone
    from ap2.types.mandate import IntentMandate
    
    # Set the expiry for the intent
    expiry = datetime.now(timezone.utc) + timedelta(hours=1)
    
    # Step 1: Instantiate the Pydantic model with official AP2 fields
    intent_mandate_model = IntentMandate(
        user_cart_confirmation_required=True,
        natural_language_description=f"Donate ${amount:.2f} to {charity_name}",
        merchants=[charity_name],
        skus=None,
        requires_refundability=False,
        intent_expiry=expiry.isoformat()
    )
    
    # Step 2: Convert the validated model to a dictionary for state storage
    intent_mandate_dict = intent_mandate_model.model_dump()
    
    # Step 3: Add the codelab's custom fields to the dictionary
    timestamp = datetime.now(timezone.utc)
    intent_mandate_dict.update({
        "timestamp": timestamp.isoformat(),
        "intent_id": f"intent_{charity_ein.replace('-', '')}_{int(timestamp.timestamp())}",
        "charity_ein": charity_ein,
        "amount": amount,
        "currency": "USD"
    })
    
    return intent_mandate_dict

तीसरा चरण: IntentMandate की मदद से, स्टेट हैंडऑफ़ टूल बनाना

अब हम IntentMandate बनाने वाले टूल को बनाएंगे और उसे स्टेट में सेव करेंगे.

👉 उसी फ़ाइल में, नीचे की ओर स्क्रोल करके

save_user_choice

फ़ंक्शन का इस्तेमाल करें. ढूंढें:

# MODULE_4_STEP_3_COMPLETE_SAVE_TOOL

👉 उस एक लाइन को इससे बदलें:

    # Validate inputs before creating IntentMandate
    is_valid, error_message = _validate_charity_data(charity_name, charity_ein, amount)
    if not is_valid:
        logger.error(f"Validation failed: {error_message}")
        return {"status": "error", "message": error_message}
    
    # Create AP2 IntentMandate using our updated helper function
    intent_mandate = _create_intent_mandate(charity_name, charity_ein, amount)
    
    # Write the IntentMandate to shared state for the next agent
    tool_context.state["intent_mandate"] = intent_mandate
    
    logger.info(f"Successfully created IntentMandate and saved to state")
    logger.info(f"Intent ID: {intent_mandate['intent_id']}")
    logger.info(f"Intent expires: {intent_mandate['intent_expiry']}")
    
    # Return success confirmation
    return {
        "status": "success",
        "message": f"Created IntentMandate: ${amount:.2f} donation to {charity_name} (EIN: {charity_ein})",
        "intent_id": intent_mandate["intent_id"],
        "expiry": intent_mandate["intent_expiry"]
    }

चौथा चरण: डिसप्ले फ़ॉर्मैटिंग हेल्पर जोड़ना

एजेंट बनाने से पहले, एक और हेल्पर जोड़ते हैं. यह हेल्पर, चैरिटी के डेटा को ऐसे फ़ॉर्मैट में बदलता है जिसे उपयोगकर्ता आसानी से समझ सकें.

👉 स्क्रोल करके ये ढूंढें:

# MODULE_4_STEP_4_ADD_FORMATTING_HELPER

👉 उस एक लाइन को इससे बदलें:

def _format_charity_display(charity: dict) -> str:
    """
    Formats a charity dictionary into a user-friendly display string.
    
    This helper function demonstrates how to transform structured data
    into readable text for the user.
    
    Args:
        charity: Dictionary containing charity data (name, ein, mission, rating, efficiency)
        
    Returns:
        Formatted string suitable for display to the user
    """
    name = charity.get('name', 'Unknown')
    ein = charity.get('ein', 'N/A')
    mission = charity.get('mission', 'No mission statement available')
    rating = charity.get('rating', 0.0)
    efficiency = charity.get('efficiency', 0.0)
    
    # Format efficiency as percentage
    efficiency_pct = int(efficiency * 100)
    
    # Build formatted string
    display = f"""
**{name}** (EIN: {ein})
⭐ Rating: {rating}/5.0
💰 Efficiency: {efficiency_pct}% of funds go to programs
📋 Mission: {mission}
    """.strip()
    
    return display

पांचवां चरण: शॉपिंग एजेंट बनाना - कॉम्पोनेंट इंपोर्ट करना

हमारे टूल अब पूरी तरह से तैयार हैं. आइए, अब हम एक ऐसा एजेंट बनाते हैं जो इनका इस्तेमाल करेगा.

👉 खोलें

charity_advisor/shopping_agent/agent.py

आपको प्लेसहोल्डर टिप्पणियों वाला टेंप्लेट दिखेगा. आइए, इसे सिलसिलेवार तरीके से बनाते हैं.

👉 ढूंढें:

# MODULE_4_STEP_5_IMPORT_COMPONENTS

👉 उस एक लाइन को इससे बदलें:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from charity_advisor.tools.charity_tools import find_charities, save_user_choice

छठा चरण: एजेंट के लिए निर्देश लिखना

निर्देश में, हम एजेंट के काम के बारे में जानकारी और उसके वर्कफ़्लो के बारे में बताते हैं. यह काफ़ी ज़रूरी है. खराब तरीके से लिखे गए निर्देश की वजह से, भरोसेमंद नतीजे नहीं मिलते.

👉 ढूंढें:

# MODULE_4_STEP_6_WRITE_INSTRUCTION
instruction="""""",

👉 उन दो लाइनों को इससे बदलें:

    instruction="""You are a research specialist helping users find verified charities.

Your workflow:

1. When the user describes what cause they want to support (e.g., "education", "health", "environment"),
   use the find_charities tool to search our vetted database.

2. Present the results clearly. The tool returns formatted charity information that you should
   show to the user.

3. When the user selects a charity and specifies an amount, use the save_user_choice tool
   to create an IntentMandate and record their decision. You MUST call save_user_choice with:
   - charity_name: The exact name of the chosen charity
   - charity_ein: The EIN of the chosen charity  
   - amount: The donation amount in dollars (as a number, not a string)

4. After successfully saving, inform the user:
   - That you've created an IntentMandate (mention the intent ID if provided)
   - When the intent expires
   - That you're passing their request to the secure payment processor

IMPORTANT BOUNDARIES:
- Your ONLY job is discovery and creating the IntentMandate
- You do NOT process payments
- You do NOT see the user's payment methods
- You do NOT create cart offers (that's the Merchant Agent's job)
- After calling save_user_choice, your work is done

WHAT IS AN INTENTMANDATE:
An IntentMandate is a structured record of what the user wants to do. It includes:
- Natural language description ("Donate $50 to Room to Read")
- Which merchants can fulfill it
- When the intent expires
- Whether user confirmation is required

This is the first of three verifiable credentials in our secure payment system.

If the user asks you to do anything related to payment processing, politely explain that
you don't have that capability and that their request will be handled by the appropriate
specialist agent.""",

सातवां चरण: एजेंट में टूल जोड़ना

अब एजेंट को दोनों टूल का ऐक्सेस देते हैं.

👉 ढूंढें:

# MODULE_4_STEP_7_ADD_TOOLS

👉 उन दो लाइनों को इससे बदलें:

    tools=[
        FunctionTool(func=find_charities),
        FunctionTool(func=save_user_choice)
    ]

आठवां चरण: अपने एजेंट की पुष्टि करना

आइए, देखते हैं कि सब कुछ सही तरीके से कनेक्ट किया गया है या नहीं.

👉 आपका पूरा

charity_advisor/shopping_agent/agent.py

अब ऐसा दिखेगा:

"""
Shopping Agent - Finds charities from a trusted database and saves the user's choice.
This agent acts as our specialized "Research Analyst."
"""

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from charity_advisor.tools.charity_tools import find_charities, save_user_choice


shopping_agent = Agent(
    name="ShoppingAgent",
    model="gemini-2.5-pro",
    description="Finds and recommends vetted charities from a trusted database, then creates an IntentMandate capturing the user's donation intent.",
    instruction="""You are a research specialist helping users find verified charities.

Your workflow:

1. When the user describes what cause they want to support (e.g., "education", "health", "environment"),
   use the find_charities tool to search our vetted database.

2. Present the results clearly. The tool returns formatted charity information that you should
   show to the user.

3. When the user selects a charity and specifies an amount, use the save_user_choice tool
   to create an IntentMandate and record their decision. You MUST call save_user_choice with:
   - charity_name: The exact name of the chosen charity
   - charity_ein: The EIN of the chosen charity  
   - amount: The donation amount in dollars (as a number, not a string)

4. After successfully saving, inform the user:
   - That you've created an IntentMandate (mention the intent ID if provided)
   - When the intent expires
   - That you're passing their request to the secure payment processor

IMPORTANT BOUNDARIES:
- Your ONLY job is discovery and creating the IntentMandate
- You do NOT process payments
- You do NOT see the user's payment methods
- You do NOT create cart offers (that's the Merchant Agent's job)
- After calling save_user_choice, your work is done

WHAT IS AN INTENTMANDATE:
An IntentMandate is a structured record of what the user wants to do. It includes:
- Natural language description ("Donate $50 to Room to Read")
- Which merchants can fulfill it
- When the intent expires
- Whether user confirmation is required

This is the first of three verifiable credentials in our secure payment system.

If the user asks you to do anything related to payment processing, politely explain that
you don't have that capability and that their request will be handled by the appropriate
specialist agent.""",
    tools=[
        FunctionTool(func=find_charities),
        FunctionTool(func=save_user_choice)
    ]
)

✅ बहुत बढ़िया! आपने प्रोडक्शन-क्वालिटी वाला, AP2 के मुताबिक काम करने वाला एजेंट बनाया है. इसमें ये सुविधाएं शामिल हैं:

  • इनपुट की पुष्टि करना
  • AP2 Pydantic मॉडल का इस्तेमाल करके, IntentMandate को सही तरीके से बनाना
  • फ़ॉर्मैट किया गया आउटपुट
  • भूमिका की सीमाओं के बारे में साफ़ तौर पर बताना
  • ज़्यादा जानकारी
  • गड़बड़ी ठीक करना

नौवां चरण: Shopping Agent को टेस्ट करना

आइए, पुष्टि करें कि हमारा एजेंट सही तरीके से काम करता है, सही IntentMandates बनाता है, और अपनी सीमाओं का पालन करता है.

👉 Cloud Shell टर्मिनल में, यह कमांड चलाएं:

adk run charity_advisor/shopping_agent

आपको [user]: प्रॉम्प्ट दिखेगा.

पहला टेस्ट: भरोसेमंद डेटाबेस की मदद से खोज करना

👉 टाइप:

I want to donate to an education charity. What are my options?

कुछ समय बाद, एजेंट जवाब देगा. _format_charity_display की मदद से, नतीजों को बेहतर तरीके से फ़ॉर्मैट किया गया है:

हमें अपने डेटाबेस में, शिक्षा के क्षेत्र में काम करने वाली तीन ऐसी चैरिटी मिली हैं जिनकी पुष्टि हो चुकी है:

Room to Read (ईआईएन: 77-0479905)
⭐ रेटिंग: 4.9/5.0
💰 दक्षता: 88% फ़ंड, प्रोग्राम पर खर्च किया जाता है
📋 मिशन: शिक्षा में साक्षरता और लैंगिक समानता पर फ़ोकस करके, कम आय वाले समुदायों के लाखों बच्चों की ज़िंदगी को बेहतर बनाना.

Teach For America (ईआईएन: 13-3541913)
⭐ रेटिंग: 4.7/5.0
💰 दक्षता: 81% फ़ंड, प्रोग्राम के लिए इस्तेमाल किया जाता है
📋 मिशन: मुश्किलों का सामना कर रहे बच्चों के लिए शिक्षा के अवसर बढ़ाना.

टेक एजुकेशन अलायंस (ईआईएन: 45-2345678)
⭐ रेटिंग: 4.8/5.0
💰 दक्षता: 92% फ़ंड प्रोग्राम के लिए इस्तेमाल किया जाता है
📋 मिशन: यह संगठन, कंप्यूटर साइंस की शिक्षा को उन स्कूलों तक पहुंचाता है जहां इसकी पहुंच कम है.

आपको किस चैरिटी को सपोर्ट करना है और आपको कितना दान करना है?

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

दूसरा टेस्ट: उपयोगकर्ता के चुने गए विकल्प को रिकॉर्ड करना और IntentMandate बनाना

👉 टाइप:

I'll donate $50 to Room to Read.

आपको एजेंट को सही पैरामीटर के साथ save_user_choice टूल को कॉल करते हुए दिखना चाहिए. AP2 मॉडल का इस्तेमाल करके IntentMandate बनाने की सुविधा की वजह से, आपको ज़्यादा व्यवस्थित जवाब मिलेगा:

बढ़िया! मैंने आपके दान के लिए एक IntentMandate बनाया है:

इंटेंट की जानकारी:

  • इंटेंट आईडी: intent_774795905_1730927536
  • रकम: Room to Read को 5,000 रुपये (ईआईएन: 77-0479905)
  • समयसीमा खत्म होने की तारीख: 2024-11-07T15:32:16Z (एक घंटे में)

इस IntentMandate से, दान करने के आपके इरादे का पता चलता है. साथ ही, इसमें कुछ शर्तें भी शामिल होती हैं, ताकि यह पक्का किया जा सके कि लेन-देन सुरक्षित तरीके से प्रोसेस किया गया है. अब हम इस जानकारी को पेमेंट प्रोसेस करने वाली सुरक्षित कंपनी को भेज रहे हैं, ताकि वह आपको औपचारिक ऑफ़र दे सके और आपका दान पूरा कर सके.

पर्दे के पीछे, कई काम एक साथ होते हैं:

  1. _validate_charity_data() इनपुट की पुष्टि की गई
  2. _create_intent_mandate() ने स्ट्रक्चर बनाने के लिए, AP2 Pydantic मॉडल का इस्तेमाल किया:
   # Created and validated via Pydantic
   intent_mandate_model = IntentMandate(
       user_cart_confirmation_required=True,
       natural_language_description="Donate $50.00 to Room to Read",
       merchants=["Room to Read"],
       skus=None,
       requires_refundability=False,
       intent_expiry="2024-11-07T15:32:16Z"
   )
   
   # Converted to dict and extended with custom fields
   intent_mandate_dict = intent_mandate_model.model_dump()
   intent_mandate_dict.update({
       "charity_ein": "77-0479905",
       "amount": 50.0,
       "currency": "USD"
   })
  1. इस टूल ने सिर्फ़ IntentMandate को शेयर की गई स्थिति में लिखा है:
   state["intent_mandate"] = intent_mandate_dict
  1. एलएलएम को, इंटेंट की जानकारी के साथ पूरा होने का मैसेज मिला
  2. एलएलएम ने उपयोगकर्ता के लिए फ़ाइनल मैसेज लिखा है

यह IntentMandate अब कारोबारी या कंपनी के एजेंट (मॉड्यूल 5) के लिए उपलब्ध है. कारोबारी या कंपनी, IntentMandate से दान का नाम और रकम की जानकारी निकालेगी. साथ ही, यह पुष्टि करेगी कि इसकी समयसीमा खत्म नहीं हुई है.

तीसरा टेस्ट: पुष्टि की प्रक्रिया जारी है

आइए, पुष्टि करने वाले हेल्पर की मदद से यह पता लगाएं कि वह गलत इनपुट का पता लगाता है या नहीं.

👉 टाइप:

I'll donate -$25 to Room to Read.

एजेंट को अमान्य रकम का पता लगाना चाहिए:

मुझे यह समस्या आ रही है: दान की रकम पॉज़िटिव होनी चाहिए, लेकिन मुझे यह मिला: $-25.0

कृपया दान की रकम डालें. इसके बाद, मैं आपके लिए IntentMandate बनाऊंगा.

यह डिफ़ेंसिव प्रोग्रामिंग का एक उदाहरण है. हमारे _validate_charity_data हेल्पर ने, अमान्य डेटा को सिस्टम में शामिल होने से रोका. साथ ही, गलत तरीके से बनाए गए IntentMandate को भी रोका.

चौथी जांच: ट्रस्ट बाउंड्री की पुष्टि करना

👉 एजेंट से पेमेंट प्रोसेस करने के लिए कहें:

Now process my credit card payment.

एजेंट को अपनी भूमिका के दायरे में रहकर, अनुरोध अस्वीकार करना चाहिए:

मेरे पास पेमेंट प्रोसेस करने की सुविधा नहीं है. यह मेरे काम का हिस्सा नहीं है. मेरा काम, पुष्टि की गई चैरिटी ढूंढने और IntentMandate बनाने में आपकी मदद करना है. इससे आपके दान करने के इरादे के बारे में पता चलता है.

आपका IntentMandate पहले ही बनाया जा चुका है और इसे पेमेंट प्रोसेस करने वाली हमारी सुरक्षित कंपनी को भेज दिया गया है. कारोबारी या कंपनी का एजेंट, एक ऑफ़िशियल ऑफ़र (CartMandate) बनाएगा. इसके बाद, क्रेडेंशियल प्रोवाइडर आपकी साफ़ तौर पर दी गई सहमति के साथ, पेमेंट को प्रोसेस करेगा.

यह ट्रस्ट बाउंड्री का इस्तेमाल करने का तरीका है. एजेंट को पता है कि उसके पास पेमेंट के डेटा को मैनेज करने का अधिकार नहीं है. साथ ही, निर्देश में साफ़ तौर पर बताया गया है कि उसे उपयोगकर्ताओं को इस बारे में बताना है. इसके अलावा, उसे उपयोगकर्ताओं को IntentMandate के कॉन्सेप्ट के बारे में भी बताना है.

👉 दबाएं

Ctrl+C

पर क्लिक करें.

आपने अभी-अभी क्या बनाया

आपने AP2 के आर्किटेक्चर का पहला हिस्सा लागू कर दिया है. साथ ही, AP2 के Pydantic मॉडल का इस्तेमाल करके, IntentMandate को सही तरीके से बनाया है.

मास्टर किए गए मुख्य कॉन्सेप्ट

✅ भूमिका के हिसाब से आर्किटेक्चर:

  • हर एजेंट का काम साफ़ तौर पर तय होता है
  • एजेंट, शेयर किए गए डेटा के ज़रिए कम्यूनिकेट करते हैं, न कि सीधे तौर पर ऐक्सेस करके
  • ट्रस्ट बाउंड्री की वजह से, किसी खाते के साथ समझौता होने का असर सीमित हो जाता है

✅ IntentMandate (AP2 Credential #1):

  • पुष्टि करने के लिए, AP2 Pydantic के आधिकारिक मॉडल का इस्तेमाल करके बनाया गया
  • उपयोगकर्ता के मकसद को स्ट्रक्चर्ड तरीके से कैप्चर करना
  • इसमें सुरक्षा के लिए समयसीमा खत्म होने की जानकारी शामिल होती है (इससे रीप्ले अटैक को रोका जा सकता है)
  • इससे पाबंदियों (कारोबारी या कंपनियां, रिफ़ंड की सुविधा, पुष्टि) के बारे में पता चलता है
  • लोगों के लिए, बोलचाल की भाषा में जानकारी
  • एजेंट के लिए मशीन से पढ़ा जा सकने वाला
  • डिक्शनरी में बदलने से पहले मॉडल की पुष्टि की गई

✅ शेयर की गई यादों के तौर पर स्थिति:

  • tool_context.state एक "नोटपैड" है, जिसे सभी एजेंट ऐक्सेस कर सकते हैं
  • स्टेट में लिखना = पुष्टि किए जा सकने वाले क्रेडेंशियल उपलब्ध कराना
  • रीडिंग फ़्रॉम स्टेट = क्रेडेंशियल का इस्तेमाल किया जा रहा है और उनकी पुष्टि की जा रही है
  • डाउनस्ट्रीम एजेंट, क्रेडेंशियल से अपनी ज़रूरत की जानकारी निकालते हैं

✅ FunctionTool:

  • यह Python फ़ंक्शन को एलएलएम-कॉल किए जा सकने वाले टूल में बदलता है
  • एलएलएम को समझने के लिए, docstrings और टाइप हिंट पर निर्भर करता है
  • यह सुविधा, अपने-आप शुरू हो जाती है
  • टूल कंपोज़िशन: छोटे और खास टूल > बड़े टूल

✅ एजेंट के लिए निर्देश:

  • वर्कफ़्लो के लिए सिलसिलेवार दिशा-निर्देश
  • साफ़ तौर पर बताई गई सीमाएं ("ऐसा न करें...")
  • गड़बड़ियों को रोकने के लिए पैरामीटर की खास बातें
  • तकनीकी परिभाषाएं (IntentMandate क्या है)
  • कभी-कभार होने वाले मामलों को हैंडल करना (कब क्या कहना है...)

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

अगले मॉड्यूल में, हम Merchant Agent बनाएंगे, ताकि IntentMandate मिल सके और दूसरा पुष्टि किया जा सकने वाला क्रेडेंशियल: CartMandate बनाया जा सके.

शॉपिंग एजेंट ने एक IntentMandate बनाया है. इसमें उपयोगकर्ता के इंटेंट की जानकारी शामिल है और इसकी समयसीमा खत्म हो जाती है. अब हमें एक ऐसे एजेंट की ज़रूरत है जो उस क्रेडेंशियल को पढ़े, पुष्टि करे कि वह मान्य है, और एक ऐसा आधिकारिक ऑफ़र बनाए जिस पर हस्ताक्षर किया गया हो. इसमें यह लिखा हो: "मैं, कारोबारी या कंपनी, इस कीमत पर सामान बेचूंगी और उसे डिलीवर करूंगी."

आइए, कारोबारी या कंपनी के एजेंट का खाता बनाएं और दूसरे AP2 क्रेडेंशियल का इस्तेमाल करके देखें.

5. कारोबारी या कंपनी के एजेंट को बनाना - ऑफ़र बाइंड करना और CartMandate

बैनर

खोज से लेकर खरीदारी तक

पिछले मॉड्यूल में, आपने शॉपिंग एजेंट बनाया था. यह एक ऐसा एजेंट है जो पुष्टि की गई चैरिटी ढूंढता है और IntentMandate बनाता है. इससे उपयोगकर्ता के इरादे का पता चलता है. अब हमें एक एजेंट की ज़रूरत है, ताकि वह IntentMandate को स्वीकार कर सके और एक औपचारिक, कानूनी तौर पर बाध्यकारी ऑफ़र बना सके.

यहां AP2 का दूसरा सिद्धांत काम करता है: CartMandate के ज़रिए पुष्टि किए जा सकने वाले क्रेडेंशियल.

AP2 सिद्धांत: कार्ट मैंडेट और बाध्यकारी ऑफ़र

हमें कारोबारी या कंपनी की भूमिका क्यों चाहिए

मॉड्यूल 4 में, शॉपिंग एजेंट ने IntentMandate बनाया और उसे इस स्थिति में सेव किया:

state["intent_mandate"] = {
    "natural_language_description": "Donate $50 to Room to Read",
    "merchants": ["Room to Read"],
    "amount": 50.0,
    "intent_expiry": "2024-11-07T15:32:16Z"
}

हालांकि, यह सिर्फ़ उपयोगकर्ता का मकसद है. किसी भी पेमेंट को प्रोसेस करने से पहले, हमें इनकी ज़रूरत होती है:

  • ऑफ़र का ऐसा स्ट्रक्चर जिसे पेमेंट सिस्टम समझ सकें
  • इस बात का सबूत कि कारोबारी या कंपनी इस कीमत पर सामान बेचेगी
  • एक ऐसा कानूनी समझौता जिसे लेन-देन के बीच में बदला नहीं जा सकता
  • इस बात की पुष्टि करना कि इंटेंट की समयसीमा खत्म नहीं हुई है

यह काम कारोबारी या कंपनी के एजेंट का है.

कार्ट मैंडेट क्या है?

CartMandate, AP2 का "डिजिटल शॉपिंग कार्ट" के लिए इस्तेमाल किया जाने वाला शब्द है. यह एक बाध्यकारी ऑफ़र के तौर पर काम करता है. इसे W3C PaymentRequest स्टैंडर्ड के मुताबिक बनाया गया है. इसका मतलब है कि:

  • दुनिया भर में पेमेंट प्रोसेस करने वाली कंपनियां इस फ़ॉर्मैट को पहचानती हैं
  • इसमें लेन-देन की सभी जानकारी, स्टैंडर्ड फ़ॉर्मैट में होती है
  • इसकी पुष्टि करने के लिए, इस पर क्रिप्टोग्राफ़िक हस्ताक्षर किया जा सकता है

इसे ठेकेदार से मिले लिखित कोटेशन की तरह समझें:

  • ❌ बोलकर: "हाँ, मैं यह काम करीब पचास डॉलर में कर सकता हूँ"
  • ✅ लिखित कोटेशन: सामान के हिसाब से लागत, कुल लागत, हस्ताक्षर, तारीख

लिखकर दिया गया कोटेशन मान्य होता है. CartMandate, डिजिटल तौर पर उपलब्ध है.

कार्ट में जोड़ने का इरादा

CartMandate का स्ट्रक्चर

AP2 में CartMandate का एक खास नेस्टेड स्ट्रक्चर होता है:

cart_mandate = {
    "contents": {  # ← AP2 wrapper
        "id": "cart_xyz123",
        "cart_expiry": "2024-11-07T15:47:16Z",
        "merchant_name": "Room to Read",
        "user_cart_confirmation_required": False,
        
        "payment_request": {  # ← W3C PaymentRequest nested inside
            "method_data": [...],
            "details": {...},
            "options": {...}
        }
    },
    "merchant_authorization": "SIG_a3f7b2c8"  # ← Merchant signature
}

तीन मुख्य कॉम्पोनेंट:

1. contents - यह कार्ट रैपर है. इसमें ये शामिल हैं:

  • कार्ट आईडी और समयसीमा खत्म होने की तारीख
  • व्यापारी का नाम
  • W3C PaymentRequest

2. payment_request (contents फ़ील्ड में) - क्या खरीदा जा रहा है:

  • method_data: पेमेंट के स्वीकार किए गए तरीके
  • जानकारी: आइटम और कुल
  • विकल्प: शिपिंग, खरीदार की जानकारी देने से जुड़ी ज़रूरी शर्तें

3. merchant_authorization - क्रिप्टोग्राफ़िक हस्ताक्षर

कारोबारी या कंपनी के हस्ताक्षर: प्रतिबद्धता का सबूत

कारोबारी या कंपनी के हस्ताक्षर ज़रूरी हैं. इससे यह साबित होता है कि:

  • यह ऑफ़र, मंज़ूरी पा चुके किसी कारोबारी या कंपनी ने दिया है
  • कारोबारी या कंपनी, इस कीमत पर प्रॉडक्ट बेचने के लिए सहमत हो
  • ऑफ़र बनाए जाने के बाद से उसमें कोई बदलाव नहीं किया गया है

प्रोडक्शन में, यह पीकेआई (पब्लिक की इन्फ़्रास्ट्रक्चर) या JWT (JSON वेब टोकन) का इस्तेमाल करके क्रिप्टोग्राफ़िक हस्ताक्षर होगा. हमारा मकसद शिक्षा से जुड़ी वर्कशॉप है. इसलिए, हम SHA-256 हैश का इस्तेमाल करके इस प्रोसेस को दिखाएंगे.

# Production (real signature):
signature = sign_with_private_key(cart_data, merchant_private_key)

# Workshop (simulated signature):
cart_hash = hashlib.sha256(cart_json.encode()).hexdigest()
signature = f"SIG_{cart_hash[:16]}"

हमारा मकसद: कारोबारी एजेंट बनाना

कारोबारी या कंपनी का एजेंट:

  1. राज्य से IntentMandate पढ़ें (Shopping Agent ने क्या लिखा)
  2. पुष्टि करें कि इंटेंट की समयसीमा खत्म नहीं हुई है
  3. दान करने वाली संस्था का नाम, दान की गई रकम, और अन्य जानकारी निकालना
  4. AP2 Pydantic मॉडल का इस्तेमाल करके, W3C के मुताबिक PaymentRequest स्ट्रक्चर बनाना
  5. इसे AP2 के CartMandate में समयसीमा खत्म होने की तारीख के साथ रैप करें
  6. कारोबारी या कंपनी के हस्ताक्षर की नकल जोड़ना
  7. क्रेडेंशियल देने वाले प्रोग्राम (अगला मॉड्यूल) के लिए, CartMandate लिखें

आइए, इसे सिलसिलेवार तरीके से बनाते हैं.

पहला चरण: Expiry Validation Helper जोड़ना

सबसे पहले, कारोबारी या कंपनी से जुड़े टूल की फ़ाइल सेट अप करते हैं. साथ ही, IntentMandate की समयसीमा खत्म होने की पुष्टि करने के लिए, एक हेल्पर जोड़ते हैं.

👉 खोलें

charity_advisor/tools/merchant_tools.py

चलिए, पुष्टि करने की समयसीमा खत्म होने की सुविधा जोड़ते हैं:

👉 ढूंढें:

# MODULE_5_STEP_1_ADD_EXPIRY_VALIDATION_HELPER

👉 उस एक लाइन को इससे बदलें:

def _validate_intent_expiry(intent_expiry_str: str) -> tuple[bool, str]:
    """
    Validates that the IntentMandate hasn't expired.
    
    This is a critical security check - expired intents should not be processed.
    
    Args:
        intent_expiry_str: The ISO 8601 timestamp string from the IntentMandate.
        
    Returns:
        (is_valid, error_message): Tuple indicating if intent is still valid.
    """
    try:
        # The .replace('Z', '+00:00') is for compatibility with older Python versions
        expiry_time = datetime.fromisoformat(intent_expiry_str.replace('Z', '+00:00'))
        now = datetime.now(timezone.utc)
        
        if expiry_time < now:
            return False, f"IntentMandate expired at {intent_expiry_str}"
        
        time_remaining = expiry_time - now
        logger.info(f"IntentMandate valid. Expires in {time_remaining.total_seconds():.0f} seconds")
        
        return True, ""
        
    except (ValueError, TypeError) as e:
        return False, f"Invalid intent_expiry format: {e}"

दूसरा चरण: Signature Generation Helper जोड़ना

अब हम एक हेल्पर फ़ंक्शन बनाएंगे, जो नकली कारोबारी या कंपनी के हस्ताक्षर जनरेट करेगा.

👉 ढूंढें:

# MODULE_5_STEP_2_ADD_SIGNATURE_HELPER

👉 उस एक लाइन को इससे बदलें:

def _generate_merchant_signature(cart_contents: CartContents) -> str:
    """
    Generates a simulated merchant signature for the CartMandate contents.
    
    In production, this would use PKI or JWT with the merchant's private key.
    For this codelab, we use a SHA-256 hash of the sorted JSON representation.
    
    Args:
        cart_contents: The Pydantic model of the cart contents to sign.
        
    Returns:
        Simulated signature string (format: "SIG_" + first 16 chars of hash).
    """
    # Step 1: Dump the Pydantic model to a dictionary. The `mode='json'` argument
    # ensures that complex types like datetimes are serialized correctly.
    cart_contents_dict = cart_contents.model_dump(mode='json')
    
    # Step 2: Use the standard json library to create a stable, sorted JSON string.
    # separators=(',', ':') removes whitespace for a compact and canonical representation.
    cart_json = json.dumps(cart_contents_dict, sort_keys=True, separators=(',', ':'))
    
    # Step 3: Generate SHA-256 hash.
    cart_hash = hashlib.sha256(cart_json.encode('utf-8')).hexdigest()
    
    # Step 4: Create signature in a recognizable format.
    signature = f"SIG_{cart_hash[:16]}"
    
    logger.info(f"Generated merchant signature: {signature}")
    return signature

तीसरा चरण: टूल का हस्ताक्षर बनाएं और उसे सेट अप करें

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

👉 ढूंढें:

# MODULE_5_STEP_3A_CREATE_TOOL_SIGNATURE

👉 उस एक लाइन को इससे बदलें:

async def create_cart_mandate(tool_context: Any) -> Dict[str, Any]:
    """
    Creates a W3C PaymentRequest-compliant CartMandate from the IntentMandate.
    
    This tool reads the IntentMandate from shared state, validates it, and
    creates a formal, signed offer using the official AP2 Pydantic models.
    
    Returns:
        Dictionary containing status and the created CartMandate.
    """
    logger.info("Tool called: Creating CartMandate from IntentMandate")
    
    # MODULE_5_STEP_3B_ADD_VALIDATION_LOGIC

तीसरा बी चरण: पुष्टि करने का लॉजिक जोड़ना

अब AP2 Pydantic मॉडल का इस्तेमाल करके, IntentMandate को पढ़ने और पुष्टि करने के लिए लॉजिक जोड़ते हैं. साथ ही, वह डेटा निकालते हैं जिसकी हमें ज़रूरत है.

👉 ढूंढें:

# MODULE_5_STEP_3B_ADD_VALIDATION_LOGIC

👉 उस एक लाइन को इससे बदलें:

    # 1. Read IntentMandate dictionary from state
    intent_mandate_dict = tool_context.state.get("intent_mandate")
    if not intent_mandate_dict:
        logger.error("No IntentMandate found in state")
        return {
            "status": "error",
            "message": "No IntentMandate found. Shopping Agent must create intent first."
        }
    
    # 2. Parse dictionary into a validated Pydantic model
    try:
        intent_mandate_model = IntentMandate.model_validate(intent_mandate_dict)
    except Exception as e:
        logger.error(f"Could not validate IntentMandate structure: {e}")
        return {"status": "error", "message": f"Invalid IntentMandate structure: {e}"}
    
    # 3. Validate that the intent hasn't expired (CRITICAL security check)
    is_valid, error_message = _validate_intent_expiry(intent_mandate_model.intent_expiry)
    if not is_valid:
        logger.error(f"IntentMandate validation failed: {error_message}")
        return {"status": "error", "message": error_message}
    
    # 4. Extract data. Safely access standard fields from the model, and
    # custom fields (like 'amount') from the original dictionary.
    charity_name = intent_mandate_model.merchants[0] if intent_mandate_model.merchants else "Unknown Charity"
    amount = intent_mandate_dict.get("amount", 0.0)
    
    # MODULE_5_STEP_3C_CREATE_CARTMANDATE_STRUCTURE

तीसरा चरण: कार्ट मैंडेट का स्ट्रक्चर बनाना

अब हम W3C के मुताबिक PaymentRequest स्ट्रक्चर बनाते हैं और इसे Pydantic मॉडल का इस्तेमाल करके AP2 CartMandate में रैप करते हैं.

👉 ढूंढें:

# MODULE_5_STEP_3C_CREATE_CARTMANDATE_STRUCTURE

👉 उस एक लाइन को इससे बदलें:

    # 5. Build the nested Pydantic models for the CartMandate
    timestamp = datetime.now(timezone.utc)
    cart_id = f"cart_{hashlib.sha256(f'{charity_name}{timestamp.isoformat()}'.encode()).hexdigest()[:12]}"
    cart_expiry = timestamp + timedelta(minutes=15)
    
    payment_request_model = PaymentRequest(
        method_data=[PaymentMethodData(
            supported_methods="CARD",
            data={"supported_networks": ["visa", "mastercard", "amex"], "supported_types": ["debit", "credit"]}
        )],
        details=PaymentDetailsInit(
            id=f"order_{cart_id}",
            display_items=[PaymentItem(
                label=f"Donation to {charity_name}",
                amount=PaymentCurrencyAmount(currency="USD", value=amount)  # Pydantic v2 handles float -> str conversion
            )],
            total=PaymentItem(
                label="Total Donation",
                amount=PaymentCurrencyAmount(currency="USD", value=amount)
            )
        ),
        options=PaymentOptions(request_shipping=False)
    )
    
    cart_contents_model = CartContents(
        id=cart_id,
        cart_expiry=cart_expiry.isoformat(),
        merchant_name=charity_name,
        user_cart_confirmation_required=False,
        payment_request=payment_request_model
    )
    
    # MODULE_5_STEP_3D_ADD_SIGNATURE_AND_SAVE

तीसरा चरण: हस्ताक्षर जोड़ें और राज्य के हिसाब से सेव करें

आखिर में, Pydantic मॉडल का इस्तेमाल करके CartMandate पर हस्ताक्षर करें और इसे अगले एजेंट के लिए स्टेट में सेव करें.

👉 ढूंढें:

# MODULE_5_STEP_3D_ADD_SIGNATURE_AND_SAVE

👉 उस एक लाइन को इससे बदलें:

    # 6. Generate signature from the validated Pydantic model
    signature = _generate_merchant_signature(cart_contents_model)
    
    # 7. Create the final CartMandate model, now including the signature
    cart_mandate_model = CartMandate(
        contents=cart_contents_model,
        merchant_authorization=signature
    )
    
    # 8. Convert the final model to a dictionary for state storage and add the custom timestamp
    cart_mandate_dict = cart_mandate_model.model_dump(mode='json')
    cart_mandate_dict["timestamp"] = timestamp.isoformat()
    
    # 9. Write the final dictionary to state
    tool_context.state["cart_mandate"] = cart_mandate_dict
    
    logger.info(f"CartMandate created successfully: {cart_id}")
    
    return {
        "status": "success",
        "message": f"Created signed CartMandate {cart_id} for ${amount:.2f} donation to {charity_name}",
        "cart_id": cart_id,
        "cart_expiry": cart_expiry.isoformat(),
        "signature": signature
    }

चौथा चरण: Merchant Agent - Import Components बनाना

अब हम उस एजेंट को बनाते हैं जो इस टूल का इस्तेमाल करेगा.

👉 खोलें

charity_advisor/merchant_agent/agent.py

आपको प्लेसहोल्डर मार्कर वाला एक टेंप्लेट दिखेगा. आइए, सबसे पहले ज़रूरी चीज़ें इंपोर्ट करें.

👉 ढूंढें:

# MODULE_5_STEP_4_IMPORT_COMPONENTS

👉 उस एक लाइन को इससे बदलें:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from charity_advisor.tools.merchant_tools import create_cart_mandate

पांचवां चरण: कारोबारी या कंपनी के एजेंट के लिए निर्देश लिखना

अब हम ऐसा निर्देश लिखेंगे जिससे एजेंट को यह पता चलेगा कि उसे अपने टूल का इस्तेमाल कब और कैसे करना है.

👉 ढूंढें:

# MODULE_5_STEP_5_WRITE_INSTRUCTION
instruction="""""",

👉 उन दो लाइनों को इससे बदलें:

    instruction="""You are a merchant specialist responsible for creating formal, signed offers (CartMandates).

Your workflow:

1. Read the IntentMandate from shared state.
   The IntentMandate was created by the Shopping Agent and contains:
   - merchants: List of merchant names
   - amount: Donation amount
   - charity_ein: Tax ID
   - intent_expiry: When the intent expires

2. Use the create_cart_mandate tool to create a W3C PaymentRequest-compliant CartMandate.
   This tool will:
   - Validate the IntentMandate hasn't expired (CRITICAL security check)
   - Extract the charity name and amount from the IntentMandate
   - Create a structured offer with payment methods, transaction details, and merchant info
   - Generate a merchant signature to prove authenticity
   - Save the CartMandate to state for the payment processor

3. After creating the CartMandate, inform the user:
   - That you've created a formal, signed offer
   - The cart ID
   - When the cart expires (15 minutes)
   - That you're passing it to the secure payment processor

IMPORTANT BOUNDARIES:
- Your ONLY job is creating signed CartMandates from valid IntentMandates
- You do NOT process payments
- You do NOT see the user's payment methods or credentials
- You do NOT interact with payment networks
- You MUST validate that the IntentMandate hasn't expired before creating a cart
- After calling create_cart_mandate, your work is done

WHAT IS A CARTMANDATE:
A CartMandate is a binding commitment that says:
"I, the merchant, commit to accepting $X for this charity donation, and I prove it with my signature."

This commitment is structured using the W3C PaymentRequest standard and includes:
- Payment methods accepted (card, bank transfer)
- Transaction details (amount, charity name)
- Cart expiry (15 minutes from creation)
- Merchant signature (proof of commitment)

This is the second of three verifiable credentials in our secure payment system.""",

छठा चरण: Merchant Agent में टूल जोड़ना

👉 ढूंढें:

# MODULE_5_STEP_6_ADD_TOOLS
tools=[],

👉 उन दो लाइनों को इससे बदलें:

    tools=[
        FunctionTool(func=create_cart_mandate)
    ],

सातवां चरण: कारोबारी या कंपनी के एजेंट की पुष्टि करना

आइए, पुष्टि करते हैं कि सब कुछ सही तरीके से कनेक्ट किया गया है.

👉 आपका पूरा

charity_advisor/merchant_agent/agent.py

अब ऐसा दिखेगा:

"""
Merchant Agent - Creates W3C-compliant CartMandates with merchant signatures.
This agent acts as our "Contract Creator."
"""

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from charity_advisor.tools.merchant_tools import create_cart_mandate


merchant_agent = Agent(
    name="MerchantAgent",
    model="gemini-2.5-flash",
    description="Creates formal, signed CartMandates for charity donations following W3C PaymentRequest standards.",
    tools=[
        FunctionTool(func=create_cart_mandate)
    ],
    instruction="""You are a merchant specialist responsible for creating formal, signed offers (CartMandates).

Your workflow:

1. Read the IntentMandate from shared state.
   The IntentMandate was created by the Shopping Agent and contains:
   - merchants: List of merchant names
   - amount: Donation amount
   - charity_ein: Tax ID
   - intent_expiry: When the intent expires

2. Use the create_cart_mandate tool to create a W3C PaymentRequest-compliant CartMandate.
   This tool will:
   - Validate the IntentMandate hasn't expired (CRITICAL security check)
   - Extract the charity name and amount from the IntentMandate
   - Create a structured offer with payment methods, transaction details, and merchant info
   - Generate a merchant signature to prove authenticity
   - Save the CartMandate to state for the payment processor

3. After creating the CartMandate, inform the user:
   - That you've created a formal, signed offer
   - The cart ID
   - When the cart expires (15 minutes)
   - That you're passing it to the secure payment processor

IMPORTANT BOUNDARIES:
- Your ONLY job is creating signed CartMandates from valid IntentMandates
- You do NOT process payments
- You do NOT see the user's payment methods or credentials
- You do NOT interact with payment networks
- You MUST validate that the IntentMandate hasn't expired before creating a cart
- After calling create_cart_mandate, your work is done

WHAT IS A CARTMANDATE:
A CartMandate is a binding commitment that says:
"I, the merchant, commit to accepting $X for this charity donation, and I prove it with my signature."

This commitment is structured using the W3C PaymentRequest standard and includes:
- Payment methods accepted (card, bank transfer)
- Transaction details (amount, charity name)
- Cart expiry (15 minutes from creation)
- Merchant signature (proof of commitment)

This is the second of three verifiable credentials in our secure payment system."""
)

✅ चेकपॉइंट: अब आपके पास Pydantic मॉडल का इस्तेमाल करके, AP2 कार्ट मैंडेट बनाने वाला पूरा Merchant Agent है.

आठवां चरण: कारोबारी या कंपनी के एजेंट की जांच करना

अब हम पुष्टि करेंगे कि हमारा एजेंट, हस्ताक्षर के साथ CartMandates को सही तरीके से बनाता है और समयसीमा खत्म होने की पुष्टि करता है.

टेस्ट सेटअप: टेस्ट स्क्रिप्ट चलाना

👉 Cloud Shell टर्मिनल में, यह कमांड चलाएं:

python scripts/test_merchant.py

अनुमानित आउटपुट:

======================================================================
MERCHANT AGENT TEST
======================================================================

Simulated IntentMandate from Shopping Agent:
  charity: Room to Read
  amount: $50.00
  expiry: 2024-11-07T16:32:16Z

----------------------------------------------------------------------
Merchant Agent Response:
----------------------------------------------------------------------
Perfect! I've received your IntentMandate and created a formal, signed offer (CartMandate) for your donation.

**CartMandate Details:**
- **Cart ID**: cart_3b4c5d6e7f8a
- **Donation Amount**: $50.00 to Room to Read
- **Payment Methods Accepted**: Credit/debit cards (Visa, Mastercard, Amex) or bank transfer
- **Cart Expires**: 2024-11-07T15:47:16Z (in 15 minutes)
- **Merchant Signature**: SIG_a3f7b2c8d9e1f4a2

This signed CartMandate proves my commitment to accept this donation amount. I'm now passing this to the secure payment processor to complete your transaction.

======================================================================
CARTMANDATE CREATED:
======================================================================
  ID: cart_3b4c5d6e7f8a
  Amount: 50.00
  Merchant: Room to Read
  Expires: 2024-11-07T15:47:16Z
  Signature: SIG_a3f7b2c8d9e1f4a2
======================================================================

दूसरा टेस्ट: W3C के मानकों के मुताबिक होने की पुष्टि करना

आइए, पुष्टि करें कि CartMandate का स्ट्रक्चर, AP2 और W3C PaymentRequest, दोनों स्टैंडर्ड के मुताबिक है.

👉 पुष्टि करने वाली स्क्रिप्ट चलाएं:

python scripts/validate_cartmandate.py

अनुमानित आउटपुट:

======================================================================
AP2 & W3C PAYMENTREQUEST VALIDATION
======================================================================
✅ CartMandate is AP2 and W3C PaymentRequest compliant

Structure validation passed:
  ✓ AP2 'contents' wrapper present
  ✓ AP2 'merchant_authorization' signature present
  ✓ cart_expiry present
  ✓ payment_request nested inside contents
  ✓ method_data present and valid
  ✓ details.total.amount present with currency and value
  ✓ All required W3C PaymentRequest fields present
======================================================================

आपने अभी-अभी क्या बनाया

आपने सही स्ट्रक्चर, समयसीमा खत्म होने की पुष्टि, और कारोबारी या कंपनी के हस्ताक्षर के लिए, Pydantic मॉडल का इस्तेमाल करके AP2 के CartMandate को लागू कर लिया है.

मास्टर किए गए मुख्य कॉन्सेप्ट

✅ CartMandate (AP2 Credential #2):

  • AP2 के आधिकारिक Pydantic मॉडल का इस्तेमाल करके बनाया गया
  • AP2 स्ट्रक्चर, जिसमें कॉन्टेंट रैपर शामिल है
  • W3C PaymentRequest में नेस्ट किया गया
  • कार्ट में जोड़ी गई चीज़ें ऑर्डर करने की समयसीमा खत्म हो गई है (इरादे से कम)
  • कारोबारी या कंपनी के हस्ताक्षर, कानूनी तौर पर बाध्यकारी प्रतिबद्धता के लिए
  • मॉडल की पुष्टि करने से, स्पेसिफ़िकेशन के मुताबिक काम करने की पुष्टि होती है

✅ समयसीमा खत्म होने की पुष्टि:

  • राज्य से IntentMandate पढ़ा जा रहा है
  • IntentMandate.model_validate() की मदद से स्ट्रक्चर की पुष्टि की जा रही है
  • ISO 8601 टाइमस्टैंप पार्स करना
  • मौजूदा समय से तुलना करना
  • सुरक्षा से जुड़ी ऐसी सुविधा जो पुरानी प्रोसेसिंग को रोकती है

✅ कारोबारी या कंपनी का हस्ताक्षर:

  • इससे यह साबित होता है कि आप भरोसेमंद हैं और आपने वादे के मुताबिक काम किया है
  • पुष्टि किए गए Pydantic मॉडल से जनरेट किया गया
  • कैननिकल यूआरएल दिखाने के लिए, model_dump(mode='json') का इस्तेमाल करता है
  • शिक्षा के लिए SHA-256 की मदद से सिम्युलेट किया गया
  • प्रोडक्शन में पीकेआई/JWT का इस्तेमाल किया जाता है
  • यह कुकी, कॉन्टेंट मॉडल पर हस्ताक्षर करती है, न कि डिक्शनरी पर

✅ W3C PaymentRequest:

  • AP2 के PaymentRequest Pydantic मॉडल का इस्तेमाल करके बनाया गया
  • पेमेंट के डेटा के लिए इंडस्ट्री स्टैंडर्ड
  • AP2 स्ट्रक्चर में नेस्ट किया गया है
  • इसमें method_data, details, options शामिल हैं
  • यह कुकी, अलग-अलग सिस्टम के साथ काम करने की सुविधा चालू करती है

✅ मॉडल के साथ क्रेडेंशियल चेन:

  • Shopping → IntentMandate (validated)
  • कारोबारी या कंपनी, IntentMandate → CartMandate पढ़ती है (दोनों मॉडल की पुष्टि हो गई है)
  • क्रेडेंशियल देने वाला प्रोग्राम, CartMandate → PaymentMandate को पढ़ेगा
  • हर चरण में, Pydantic का इस्तेमाल करके पिछले क्रेडेंशियल की पुष्टि की जाती है

✅ मॉडल-ड्रिवन डेवलपमेंट:

  • model_validate() के ज़रिए इनपुट की पुष्टि करना
  • टाइप-सेफ़ कंस्ट्रक्शन
  • model_dump() के ज़रिए अपने-आप क्रम से लगाना
  • प्रोडक्शन के लिए तैयार पैटर्न

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

अगले मॉड्यूल में, हम सुरक्षित तरीके से पेमेंट प्रोसेस करने के लिए क्रेडेंशियल प्रोवाइडर बनाएंगे.

कारोबारी या कंपनी के एजेंट ने AP2 मॉडल का इस्तेमाल करके, एक ऐसा ऑफ़र बनाया है जो खरीदार के लिए बाध्यकारी है और उसकी समयसीमा खत्म हो चुकी है. अब हमें एक ऐसे एजेंट की ज़रूरत है जो CartMandate को पढ़ सके, उपयोगकर्ता की सहमति ले सके, और पेमेंट कर सके.

क्रेडेंशियल देने वाला प्रोग्राम बनाते हैं और AP2 क्रेडेंशियल चेन को पूरा करते हैं.

6. क्रेडेंशियल देने वाला प्रोग्राम बनाना - सुरक्षित तरीके से पेमेंट करना

बैनर

ऑफ़र को लिंक करने से लेकर पेमेंट पूरा करने तक

मॉड्यूल 5 में, आपने Merchant Agent बनाया था. यह एक विशेषज्ञ है, जो IntentMandates को पढ़ता है. साथ ही, यह पुष्टि करता है कि वे खत्म नहीं हुए हैं. इसके अलावा, यह कारोबारी या कंपनी के हस्ताक्षर वाले CartMandates बनाता है. अब हमें एक ऐसे एजेंट की ज़रूरत है जो उस CartMandate को स्वीकार करे और पेमेंट को प्रोसेस करे.

यहां AP2 का तीसरा और आखिरी सिद्धांत काम करता है: PaymentMandate के ज़रिए सुरक्षित तरीके से पेमेंट करना.

AP2 सिद्धांत: पेमेंट मैंडेट और पेमेंट पूरा करना

हमें क्रेडेंशियल देने वाले की भूमिका क्यों चाहिए

मॉड्यूल 5 में, कारोबारी या कंपनी के एजेंट ने CartMandate बनाया और उसे इस स्थिति में सेव किया:

state["cart_mandate"] = {
    "contents": {
        "id": "cart_abc123",
        "cart_expiry": "2025-11-07:15:47:16Z",
        "payment_request": {
            "details": {
                "total": {
                    "amount": {"currency": "USD", "value": "50.00"}
                }
            }
        }
    },
    "merchant_authorization": "SIG_a3f7b2c8"
}

हालांकि, यह सिर्फ़ एक बाइंडिंग ऑफ़र है. पेमेंट करने से पहले, हमें इनकी ज़रूरत होगी:

  • इस कुकी से यह पुष्टि की जाती है कि कार्ट में जोड़ी गई चीज़ें ऑर्डर करने की समयसीमा खत्म नहीं हुई है
  • पेमेंट करने के लिए उपयोगकर्ता की सहमति
  • ऐसा क्रेडेंशियल जो पेमेंट करने की अनुमति देता है
  • असल में पेमेंट प्रोसेस करना (या हमारी वर्कशॉप के लिए सिम्युलेशन)

यह काम क्रेडेंशियल देने वाली कंपनी का है.

पेमेंट मैंडेट क्या है?

PaymentMandate, AP2 का एक शब्द है. इसका मतलब है कि पेमेंट करने की अनुमति देने वाला फ़ाइनल दस्तावेज़. यह AP2 चेन में तीसरा और आखिरी पुष्टि किया जा सकने वाला क्रेडेंशियल है.

तीनों क्रेडेंशियल को कॉन्ट्रैक्ट पर हस्ताक्षर करने की प्रोसेस की तरह समझें:

  • IntentMandate: "मुझे इसे खरीदने में दिलचस्पी है" (खरीदारी की इच्छा ज़ाहिर करना)
  • CartMandate: "मैं कारोबारी या कंपनी, इस कीमत पर सामान बेचने का ऑफ़र देती हूं" (लिखा गया कोटेशन)
  • PaymentMandate: "I authorize you to charge my payment method" (Signed contract)

तीनों क्रेडेंशियल मौजूद होने पर ही पेमेंट किया जा सकता है.

पूरे क्रेडेंशियल चेन

PaymentMandate का स्ट्रक्चर

AP2 में PaymentMandate का एक खास स्ट्रक्चर होता है:

payment_mandate = {
    "payment_mandate_contents": {  # ← AP2 wrapper
        "payment_mandate_id": "payment_xyz123",
        "payment_details_id": "cart_abc123",  # Links to CartMandate
        "user_consent": True,
        "consent_timestamp": "2025-11-07T15:48:00Z",
        "amount": {
            "currency": "USD",
            "value": "50.00"
        },
        "merchant_name": "Room to Read"
    },
    "agent_present": True,  # Human-in-the-loop flow
    "timestamp": "2025-11-07T15:48:00Z"
}

मुख्य कॉम्पोनेंट:

1. payment_mandate_contents - यह अनुमति देने वाला रैपर है. इसमें यह जानकारी शामिल होती है:

  • payment_mandate_id: यूनीक आइडेंटिफ़ायर
  • payment_details_id: CartMandate से वापस लिंक करता है
  • user_consent: Whether user approved
  • रकम: पेमेंट की रकम (CartMandate से निकाली गई)

2. agent_present - यह पैरामीटर बताता है कि बातचीत में एजेंट मौजूद है या नहीं

3. timestamp - When authorization was created

हमारा मकसद: क्रेडेंशियल देने वाले एक्सटेंशन को बनाना

क्रेडेंशियल देने वाली कंपनी:

  1. स्टेट से CartMandate पढ़ें (कारोबारी या कंपनी के एजेंट ने क्या लिखा है)
  2. AP2 Pydantic मॉडल का इस्तेमाल करके, पुष्टि करें कि कार्ट की समयसीमा खत्म नहीं हुई है
  3. नेस्ट किए गए स्ट्रक्चर से पेमेंट की जानकारी निकालना
  4. AP2 मॉडल का इस्तेमाल करके, उपयोगकर्ता की सहमति से पेमेंट मैंडेट बनाना
  5. पेमेंट प्रोसेस करने की सुविधा को सिम्युलेट करें (प्रोडक्शन में, असली पेमेंट एपीआई को कॉल करेगा)
  6. पेमेंट के निर्देश और पेमेंट के नतीजे को राज्य के हिसाब से लिखना

आइए, इसे सिलसिलेवार तरीके से बनाते हैं.

पहला चरण: कार्ट के खत्म होने की पुष्टि करने वाला हेल्पर जोड़ना

सबसे पहले, एक हेल्पर बनाते हैं. यह हेल्पर, CartMandate की समयसीमा खत्म न होने की पुष्टि करता है. ठीक वैसे ही जैसे हमने मॉड्यूल 5 में IntentMandate की समयसीमा खत्म न होने की पुष्टि की थी.

👉 खोलें

charity_advisor/tools/payment_tools.py

चलिए, पुष्टि करने की समयसीमा खत्म होने की सुविधा जोड़ते हैं:

👉 ढूंढें:

# MODULE_6_STEP_1_ADD_CART_EXPIRY_VALIDATION_HELPER

👉 उस एक लाइन को इससे बदलें:

def _validate_cart_expiry(cart: CartMandate) -> tuple[bool, str]:
    """
    Validates that the CartMandate hasn't expired.
    
    This is a critical security check - expired carts should not be processed.
    
    Args:
        cart: The Pydantic CartMandate model to validate.
        
    Returns:
        (is_valid, error_message): Tuple indicating if cart is still valid.
    """
    try:
        expiry_str = cart.contents.cart_expiry
        expiry_time = datetime.fromisoformat(expiry_str.replace('Z', '+00:00'))
        now = datetime.now(timezone.utc)
        
        if expiry_time < now:
            return False, f"CartMandate expired at {expiry_str}"
        
        time_remaining = expiry_time - now
        logger.info(f"CartMandate valid. Expires in {time_remaining.total_seconds():.0f} seconds")
        
        return True, ""
        
    except (ValueError, TypeError, AttributeError) as e:
        return False, f"Invalid cart_expiry format or structure: {e}"

दूसरा चरण: PaymentMandate Creation Helper जोड़ना

अब हम एक हेल्पर बनाएंगे, जो आधिकारिक AP2 Pydantic मॉडल का इस्तेमाल करके PaymentMandate स्ट्रक्चर बनाता है.

👉 ढूंढें:

# MODULE_6_STEP_2_ADD_PAYMENT_MANDATE_CREATION_HELPER

👉 उस एक लाइन को इससे बदलें:

def _create_payment_mandate(cart: CartMandate, consent_granted: bool) -> dict:
    """
    Creates a PaymentMandate using the official AP2 Pydantic models.
    
    It links to the CartMandate and includes user consent status.
    
    Args:
        cart: The validated Pydantic CartMandate model being processed.
        consent_granted: Whether the user has consented to the payment.
        
    Returns:
        A dictionary representation of the final, validated PaymentMandate.
    """
    timestamp = datetime.now(timezone.utc)
    
    # Safely extract details from the validated CartMandate model
    cart_id = cart.contents.id
    merchant_name = cart.contents.merchant_name
    total_item = cart.contents.payment_request.details.total
    
    # Create the nested PaymentResponse model for the mandate
    payment_response_model = PaymentResponse(
        request_id=cart_id,
        method_name="CARD",  # As per the simulated flow
        details={"token": "simulated_payment_token_12345"}
    )
    
    # Create the PaymentMandateContents model
    payment_mandate_contents_model = PaymentMandateContents(
        payment_mandate_id=f"payment_{hashlib.sha256(f'{cart_id}{timestamp.isoformat()}'.encode()).hexdigest()[:12]}",
        payment_details_id=cart_id,
        payment_details_total=total_item,
        payment_response=payment_response_model,
        merchant_agent=merchant_name,
        timestamp=timestamp.isoformat()
    )
    
    # Create the top-level PaymentMandate model
    # In a real system, a user signature would be added to this model
    payment_mandate_model = PaymentMandate(
        payment_mandate_contents=payment_mandate_contents_model
    )
    
    # Convert the final Pydantic model to a dictionary for state storage
    final_dict = payment_mandate_model.model_dump(mode='json')
    
    # Add any custom/non-standard fields required by the codelab's logic to the dictionary
    # The spec does not have these fields, but your original code did. We add them
    # back to ensure compatibility with later steps.
    final_dict['payment_mandate_contents']['user_consent'] = consent_granted
    final_dict['payment_mandate_contents']['consent_timestamp'] = timestamp.isoformat() if consent_granted else None
    final_dict['agent_present'] = True
    
    return final_dict

तीसरा चरण: टूल का हस्ताक्षर बनाएं और उसे सेट अप करें

अब हम मुख्य टूल को धीरे-धीरे बनाना शुरू करते हैं. सबसे पहले, फ़ंक्शन सिग्नेचर और शुरुआती सेटअप.

👉 ढूंढें:

# MODULE_6_STEP_3A_CREATE_TOOL_SIGNATURE

👉 उस एक लाइन को इससे बदलें:

async def create_payment_mandate(tool_context: Any) -> Dict[str, Any]:
    """
    Creates a PaymentMandate and simulates payment processing using Pydantic models.
    
    This tool now reads the CartMandate from state, parses it into a validated model,
    and creates a spec-compliant PaymentMandate.
    """
    logger.info("Tool called: Creating PaymentMandate and processing payment")
    
    # MODULE_6_STEP_3B_VALIDATE_CARTMANDATE

तीसरा चरण: CartMandate की पुष्टि करना

अब AP2 Pydantic मॉडल का इस्तेमाल करके, CartMandate को पढ़ने और उसकी पुष्टि करने का लॉजिक जोड़ते हैं. साथ ही, इसकी समयसीमा खत्म होने की तारीख की जांच करते हैं.

👉 ढूंढें:

# MODULE_6_STEP_3B_VALIDATE_CARTMANDATE

👉 उस एक लाइन को इससे बदलें:

    # 1. Read CartMandate dictionary from state
    cart_mandate_dict = tool_context.state.get("cart_mandate")
    if not cart_mandate_dict:
        logger.error("No CartMandate found in state")
        return { "status": "error", "message": "No CartMandate found. Merchant Agent must create cart first." }
    
    # 2. Parse dictionary into a validated Pydantic model
    try:
        cart_model = CartMandate.model_validate(cart_mandate_dict)
    except Exception as e:
        logger.error(f"Could not validate CartMandate structure: {e}")
        return {"status": "error", "message": f"Invalid CartMandate structure: {e}"}
    
    # 3. Validate that the cart hasn't expired using the Pydantic model
    is_valid, error_message = _validate_cart_expiry(cart_model)
    if not is_valid:
        logger.error(f"CartMandate validation failed: {error_message}")
        return {"status": "error", "message": error_message}
    
    # MODULE_6_STEP_3C_EXTRACT_PAYMENT_DETAILS

तीसरा चरण: नेस्ट किए गए स्ट्रक्चर से पेमेंट की जानकारी निकालना

अब, पुष्टि किए गए CartMandate मॉडल पर नेविगेट करते हैं, ताकि हम पेमेंट की ज़रूरी जानकारी निकाल सकें.

👉 ढूंढें:

# MODULE_6_STEP_3C_EXTRACT_PAYMENT_DETAILS

👉 उस एक लाइन को इससे बदलें:

    # 4. Safely extract data from the validated model
    cart_id = cart_model.contents.id
    merchant_name = cart_model.contents.merchant_name
    amount_value = cart_model.contents.payment_request.details.total.amount.value
    currency = cart_model.contents.payment_request.details.total.amount.currency
    consent_granted = True  # Assume consent for this codelab flow
    
    # MODULE_6_STEP_3D_CREATE_PAYMENTMANDATE_AND_SIMULATE

तीसरा चरण: पेमेंट मैंडेट बनाना और पेमेंट का सिम्युलेशन करना

आखिर में, हम Pydantic पर आधारित हेल्पर का इस्तेमाल करके PaymentMandate बनाएंगे. साथ ही, पेमेंट प्रोसेस करने की प्रोसेस को सिम्युलेट करेंगे और हर चीज़ को स्टेट में सेव करेंगे.

👉 ढूंढें:

# MODULE_6_STEP_3D_CREATE_PAYMENTMANDATE_AND_SIMULATE

👉 उस एक लाइन को इससे बदलें:

    # 5. Create the spec-compliant PaymentMandate using the validated CartMandate model
    payment_mandate_dict = _create_payment_mandate(cart_model, consent_granted)
    
    # 6. Simulate payment processing
    transaction_id = f"txn_{hashlib.sha256(f'{cart_id}{datetime.now(timezone.utc).isoformat()}'.encode()).hexdigest()[:16]}"
    payment_result = {
        "transaction_id": transaction_id,
        "status": "completed",
        "amount": amount_value,
        "currency": currency,
        "merchant": merchant_name,
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "simulation": True
    }
    
    # 7. Write the compliant PaymentMandate dictionary and result to state
    tool_context.state["payment_mandate"] = payment_mandate_dict
    tool_context.state["payment_result"] = payment_result
    
    logger.info(f"Payment processed successfully: {transaction_id}")
    
    return {
        "status": "success",
        "message": f"Payment of {currency} {amount_value:.2f} to {merchant_name} processed successfully",
        "transaction_id": transaction_id,
        "payment_mandate_id": payment_mandate_dict["payment_mandate_contents"]["payment_mandate_id"]
    }

चौथा चरण: क्रेडेंशियल प्रोवाइडर एजेंट बनाना - कॉम्पोनेंट इंपोर्ट करना

अब हम इस टूल का इस्तेमाल करने वाला एजेंट बनाते हैं.

👉 खोलें

charity_advisor/credentials_provider/agent.py

आपको प्लेसहोल्डर मार्कर वाला एक टेंप्लेट दिखेगा. आइए, सबसे पहले ज़रूरी चीज़ें इंपोर्ट करें.

👉 ढूंढें:

# MODULE_6_STEP_4_IMPORT_COMPONENTS

👉 उस एक लाइन को इससे बदलें:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from charity_advisor.tools.payment_tools import create_payment_mandate

पांचवां चरण: क्रेडेंशियल प्रोवाइडर के लिए निर्देश लिखना

अब हम एजेंट को निर्देश देने के लिए एक प्रॉम्प्ट लिखते हैं.

👉 ढूंढें:

# MODULE_6_STEP_5_WRITE_INSTRUCTION
instruction="""""",

👉 उन दो लाइनों को इससे बदलें:

    instruction="""You are a payment specialist responsible for securely processing payments with user consent.

Your workflow:

1. Read the CartMandate from shared state.
   The CartMandate was created by the Merchant Agent and has this structure:
   - contents: AP2 wrapper containing:
     - id: Cart identifier
     - cart_expiry: When the cart expires
     - merchant_name: Who is receiving payment
     - payment_request: W3C PaymentRequest with transaction details
   - merchant_authorization: Merchant's signature

2. Extract payment details from the nested structure:
   - Navigate: cart_mandate["contents"]["payment_request"]["details"]["total"]["amount"]
   - This gives you the currency and value

3. **IMPORTANT - Two-Turn Conversational Confirmation Pattern:**
   Before calling create_payment_mandate, you MUST:
   - Present the payment details clearly to the user
   - Ask explicitly: "I'm ready to process a payment of $X to [Charity Name]. Do you want to proceed with this donation?"
   - WAIT for the user's explicit confirmation (e.g., "yes", "proceed", "confirm")
   - ONLY call create_payment_mandate AFTER receiving explicit confirmation
   - If user says "no" or "cancel", DO NOT call the tool

4. After user confirms, use the create_payment_mandate tool to:
   - Validate the CartMandate hasn't expired (CRITICAL security check)
   - Create a PaymentMandate (the third AP2 credential)
   - Simulate payment processing
   - Record the transaction result

5. After processing, inform the user:
   - That payment was processed successfully (this is a simulation)
   - The transaction ID
   - The amount and merchant
   - That this completes the three-agent AP2 credential chain

IMPORTANT BOUNDARIES:
- Your ONLY job is creating PaymentMandates and processing payments
- You do NOT discover charities (that's Shopping Agent's job)
- You do NOT create offers (that's Merchant Agent's job)
- You MUST validate that the CartMandate hasn't expired before processing
- You MUST get explicit user confirmation before calling create_payment_mandate
- In production, this consent mechanism would be even more robust

WHAT IS A PAYMENTMANDATE:
A PaymentMandate is the final credential that authorizes payment execution. It:
- Links to the CartMandate (proving the merchant's offer)
- Records user consent
- Contains payment details extracted from the CartMandate
- Enables the actual payment transaction

This is the third and final verifiable credential in our secure payment system.

THE COMPLETE AP2 CREDENTIAL CHAIN:
1. Shopping Agent creates IntentMandate (user's intent)
2. Merchant Agent reads IntentMandate, creates CartMandate (merchant's binding offer)
3. You read CartMandate, get user confirmation, create PaymentMandate (authorized payment execution)

Each credential:
- Has an expiry time (security feature)
- Links to the previous credential
- Is validated before the next step
- Creates an auditable chain of trust""",

छठा चरण: क्रेडेंशियल प्रोवाइडर में टूल जोड़ना

👉 ढूंढें:

# MODULE_6_STEP_6_ADD_TOOLS
tools=[],

👉 उन दो लाइनों को इससे बदलें:

    tools=[
        FunctionTool(func=create_payment_mandate)
    ],

सातवां चरण: क्रेडेंशियल की पूरी जानकारी देने वाले व्यक्ति की पुष्टि करना

आइए, पुष्टि करते हैं कि सब कुछ सही तरीके से कनेक्ट किया गया है.

👉 आपका पूरा

charity_advisor/credentials_provider/agent.py

अब ऐसा दिखेगा:

"""
Credentials Provider Agent - Handles payment processing with user consent.
This agent acts as our "Payment Processor."
"""

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from charity_advisor.tools.payment_tools import create_payment_mandate


credentials_provider = Agent(
    name="CredentialsProvider",
    model="gemini-2.5-flash",
    description="Securely processes payments by creating PaymentMandates and executing transactions with user consent.",
    tools=[
        FunctionTool(func=create_payment_mandate)
    ],
    instruction="""You are a payment specialist responsible for securely processing payments with user consent.

Your workflow:

1. Read the CartMandate from shared state.
   The CartMandate was created by the Merchant Agent and has this structure:
   - contents: AP2 wrapper containing:
     - id: Cart identifier
     - cart_expiry: When the cart expires
     - merchant_name: Who is receiving payment
     - payment_request: W3C PaymentRequest with transaction details
   - merchant_authorization: Merchant's signature

2. Extract payment details from the nested structure:
   - Navigate: cart_mandate["contents"]["payment_request"]["details"]["total"]["amount"]
   - This gives you the currency and value

3. **IMPORTANT - Two-Turn Conversational Confirmation Pattern:**
   Before calling create_payment_mandate, you MUST:
   - Present the payment details clearly to the user
   - Ask explicitly: "I'm ready to process a payment of $X to [Charity Name]. Do you want to proceed with this donation?"
   - WAIT for the user's explicit confirmation (e.g., "yes", "proceed", "confirm")
   - ONLY call create_payment_mandate AFTER receiving explicit confirmation
   - If user says "no" or "cancel", DO NOT call the tool

4. After user confirms, use the create_payment_mandate tool to:
   - Validate the CartMandate hasn't expired (CRITICAL security check)
   - Create a PaymentMandate (the third AP2 credential)
   - Simulate payment processing
   - Record the transaction result

5. After processing, inform the user:
   - That payment was processed successfully (this is a simulation)
   - The transaction ID
   - The amount and merchant
   - That this completes the three-agent AP2 credential chain

IMPORTANT BOUNDARIES:
- Your ONLY job is creating PaymentMandates and processing payments
- You do NOT discover charities (that's Shopping Agent's job)
- You do NOT create offers (that's Merchant Agent's job)
- You MUST validate that the CartMandate hasn't expired before processing
- You MUST get explicit user confirmation before calling create_payment_mandate
- In production, this consent mechanism would be even more robust

WHAT IS A PAYMENTMANDATE:
A PaymentMandate is the final credential that authorizes payment execution. It:
- Links to the CartMandate (proving the merchant's offer)
- Records user consent
- Contains payment details extracted from the CartMandate
- Enables the actual payment transaction

This is the third and final verifiable credential in our secure payment system.

THE COMPLETE AP2 CREDENTIAL CHAIN:
1. Shopping Agent creates IntentMandate (user's intent)
2. Merchant Agent reads IntentMandate, creates CartMandate (merchant's binding offer)
3. You read CartMandate, get user confirmation, create PaymentMandate (authorized payment execution)

Each credential:
- Has an expiry time (security feature)
- Links to the previous credential
- Is validated before the next step
- Creates an auditable chain of trust"""
)

✅ चेकपॉइंट: अब आपके पास पूरा क्रेडेंशियल प्रोवाइडर है. इसमें AP2 Pydantic मॉडल का इस्तेमाल करके, CartMandate को सही तरीके से पढ़ा जा सकता है और PaymentMandate बनाया जा सकता है.

आठवां चरण: क्रेडेंशियल प्रोवाइडर की जांच करना

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

👉 Cloud Shell टर्मिनल में, यह कमांड चलाएं:

python scripts/test_credentials_provider.py

अनुमानित आउटपुट:

======================================================================
CREDENTIALS PROVIDER TEST (MOCK - NO CONFIRMATION)
======================================================================

Simulated CartMandate from Merchant Agent:
  - Cart ID: cart_test123
  - Merchant: Room to Read
  - Amount: $50.00
  - Expires: 2025-11-07T15:47:16Z
  - Signature: SIG_test_signature

Calling Credentials Provider to process payment...
======================================================================
INFO:charity_advisor.tools.payment_tools:Tool called: Creating PaymentMandate and processing payment
INFO:charity_advisor.tools.payment_tools:CartMandate valid. Expires in 900 seconds
INFO:charity_advisor.tools.payment_tools:Payment processed successfully: txn_a3f7b2c8d9e1f4a2

======================================================================
CREDENTIALS PROVIDER RESPONSE:
======================================================================
I've successfully processed your payment. Here are the details:

**Payment Completed** (Simulated)
- Transaction ID: txn_a3f7b2c8d9e1f4a2
- Amount: USD 50.00
- Merchant: Room to Read
- Status: Completed

This completes the three-agent AP2 credential chain:
1. ✓ Shopping Agent created IntentMandate (your intent)
2. ✓ Merchant Agent created CartMandate (binding offer)
3. ✓ Credentials Provider created PaymentMandate (payment authorization)

Your donation has been processed securely through our verifiable credential system.

======================================================================
PAYMENTMANDATE CREATED:
======================================================================
  Payment Mandate ID: payment_3b4c5d6e7f8a
  Linked to Cart: cart_test123
  User Consent: True
  Amount: USD 50.00
  Merchant: Room to Read
  Agent Present: True
======================================================================

======================================================================
PAYMENT RESULT:
======================================================================
  Transaction ID: txn_a3f7b2c8d9e1f4a2
  Status: completed
  Amount: USD 50.00
  Merchant: Room to Read
  Simulation: True
======================================================================

नौवां चरण: तीनों एजेंट वाली पाइपलाइन की जांच करना

अब हम तीनों एजेंट को एक साथ काम करते हुए टेस्ट करेंगे!

👉 पूरे पाइपलाइन टेस्ट को चलाएं:

python scripts/test_full_pipeline.py

अनुमानित आउटपुट:

======================================================================
THREE-AGENT PIPELINE TEST (AP2 CREDENTIAL CHAIN)
======================================================================

[1/3] SHOPPING AGENT - Finding charity and creating IntentMandate...
----------------------------------------------------------------------
✓ IntentMandate created
  - Intent ID: intent_774799058_1730927536
  - Description: Donate $75.00 to Room to Read
  - Merchant: Room to Read
  - Amount: $75.0
  - Expires: 2025-11-07T16:32:16Z

[2/3] MERCHANT AGENT - Reading IntentMandate and creating CartMandate...
----------------------------------------------------------------------
✓ CartMandate created
  - ID: cart_3b4c5d6e7f8a
  - Expires: 2025-11-07T15:47:16Z
  - Signature: SIG_a3f7b2c8d9e1f4a2

[3/3] CREDENTIALS PROVIDER - Creating PaymentMandate and processing...
----------------------------------------------------------------------
NOTE: In the web UI, this would show a confirmation dialog
      For this test, consent is automatically granted
✓ Payment processed (SIMULATED)
  - Transaction ID: txn_a3f7b2c8d9e1f4a2
  - Amount: $75.0
  - Status: completed

======================================================================
COMPLETE AP2 CREDENTIAL CHAIN
======================================================================

✓ Credential 1: IntentMandate (User's Intent)
  - Intent ID: intent_774799058_1730927536
  - Description: Donate $75.00 to Room to Read
  - Expiry: 2025-11-07T16:32:16Z

✓ Credential 2: CartMandate (Merchant's Offer)
  - Cart ID: cart_3b4c5d6e7f8a
  - Cart Expiry: 2025-11-07T15:47:16Z
  - Merchant Signature: SIG_a3f7b2c8d9e1f4a2

✓ Credential 3: PaymentMandate (Payment Execution)
  - Payment Mandate ID: payment_3b4c5d6e7f8a
  - Linked to Cart: cart_3b4c5d6e7f8a
  - Agent Present: True

✓ Transaction Result:
  - Transaction ID: txn_a3f7b2c8d9e1f4a2
  - Simulation: True

======================================================================
✅ COMPLETE PIPELINE TEST PASSED
======================================================================

यह AP2 क्रेडेंशियल चेन का पूरा प्रोसेस है!

हर एजेंट:

  1. यह कुकी, स्थिति से क्रेडेंशियल को पढ़ती है
  2. Pydantic मॉडल (स्ट्रक्चर + समयसीमा खत्म होने की तारीख की जांच) का इस्तेमाल करके इसकी पुष्टि करता है
  3. AP2 मॉडल का इस्तेमाल करके, अगला क्रेडेंशियल बनाता है
  4. यह कुकी, अगले एजेंट के लिए स्थिति की जानकारी लिखती है

आपने अभी-अभी क्या बनाया

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

मास्टर किए गए मुख्य कॉन्सेप्ट

✅ PaymentMandate (AP2 Credential #3):

  • AP2 के आधिकारिक Pydantic मॉडल का इस्तेमाल करके बनाया गया
  • पेमेंट करने के लिए, क्रेडेंशियल की पुष्टि करने वाला फ़ाइनल क्रेडेंशियल
  • payment_details_id के ज़रिए CartMandate से लिंक करता है
  • यह कुकी, उपयोगकर्ता की सहमति और टाइमस्टैंप को रिकॉर्ड करती है
  • इसमें CartMandate से निकाली गई पेमेंट की रकम शामिल होती है
  • इसमें ह्यूमन-इन-द-लूप के लिए agent_present फ़्लैग शामिल है
  • मॉडल की पुष्टि करने से, स्पेसिफ़िकेशन के मुताबिक काम करने की पुष्टि होती है

✅ CartMandate से डेटा पढ़ा जा रहा है:

  • CartMandate.model_validate() की मदद से स्ट्रक्चर की पुष्टि करना
  • टाइप-सेफ़ एट्रिब्यूट ऐक्सेस: cart_model.contents.payment_request.details.total.amount
  • AP2 रैपर और W3C स्टैंडर्ड सेपरेशन के बीच का अंतर समझना
  • मॉडल से merchant_name, amount, currency की जानकारी सुरक्षित तरीके से निकालो
  • Pydantic, स्ट्रक्चर से जुड़ी गड़बड़ियों का पता अपने-आप लगाता है

✅ कार्ट में मौजूद आइटम की समयसीमा खत्म होने की पुष्टि:

  • पुष्टि किए गए CartMandate Pydantic मॉडल को स्वीकार करता है
  • cart.contents.cart_expiry से डेटा पढ़ता है (एट्रिब्यूट ऐक्सेस)
  • सुरक्षा से जुड़ी ऐसी सुविधा जो कार्ट को प्रोसेस करने से रोकती है
  • इरादे के मुकाबले कम समय (15 मिनट)

✅ पेमेंट सिम्युलेशन:

  • पेमेंट प्रोसेस करने वाली असली कंपनी का शिक्षा के मकसद से बनाया गया मॉक
  • यह कुकी, लेन-देन आईडी जनरेट करती है
  • यह कुकी, पेमेंट_रिज़ल्ट को state में रिकॉर्ड करती है
  • सिमुलेशन के तौर पर साफ़ तौर पर मार्क किया गया हो (सिमुलेशन: True फ़्लैग)

✅ मॉडल के साथ AP2 चेन पूरी करें:

  • तीन एजेंट, तीन क्रेडेंशियल, तीन Pydantic की पुष्टि
  • हर एजेंट, मॉडल का इस्तेमाल करके पिछले क्रेडेंशियल के स्ट्रक्चर की पुष्टि करता है
  • ऑडिट ट्रेल के लिए, हर क्रेडेंशियल पिछले क्रेडेंशियल से लिंक होता है
  • स्टेट के आधार पर हैंडऑफ़ करने से, भूमिकाओं को अलग-अलग रखा जाता है
  • पूरी चेन में टाइप सेफ़्टी

✅ मॉडल-ड्रिवन डेवलपमेंट:

  • model_validate() के ज़रिए इनपुट की पुष्टि करना
  • नेस्ट किए गए मॉडल के साथ टाइप-सेफ़ कंस्ट्रक्शन
  • model_dump(mode='json') के ज़रिए अपने-आप क्रम से लगाना
  • शुरू से ही प्रोडक्शन के लिए तैयार पैटर्न

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

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

आपने AP2 Pydantic मॉडल का इस्तेमाल करके, तीन बेहतरीन स्पेशलिस्ट एजेंट बनाए हैं. अब हम एक ऐसा कंडक्टर बनाते हैं जो इन सभी को एक साथ जोड़कर, दान करने का आसान अनुभव देता है.

चलिए, ऑर्केस्ट्रेटर बनाते हैं और पूरे सिस्टम को काम करते हुए देखते हैं.

7. ऑर्केस्ट्रेशन - सभी को एक साथ लाना

सीक्वेंशियल पाइपलाइन

स्पेशलिस्ट से लेकर बिना किसी रुकावट के काम करने तक

पिछले मॉड्यूल में, आपने तीन खास एजेंट बनाए थे:

  • Shopping Agent: यह चैरिटी संस्थाएं ढूंढता है और IntentMandate बनाता है
  • कारोबारी या कंपनी का एजेंट: यह IntentMandate से CartMandate बनाता है
  • क्रेडेंशियल देने वाली कंपनी: PaymentMandate बनाती है और पेमेंट प्रोसेस करती है

ये एजेंट, स्वाभाविक रूप से दो चरणों में काम करते हैं:

  • पहला चरण (शॉपिंग): दान के लिए किसी चैरिटी को ढूंढने और चुनने के लिए, कई बार बातचीत करना
  • दूसरा चरण (प्रोसेसिंग): ऑफ़र बनाने और पेमेंट करने की प्रोसेस एक साथ पूरी होगी

हालांकि, फ़िलहाल आपको इन चरणों को मैन्युअल तरीके से खुद ही मैनेज करना होगा.

इस मामले में, ADK के ऑर्केस्ट्रेशन पैटर्न काम आते हैं.

AP2 सिद्धांत: ऑर्केस्ट्रेशन, भरोसे की सीमाओं को लागू करता है

सुरक्षा के लिए ऑर्केस्ट्रेशन क्यों ज़रूरी है

ऑर्केस्ट्रेशन सिर्फ़ सुविधा के बारे में नहीं है, बल्कि आर्किटेक्चर के ज़रिए भरोसे की सीमाओं को लागू करने के बारे में है.

ऑर्केस्ट्रेशन के बिना:

# User could accidentally skip steps or reorder them
shopping_agent.run("Find charity")
# Oops, forgot to create CartMandate!
credentials_provider.run("Process payment")  # No offer to validate!

ऑर्केस्ट्रेशन के साथ:

# Pipeline enforces correct order
donation_processing_pipeline = SequentialAgent(
    sub_agents=[
        merchant_agent,      # Must run first
        credentials_provider # Must run second
    ]
)
# Steps ALWAYS run in order, no skipping allowed

सीक्वेंशियल पाइपलाइन इन बातों की गारंटी देती है:

  • ✅ IntentMandate को CartMandate से पहले बनाया गया हो
  • ✅ पेमेंट प्रोसेस होने से पहले कार्ट मैंडेट बनाया गया हो
  • ✅ हर एजेंट, अपने अलग कॉन्टेक्स्ट में काम करता है
  • ✅ क्रेडेंशियल चेन के ज़रिए, राज्य की जानकारी आगे बढ़ती है

हमारा मकसद: पूरा सिस्टम बनाना

हम दो लेयर बनाएंगे:

लेयर 1: प्रोसेसिंग पाइपलाइन (SequentialAgent)

  • कारोबारी या कंपनी के क्रेडेंशियल → Wires together Merchant
  • दान के लिए किसी संस्था को चुनने के बाद, यह अपने-आप क्रम से चलता है
  • ऑफ़र और पेमेंट को एक साथ पूरा करना

दूसरी लेयर: रूट ऑर्केस्ट्रेटर (उपयोगकर्ता से इंटरैक्ट करने वाला एजेंट)

  • मिलनसार स्वभाव
  • यह कुकी, चैरिटी चुनने के लिए shopping_agent को डेलिगेट करती है
  • IntentMandate बनने के बाद, प्रोसेसिंग पाइपलाइन को डेलिगेट करता है
  • बातचीत और फ़ेज़ ट्रांज़िशन को मैनेज करता है

दो लेयर वाला यह तरीका, नैचुरल फ़्लो से मेल खाता है:

  • खरीदारी का चरण: कई बार बातचीत करना (उपयोगकर्ता ब्राउज़ करता है, सवाल पूछता है, और फ़ैसला लेता है)
  • प्रोसेसिंग का चरण: एटॉमिक एक्ज़ीक्यूशन (ऑफ़र → पेमेंट)

आइए, दोनों को बनाते हैं.

पहला चरण: ऑर्केस्ट्रेशन कॉम्पोनेंट इंपोर्ट करना

सबसे पहले, ज़रूरी इंपोर्ट के साथ ऑर्केस्ट्रेशन फ़ाइल सेट अप करते हैं.

👉 खोलें

charity_advisor/agent.py

चलिए, इंपोर्ट करने से शुरू करते हैं:

👉 ढूंढें:

# MODULE_7_STEP_1_IMPORT_COMPONENTS

👉 उस एक लाइन को इससे बदलें:

from google.adk.agents import Agent, SequentialAgent
from charity_advisor.shopping_agent.agent import shopping_agent
from charity_advisor.merchant_agent.agent import merchant_agent
from charity_advisor.credentials_provider.agent import credentials_provider

दूसरा चरण: प्रोसेसिंग पाइपलाइन बनाना

अब हम ऐसी पाइपलाइन बनाएंगे जो ऑफ़र बनाने और पेमेंट प्रोसेस करने की सुविधा को एक साथ चलाती है.

👉 ढूंढें:

# MODULE_7_STEP_2_CREATE_SEQUENTIAL_PIPELINE

👉 उन दो लाइनों को इससे बदलें:

# Create the donation processing pipeline
# This runs Merchant → Credentials in sequence AFTER charity is selected
donation_processing_pipeline = SequentialAgent(
    name="DonationProcessingPipeline",
    description="Creates signed offer and processes payment after charity is selected",
    sub_agents=[
        merchant_agent,
        credentials_provider
    ]
)

तीसरा चरण: रूट एजेंट का सेटअप बनाना

अब हम उपयोगकर्ता के लिए ऐसा एजेंट बनाते हैं जो दोनों चरणों को व्यवस्थित करता है. हम इसे तीन हिस्सों में बांटकर समझेंगे: सेटअप (3A), निर्देश (3B), और सब-एजेंट (3C).

👉 ढूंढें:

# MODULE_7_STEP_3A_CREATE_ROOT_AGENT_SETUP

👉 उस एक लाइन को इससे बदलें:

# Create the root orchestrator agent
# This is what users interact with directly
root_agent = Agent(
    name="CharityAdvisor",
    model="gemini-2.5-pro",
    description="A friendly charity giving assistant that helps users donate to verified organizations.",
    # MODULE_7_STEP_3B_WRITE_ROOT_AGENT_INSTRUCTION

तीसरा चरण (B): रूट एजेंट के लिए निर्देश लिखना

अब हम ऐसा निर्देश जोड़ते हैं जो दोनों चरणों में, दान से जुड़ी सलाह देने वाले व्यक्ति के व्यवहार को गाइड करता है.

👉 ढूंढें:

# MODULE_7_STEP_3B_WRITE_ROOT_AGENT_INSTRUCTION

👉 उस एक लाइन को इससे बदलें:

    instruction="""You are a helpful and friendly charity giving advisor.

Your workflow has TWO distinct phases:

PHASE 1: CHARITY SELECTION (delegate to shopping_agent)
When a user expresses interest in donating:
1. Delegate to shopping_agent immediately
2. The shopping_agent will:
   - Search for charities matching their cause
   - Present verified options with ratings
   - Engage in conversation (user may ask questions, change their mind)
   - Wait for user to select a specific charity and amount
   - Create an IntentMandate when user decides
3. Wait for shopping_agent to complete

You'll know Phase 1 is complete when shopping_agent's response includes:
- "IntentMandate created" or "Intent ID: intent_xxx" 
- Charity name and donation amount

PHASE 2: PAYMENT PROCESSING (delegate to DonationProcessingPipeline)
After shopping_agent completes:
1. Acknowledge the user's selection naturally:
   "Perfect! Let me process your $X donation to [Charity]..."
2. Delegate to DonationProcessingPipeline
3. The pipeline will automatically:
   - Create signed cart offer (MerchantAgent)
   - Get consent and process payment (CredentialsProvider)
4. After pipeline completes, summarize the transaction

CRITICAL RULES:
- Phase 1 may take multiple conversation turns (this is normal)
- Only proceed to Phase 2 after IntentMandate exists
- Don't rush the user during charity selection
- Don't ask user to "proceed" between phases - transition automatically

EXAMPLE FLOW:
User: "I want to donate to education"
You: [delegate to shopping_agent]
Shopping: "Here are 3 education charities..." [waits]
User: "Tell me more about the first one"
Shopping: "Room to Read focuses on..." [waits]
User: "Great, I'll donate $50 to Room to Read"
Shopping: "IntentMandate created (ID: intent_123)..."
You: "Perfect! Processing your $50 donation to Room to Read..." [delegate to DonationProcessingPipeline]
Pipeline: [creates offer, gets consent, processes payment]
You: "Done! Your donation was processed successfully. Transaction ID: txn_456"

Your personality:
- Warm and encouraging
- Patient during charity selection
- Clear about educational nature
- Smooth transitions between phases""",
# MODULE_7_STEP_3C_ADD_ROOT_AGENT_SUBAGENTS

तीसरा चरण: उप-एजेंट जोड़ना

आखिर में, हम चैरिटी सलाहकार को शॉपिंग एजेंट और प्रोसेसिंग पाइपलाइन, दोनों का ऐक्सेस देते हैं. साथ ही, एजेंट की परिभाषा को बंद करते हैं.

👉 ढूंढें:

# MODULE_7_STEP_3C_ADD_ROOT_AGENT_SUBAGENTS

👉 उस एक लाइन को इससे बदलें:

    sub_agents=[
        shopping_agent,
        donation_processing_pipeline
    ]
)

चौथा चरण: पूरे सिस्टम की पुष्टि करना

आइए, पुष्टि करते हैं कि ऑर्केस्ट्रेशन को सही तरीके से कॉन्फ़िगर किया गया है.

👉 आपका पूरा

charity_advisor/agent.py

अब ऐसा दिखेगा:

"""
Main orchestration: The donation processing pipeline and root orchestrator agent.
"""

from google.adk.agents import Agent, SequentialAgent
from charity_advisor.shopping_agent.agent import shopping_agent
from charity_advisor.merchant_agent.agent import merchant_agent
from charity_advisor.credentials_provider.agent import credentials_provider

# Create the donation processing pipeline
# This runs Merchant → Credentials in sequence AFTER charity is selected
donation_processing_pipeline = SequentialAgent(
    name="DonationProcessingPipeline",
    description="Creates signed offer and processes payment after charity is selected",
    sub_agents=[
        merchant_agent,
        credentials_provider
    ]
)

# Create the root orchestrator agent
# This is what users interact with directly
root_agent = Agent(
    name="CharityAdvisor",
    model="gemini-2.5-flash",
    description="A friendly charity giving assistant that helps users donate to verified organizations.",
    instruction="""You are a helpful and friendly charity giving advisor.

Your workflow has TWO distinct phases:

PHASE 1: CHARITY SELECTION (delegate to shopping_agent)
When a user expresses interest in donating:
1. Delegate to shopping_agent immediately
2. The shopping_agent will:
   - Search for charities matching their cause
   - Present verified options with ratings
   - Engage in conversation (user may ask questions, change their mind)
   - Wait for user to select a specific charity and amount
   - Create an IntentMandate when user decides
3. Wait for shopping_agent to complete

You'll know Phase 1 is complete when shopping_agent's response includes:
- "IntentMandate created" or "Intent ID: intent_xxx" 
- Charity name and donation amount

PHASE 2: PAYMENT PROCESSING (delegate to DonationProcessingPipeline)
After shopping_agent completes:
1. Acknowledge the user's selection naturally:
   "Perfect! Let me process your $X donation to [Charity]..."
2. Delegate to DonationProcessingPipeline
3. The pipeline will automatically:
   - Create signed cart offer (MerchantAgent)
   - Get consent and process payment (CredentialsProvider)
4. After pipeline completes, summarize the transaction

CRITICAL RULES:
- Phase 1 may take multiple conversation turns (this is normal)
- Only proceed to Phase 2 after IntentMandate exists
- Don't rush the user during charity selection
- Don't ask user to "proceed" between phases - transition automatically

EXAMPLE FLOW:
User: "I want to donate to education"
You: [delegate to shopping_agent]
Shopping: "Here are 3 education charities..." [waits]
User: "Tell me more about the first one"
Shopping: "Room to Read focuses on..." [waits]
User: "Great, I'll donate $50 to Room to Read"
Shopping: "IntentMandate created (ID: intent_123)..."
You: "Perfect! Processing your $50 donation to Room to Read..." [delegate to DonationProcessingPipeline]
Pipeline: [creates offer, gets consent, processes payment]
You: "Done! Your donation was processed successfully. Transaction ID: txn_456"

Your personality:
- Warm and encouraging
- Patient during charity selection
- Clear about educational nature
- Smooth transitions between phases""",
    sub_agents=[
        shopping_agent,
        donation_processing_pipeline
    ]
)

पांचवां चरण: पुष्टि करने के लिए कॉलबैक का इस्तेमाल करना (ज़रूरी नहीं है. सातवें चरण पर जाएं)

कॉलबैक

SequentialAgent, एक्ज़ीक्यूशन के क्रम की गारंटी देता है. हालांकि, अगर:

  • Shopping Agent चुपचाप फ़ेल हो जाता है (IntentMandate कभी नहीं बनाया जाता)
  • शॉपिंग और कारोबारी या कंपनी के पेज के बीच एक घंटा बीत गया (इंटेंट खत्म हो गया)
  • स्टेट खराब हो जाता है या मिट जाता है
  • कोई व्यक्ति सीधे तौर पर कारोबारी या कंपनी को कॉल करने की कोशिश करता है, न कि Shopping के ज़रिए

कॉलबैक आर्किटेक्चरल एनफ़ोर्समेंट जोड़ते हैं - ये किसी एजेंट के एलएलएम कॉल शुरू करने से पहले, ज़रूरी शर्तों की पुष्टि करते हैं. यह सुरक्षा की एक लेयर्ड रणनीति है: टूल, एक्ज़ीक्यूशन के दौरान पुष्टि करते हैं, जबकि कॉलबैक, एक्ज़ीक्यूशन से पहले पुष्टि करते हैं.

आइए, हम Merchant और Credentials Provider एजेंट में पुष्टि करने के लिए कॉलबैक जोड़ते हैं.

पांचवां चरण: कारोबारी या कंपनी की पुष्टि करने की सुविधा जोड़ना - इंपोर्ट कॉलबैक टाइप

सबसे पहले, कॉलबैक के लिए ज़रूरी इंपोर्ट जोड़ते हैं.

👉 खोलें

charity_advisor/merchant_agent/agent.py

फ़ाइल में सबसे ऊपर, मौजूदा इंपोर्ट के बाद यह कोड जोड़ें:

from typing import Optional
from datetime import datetime, timezone
from google.adk.agents.callback_context import CallbackContext
from google.genai.types import Content, Part
import logging

logger = logging.getLogger(__name__)

पांचवां चरण: इंटेंट की पुष्टि करने वाला फ़ंक्शन बनाना

अब हम एक कॉलबैक फ़ंक्शन बनाएंगे, जो Merchant Agent के चलने से पहले IntentMandate की पुष्टि करता है.

👉 In

charity_advisor/merchant_agent/agent.py

, इस फ़ंक्शन को

merchant_agent = Agent(...)

definition:

def validate_intent_before_merchant(
    callback_context: CallbackContext,
) -> Optional[Content]:
    """
    Validates IntentMandate exists and hasn't expired before Merchant runs.
    
    This callback enforces that the Shopping Agent completed successfully
    before the Merchant Agent attempts to create a CartMandate.
    
    Returns:
        None: Allow Merchant Agent to proceed normally
        Content: Skip Merchant Agent and return error to user
    """
    state = callback_context.state
    
    # Check credential exists
    if "intent_mandate" not in state:
        logger.error("❌ IntentMandate missing - Shopping Agent may have failed")
        return Content(parts=[Part(text=(
            "Error: Cannot create cart. User intent was not properly recorded. "
            "Please restart the donation process."
        ))])
    
    intent_mandate = state["intent_mandate"]
    
    # Validate expiry (critical security check)
    try:
        expiry_time = datetime.fromisoformat(
            intent_mandate["intent_expiry"].replace('Z', '+00:00')
        )
        now = datetime.now(timezone.utc)
        
        if expiry_time < now:
            logger.error(f"❌ IntentMandate expired at {intent_mandate['intent_expiry']}")
            return Content(parts=[Part(text=(
                "Error: Your donation intent has expired. "
                "Please select a charity again to restart."
            ))])
        
        time_remaining = expiry_time - now
        logger.info(f"✓ IntentMandate validated. Expires in {time_remaining.total_seconds():.0f}s")
        
    except (KeyError, ValueError) as e:
        logger.error(f"❌ Invalid IntentMandate structure: {e}")
        return Content(parts=[Part(text=(
            "Error: Invalid intent data. Please restart the donation."
        ))])
    
    # All checks passed - allow Merchant Agent to proceed
    logger.info(f"✓ Prerequisites met for Merchant Agent: {intent_mandate['intent_id']}")
    return None

5C: कारोबारी या कंपनी के एजेंट को कॉल बैक की सुविधा अटैच करना

अब एजेंट को कॉल बैक करने के लिए कनेक्ट करते हैं.

👉 In

charity_advisor/merchant_agent/agent.py

, में बदलाव करें

merchant_agent = Agent(...)

definition:

एजेंट की परिभाषा में यह लाइन ढूंढें:

merchant_agent = Agent(
    name="MerchantAgent",
    model="gemini-2.5-flash",
    description="Creates formal, signed CartMandates for charity donations following W3C PaymentRequest standards.",

इस लाइन को

description

line:

    before_agent_callback=validate_intent_before_merchant,

अब आपकी एजेंट डेफ़िनिशन ऐसी दिखनी चाहिए:

merchant_agent = Agent(
    name="MerchantAgent",
    model="gemini-2.5-flash",
    description="Creates formal, signed CartMandates for charity donations following W3C PaymentRequest standards.",
    before_agent_callback=validate_intent_before_merchant,
    tools=[
        FunctionTool(func=create_cart_mandate)
    ],
    instruction="""..."""
)

छठा चरण: क्रेडेंशियल देने वाली कंपनी की पुष्टि करना (ज़रूरी नहीं है. सातवें चरण पर जाएं)

एक जैसा पैटर्न - आइए, पेमेंट के चरण के लिए पुष्टि करने की सुविधा जोड़ें.

छठा चरण: कॉल बैक टाइप इंपोर्ट करना

👉 खोलें

charity_advisor/credentials_provider/agent.py

फ़ाइल में सबसे ऊपर, मौजूदा इंपोर्ट के बाद यह कोड जोड़ें:

from typing import Optional
from datetime import datetime, timezone
from google.adk.agents.callback_context import CallbackContext
from google.genai.types import Content, Part
import logging

logger = logging.getLogger(__name__)

छठा चरण (बी): कार्ट की पुष्टि करने वाला फ़ंक्शन बनाना

👉 In

charity_advisor/credentials_provider/agent.py

, इस फ़ंक्शन को

credentials_provider = Agent(...)

definition:

def validate_cart_before_payment(
    callback_context: CallbackContext,
) -> Optional[Content]:
    """
    Validates CartMandate exists and hasn't expired before payment processing.
    
    This callback enforces that the Merchant Agent completed successfully
    before the Credentials Provider attempts to process payment.
    
    Returns:
        None: Allow Credentials Provider to proceed
        Content: Skip payment processing and return error
    """
    state = callback_context.state
    
    # Check credential exists
    if "cart_mandate" not in state:
        logger.error("❌ CartMandate missing - Merchant Agent may have failed")
        return Content(parts=[Part(text=(
            "Error: Cannot process payment. Cart was not properly created. "
            "Please restart the donation process."
        ))])
    
    cart_mandate = state["cart_mandate"]
    
    # Validate AP2 structure
    if "contents" not in cart_mandate:
        logger.error("❌ CartMandate missing AP2 contents wrapper")
        return Content(parts=[Part(text=(
            "Error: Invalid cart structure. Please restart."
        ))])
    
    # Validate expiry
    try:
        contents = cart_mandate["contents"]
        expiry_time = datetime.fromisoformat(
            contents["cart_expiry"].replace('Z', '+00:00')
        )
        now = datetime.now(timezone.utc)
        
        if expiry_time < now:
            logger.error(f"❌ CartMandate expired at {contents['cart_expiry']}")
            return Content(parts=[Part(text=(
                "Error: Your cart has expired (15 minute limit). "
                "Please restart the donation to get a fresh offer."
            ))])
        
        time_remaining = expiry_time - now
        logger.info(f"✓ CartMandate validated. Expires in {time_remaining.total_seconds():.0f}s")
        
    except (KeyError, ValueError) as e:
        logger.error(f"❌ Invalid CartMandate structure: {e}")
        return Content(parts=[Part(text=(
            "Error: Invalid cart data. Please restart the donation."
        ))])
    
    # All checks passed - allow payment processing
    logger.info(f"✓ Prerequisites met for Credentials Provider: {contents['id']}")
    return None

छठा चरण: क्रेडेंशियल देने वाले एक्सटेंशन में कॉलबैक अटैच करना

👉 In

charity_advisor/credentials_provider/agent.py

, में बदलाव करें

credentials_provider = Agent(...)

definition:

एजेंट की परिभाषा में यह लाइन ढूंढें:

credentials_provider = Agent(
    name="CredentialsProvider",
    model="gemini-2.5-flash",
    description="Securely processes payments by creating PaymentMandates and executing transactions with user consent.",

इस लाइन को

description

line:

    before_agent_callback=validate_cart_before_payment,

अब आपकी एजेंट डेफ़िनिशन ऐसी दिखनी चाहिए:

credentials_provider = Agent(
    name="CredentialsProvider",
    model="gemini-2.5-flash",
    description="Securely processes payments by creating PaymentMandates and executing transactions with user consent.",
    before_agent_callback=validate_cart_before_payment,
    tools=[
        FunctionTool(func=create_payment_mandate)
    ],
    instruction="""..."""
)

सातवां चरण: ADK Web UI के साथ टेस्ट करना

अब पुष्टि करने वाले कॉलबैक चालू करके, पूरी तरह से सुरक्षित किए गए सिस्टम की जांच करते हैं.

👉 Cloud Shell टर्मिनल में, यह कमांड चलाएं:

adk web

आपको इस तरह का आउटपुट दिखेगा:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 इसके बाद, अपने ब्राउज़र से ADK के वेब यूज़र इंटरफ़ेस (यूआई) को ऐक्सेस करने के लिए:

Cloud Shell टूलबार (आम तौर पर सबसे ऊपर दाईं ओर) में मौजूद, वेब की झलक आइकॉन (यह आंख या ऐरो वाले स्क्वेयर जैसा दिखता है) से, पोर्ट बदलें को चुनें. पॉप-अप विंडो में, पोर्ट को 8000 पर सेट करें. इसके बाद, "बदलें और झलक देखें" पर क्लिक करें. इसके बाद, Cloud Shell एक नया ब्राउज़र टैब खोलेगा. इसमें ADK का वेब यूज़र इंटरफ़ेस (यूआई) दिखेगा.

webpreview

👉 ड्रॉपडाउन से अपना एजेंट चुनें:

ADK के वेब यूज़र इंटरफ़ेस (यूआई) में, आपको सबसे ऊपर एक ड्रॉपडाउन मेन्यू दिखेगा. सूची में से charity_advisor चुनें.

agent-select

आपको ADK का वेब इंटरफ़ेस दिखेगा. इसमें ये शामिल होंगे:

  • चैट पैनल: यह बाईं ओर होता है. इसका इस्तेमाल बातचीत करने के लिए किया जाता है
  • ट्रेस पैनल: दाईं ओर, निगरानी के लिए (हम इसका इस्तेमाल मॉड्यूल 9 में करेंगे)

पहला टेस्ट: दान करने की प्रोसेस पूरी करना (सामान्य मामला)

👉 चैट इंटरफ़ेस में, यह टाइप करें:

I want to donate to an education charity

पूरी प्रोसेस देखें:

adk web shopping agent

adk web donation processing pipeline

क्या हो रहा है (दाईं ओर मौजूद ट्रेस पैनल में दिखता है):

1. Advisor, ShoppingAgent को डेलिगेट करता है:

  • ShoppingAgent, शिक्षा के लिए काम करने वाली चैरिटी के बारे में खोज करता है
  • आपको पुष्टि किए गए तीन विकल्प और उनकी जानकारी दिखाता है

2. ShoppingAgent के साथ इंटरैक्ट करना (इसमें कई बार लग सकता है):

User: "Tell me more about Room to Read"
Shopping: [explains mission and impact]
User: "I'll donate $50 to Room to Read"

3. ShoppingAgent, IntentMandate बनाता है:

  • यह कुकी, इंटेंट बनाती है और उस पर हस्ताक्षर करती है
  • इस इंटेंट आईडी के साथ पुष्टि की जानकारी दिखाता है

4. सलाहकार को प्रोसेसिंग फ़ेज़ में ले जाया जाता है:

बढ़िया! Room to Read को दिए गए 50 डॉलर के आपके दान को प्रोसेस किया जा रहा है...

5. DonationProcessingPipeline activates:

  • कारोबारी या कंपनी का कॉलबैक, IntentMandate की पुष्टि करता है (✓ पास किया गया) ← नया!
  • कारोबारी या कंपनी का एजेंट, हस्ताक्षर के साथ CartMandate बनाता है
  • क्रेडेंशियल कॉलबैक, CartMandate की पुष्टि करता है (✓ पास किया गया) ← नया!
  • क्रेडेंशियल देने वाली कंपनी, पेमेंट तैयार करती है

6. पेमेंट प्रोसेस:

  • क्रेडेंशियल देने वाली कंपनी, PaymentMandate बनाती है
  • यह कुकी, पेमेंट प्रोसेस करने की प्रोसेस को सिम्युलेट करती है
  • सामान लौटाने के लेन-देन का आईडी

7. सलाहकार की खास जानकारी:

बढ़िया! आपका दान स्वीकार कर लिया गया है! 🎉

जानकारी:

  • रकम: 5,000 रुपये
  • दान: Room to Read (ईआईएन: 77-0479905)
  • लेन-देन आईडी: txn_a3f7b2c8d9e1f4a2

दूसरा टेस्ट: पुष्टि करें कि कॉलबैक में गड़बड़ियां पकड़ी गई हैं या नहीं (ऐडवांस टेस्ट, ज़रूरी नहीं)

क्या आपको यह देखना है कि गड़बड़ियों का पता लगाने के लिए, कॉलबैक कैसे काम करते हैं? आपको मैन्युअल तरीके से स्थिति को खराब करना होगा (ऐडवांस डीबगिंग), लेकिन प्रोडक्शन में, कॉलबैक इन समस्याओं का पता लगा लेंगे:

  • Shopping Agent टूल काम नहीं करता → कारोबारी या कंपनी के कॉलबैक ब्लॉक: "गड़बड़ी: कार्ट नहीं बनाया जा सकता..."
  • दो घंटे बीत जाने पर → कारोबारी या कंपनी के कॉलबैक ब्लॉक हो जाते हैं: "गड़बड़ी: इंटेंट की समयसीमा खत्म हो गई है..."
  • कार्ट की समयसीमा खत्म हो जाती है → क्रेडेंशियल कॉलबैक ब्लॉक करता है: "Error: Cart expired (15 min limit)..."

इन खास मामलों को अब आर्किटेक्चर के हिसाब से लागू किया जाता है. इसके लिए, पुष्टि करने वाले कॉलबैक का इस्तेमाल किया जाता है.

आपने अभी-अभी क्या बनाया

आपने तीन खास एजेंट को एक भरोसेमंद सिस्टम में इंटिग्रेट किया है. साथ ही, आर्किटेक्चर की पुष्टि भी की है.

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

आपने भरोसेमंद एजेंट बनाने की तकनीकी प्रक्रिया पूरी कर ली है:

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

आइए, आपके मज़बूत एजेंट को Google Cloud पर डिप्लॉय करते हैं.

8. डिप्लॉयमेंट

बैनर

दान करने के लिए भरोसेमंद सिस्टम अब तैयार है. इसमें तीन विशेषज्ञ एजेंट स्थानीय स्तर पर काम कर रहे हैं:

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

इस मॉड्यूल में, आपको Google Cloud पर एजेंट को डिप्लॉय करने का तरीका बताया गया है. इसमें निगरानी की सुविधा पहले दिन से ही चालू होती है. डिप्लॉयमेंट के दौरान इस्तेमाल किया जाने वाला --trace_to_cloud फ़्लैग, मॉड्यूल 9 में जवाबदेही के निशान को ट्रैक करने की सुविधा देता है.

डिप्लॉयमेंट के विकल्पों के बारे में जानकारी

ADK में, डिप्लॉयमेंट के लिए कई टारगेट इस्तेमाल किए जा सकते हैं. इनकी जटिलता, सेशन मैनेजमेंट, स्केलिंग, और लागत अलग-अलग होती है:

सिग्नल

स्थानीय (adk web)

Agent Engine

Cloud Run

जटिलता

मिनिमल

कम

मीडियम

सेशन बनाए रखना

सिर्फ़ मेमोरी में (रीस्टार्ट करने पर मिट जाता है)

Vertex AI की ओर से मैनेज किया गया (अपने-आप)

Cloud SQL (PostgreSQL) या इन-मेमोरी

इन्फ़्रास्ट्रक्चर

कोई नहीं (सिर्फ़ डेवलपर मशीन)

पूरी तरह से प्रबंधित

कंटेनर + वैकल्पिक डेटाबेस

कोल्ड स्टार्ट

लागू नहीं

100-500 मि॰से॰

100-2000 मि॰से॰

स्केलिंग

सिंगल इंस्टेंस

ऑटोमैटिक

अपने-आप (शून्य पर)

लागत मॉडल

मुफ़्त (लोकल कंप्यूट)

कंप्यूट के आधार पर

अनुरोध पर आधारित + फ़्री टियर

यूज़र इंटरफ़ेस (यूआई) से जुड़ी सहायता

हां (पहले से मौजूद)

नहीं (सिर्फ़ एपीआई)

हां (--with_ui फ़्लैग के ज़रिए)

Observability Setup

लोकल ट्रेस व्यूअर

--trace_to_cloud की मदद से अपने-आप होने वाला पेमेंट

--trace_to_cloud फ़्लैग की ज़रूरत है

इन स्थितियों में बेहतर है

डेवलपमेंट और टेस्टिंग

प्रोडक्शन एजेंट

प्रोडक्शन एजेंट

सुझाव: दान करने के इस भरोसेमंद सिस्टम के लिए, हमारा सुझाव है कि आप Agent Engine को अपने मुख्य प्रोडक्शन डिप्लॉयमेंट के तौर पर इस्तेमाल करें. इसकी वजह यह है कि यह आपको ये सुविधाएं देता है:

  • पूरी तरह से मैनेज किया गया इंफ़्रास्ट्रक्चर (कंटेनर मैनेज करने की ज़रूरत नहीं)
  • VertexAiSessionService के ज़रिए सेशन को बनाए रखने की सुविधा
  • कोल्ड स्टार्ट के बिना अपने-आप स्केलिंग की सुविधा
  • आसान डिप्लॉयमेंट (इसके लिए, Docker की जानकारी होना ज़रूरी नहीं है)
  • Cloud Trace के साथ इंटिग्रेशन की सुविधा

अन्य विकल्प: Google Kubernetes Engine (GKE)

अगर आपको Kubernetes-लेवल का कंट्रोल, कस्टम नेटवर्किंग या मल्टी-सर्विस ऑर्केस्ट्रेशन की ज़रूरत है, तो GKE डिप्लॉयमेंट का इस्तेमाल करें. इस विकल्प से आपको ज़्यादा से ज़्यादा सुविधाएं मिलती हैं. हालांकि, इसके लिए आपको ऑपरेशनल एक्सपर्ट (क्लस्टर मैनेजमेंट, मेनिफ़ेस्ट, सेवा खाते) की ज़रूरत होती है.

GKE डिप्लॉयमेंट के बारे में इस कोडलैब में नहीं बताया गया है. हालांकि, इसकी पूरी जानकारी ADK GKE डिप्लॉयमेंट गाइड में दी गई है.

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

1. Google Cloud प्रोजेक्ट का सेटअप

आपके पास बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट होना चाहिए. अगर आपके पास कोई खाता नहीं है, तो:

  1. प्रोजेक्ट बनाना: Google Cloud Console
  2. बिलिंग चालू करें: बिलिंग चालू करें
  3. अपना प्रोजेक्ट आईडी नोट करें. प्रोजेक्ट का नाम या नंबर नहीं

2. फिर से पुष्टि करना (ज़रूरी नहीं)

Google Cloud की मदद से पुष्टि करें:

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

YOUR_PROJECT_ID की जगह अपना Google Cloud प्रोजेक्ट आईडी डालें.

पुष्टि करें कि आपने सही तरीके से पुष्टि की है:

gcloud config get-value project
# Should output: YOUR_PROJECT_ID

3. एनवायरमेंट वैरिएबल

अपनी .env फ़ाइल में अपने-आप जानकारी भरने के लिए, इन कमांड का इस्तेमाल करें:

# Get your current Project ID
PROJECT_ID=$(gcloud config get-value project)
STAGING_BUCKET_VALUE="gs://${PROJECT_ID}-staging"
ENV_FILE=".env"

# Check if STAGING_BUCKET is already set in the .env file
if grep -q "^STAGING_BUCKET=" "${ENV_FILE}"; then
  # If it exists, replace the line
  # The sed command finds the line starting with STAGING_BUCKET= and replaces the entire line.
  # Using | as a delimiter to avoid issues with slashes in the bucket name.
  sed -i "s|^STAGING_BUCKET=.*|STAGING_BUCKET=${STAGING_BUCKET_VALUE}|" "${ENV_FILE}"
  echo "Updated STAGING_BUCKET in ${ENV_FILE}"
else
  # If it doesn't exist, add it to the end of the file
  echo "STAGING_BUCKET=${STAGING_BUCKET_VALUE}" >> "${ENV_FILE}"
  echo "Added STAGING_BUCKET to ${ENV_FILE}"
fi

# Verify it was added or updated correctly
echo "Current STAGING_BUCKET setting:"
grep "^STAGING_BUCKET=" "${ENV_FILE}"

आपको यह दिखना चाहिए:

STAGING_BUCKET=gs://your-actual-project-id-staging

अहम जानकारी:

  • YOUR_PROJECT_ID की जगह अपना प्रोजेक्ट आईडी डालें या ऊपर दिए गए निर्देशों का इस्तेमाल करें
  • GOOGLE_CLOUD_LOCATION के लिए, इन देशों और इलाकों में मान्य है एट्रिब्यूट का इस्तेमाल करें
  • डप्लॉयमेंट स्क्रिप्ट चलाने पर, अगर स्टेजिंग बकेट मौजूद नहीं है, तो वह अपने-आप बन जाएगी

4. ज़रूरी एपीआई चालू करना

डप्लॉयमेंट की प्रोसेस के लिए, Google Cloud के कई एपीआई चालू होने चाहिए. इन्हें चालू करने के लिए, यह कमांड चलाएं:

gcloud services enable \
    aiplatform.googleapis.com \
    storage.googleapis.com \
    cloudbuild.googleapis.com \
    cloudtrace.googleapis.com \
    compute.googleapis.com

इस कमांड से ये सुविधाएं चालू हो जाती हैं:

  • AI Platform API - Agent Engine और Vertex AI मॉडल के लिए
  • Cloud Storage API - For staging bucket
  • Cloud Build API - कंटेनर बनाने के लिए (Cloud Run)
  • Cloud Trace API - इससे निगरानी और जवाबदेही से जुड़ी जानकारी मिलती है
  • Compute Engine API - इसका इस्तेमाल सर्विस खाते को मैनेज करने के लिए किया जाता है

पहला चरण: डिप्लॉयमेंट इंफ़्रास्ट्रक्चर को समझना

आपके प्रोजेक्ट में एक यूनिफ़ाइड डिप्लॉयमेंट स्क्रिप्ट (deploy.sh) शामिल है, जो सभी डिप्लॉयमेंट मोड को मैनेज करती है.

👉 डिप्लॉयमेंट स्क्रिप्ट की समीक्षा करें (ज़रूरी नहीं):

cat deploy.sh

यह स्क्रिप्ट, तीन तरह के डिप्लॉयमेंट मोड उपलब्ध कराती है:

  • ./deploy.sh local - इसे मेमोरी में सेव किए गए डेटा के साथ स्थानीय तौर पर चलाएं
  • ./deploy.sh agent-engine - Vertex AI Agent Engine पर डिप्लॉय करें (सुझाया गया)
  • ./deploy.sh cloud-run - Cloud Run पर डिप्लॉय करें. इसमें यूज़र इंटरफ़ेस (यूआई) का इस्तेमाल करना ज़रूरी नहीं है

यह सुविधा कैसे काम करती है:

एजेंट इंजन को डिप्लॉय करने के लिए, स्क्रिप्ट यह काम करती है:

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --staging_bucket=$STAGING_BUCKET \
  --display_name="Charity Advisor" \
  --trace_to_cloud \
  charity_advisor

Cloud Run डिप्लॉयमेंट के लिए, यह कमांड एक्ज़ीक्यूट करता है:

adk deploy cloud_run \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --service_name="charity-advisor" \
  --app_name="charity_advisor" \
  --with_ui \
  --trace_to_cloud \
  charity_advisor

--trace_to_cloud फ़्लैग, दोनों तरह के डिप्लॉयमेंट के लिए ज़रूरी है. यह Cloud Trace इंटिग्रेशन को चालू करता है. इसके बारे में आपको मॉड्यूल 9 में ज़्यादा जानकारी मिलेगी.

दूसरा चरण: एजेंट इंजन रैपर तैयार करना

Agent Engine को एक खास एंट्री पॉइंट की ज़रूरत होती है. यह एंट्री पॉइंट, मैनेज किए गए रनटाइम के लिए आपके एजेंट को रैप करता है. यह फ़ाइल आपके लिए बनाई गई है.

👉 समीक्षा करें

charity_advisor/agent_engine_app.py

:

"""Agent Engine application wrapper.

This file prepares the Charity Advisor agent for deployment to Vertex AI Agent Engine.
"""

from vertexai import agent_engines
from .agent import root_agent

# Wrap the agent in an AdkApp object for Agent Engine deployment
app = agent_engines.AdkApp(
    agent=root_agent,
    enable_tracing=True,  # Enables Cloud Trace integration automatically
)

यह फ़ाइल क्यों ज़रूरी है:

  • Agent Engine को एजेंट की ज़रूरत होती है, जिसे AdkApp ऑब्जेक्ट में रैप किया गया हो
  • enable_tracing=True पैरामीटर, Cloud Trace इंटिग्रेशन को अपने-आप चालू कर देता है
  • इस रैपर का इस्तेमाल, ADK CLI डिप्लॉयमेंट के दौरान करती है
  • यह कुकी, सेशन के अपने-आप बने रहने के लिए VertexAiSessionService को कॉन्फ़िगर करती है

Agent Engine, भरोसेमंद दान सिस्टम के लिए प्रोडक्शन डिप्लॉयमेंट का सुझाव दिया गया है. ऐसा इसलिए, क्योंकि यह पूरी तरह से मैनेज किया गया इंफ़्रास्ट्रक्चर उपलब्ध कराता है. इसमें सेशन को बनाए रखने की सुविधा पहले से मौजूद होती है.

डिप्लॉयमेंट शुरू करना

अपने प्रोजेक्ट के रूट से:

chmod +x deploy.sh
./deploy.sh agent-engine

डिप्लॉयमेंट के चरण

स्क्रिप्ट को इन फ़ेज़ में एक्ज़ीक्यूट होते हुए देखें:

Phase 1: API Enablement
  ✓ aiplatform.googleapis.com
  ✓ storage.googleapis.com
  ✓ cloudbuild.googleapis.com
  ✓ cloudtrace.googleapis.com
  ✓ compute.googleapis.com

Phase 2: IAM Setup
  ✓ Getting project number
  ✓ Granting Storage Object Admin
  ✓ Granting Vertex AI User
  ✓ Granting Cloud Trace Agent

Phase 3: Staging Bucket
  ✓ Creating gs://your-project-id-staging (if needed)
  ✓ Setting permissions

Phase 4: Validation
  ✓ Checking agent.py exists
  ✓ Verifying root_agent defined
  ✓ Checking agent_engine_app.py exists
  ✓ Validating requirements.txt

Phase 5: Build & Deploy
  ✓ Packaging agent code
  ✓ Uploading to staging bucket
  ✓ Creating Agent Engine instance
  ✓ Configuring session persistence
  ✓ Setting up Cloud Trace integration
  ✓ Running health checks

इस प्रोसेस में 5 से 10 मिनट लगते हैं. ऐसा इसलिए, क्योंकि इसमें एजेंट को पैकेज किया जाता है और Vertex AI के इन्फ़्रास्ट्रक्चर पर डिप्लॉय किया जाता है.

अपने एजेंट इंजन का आईडी सेव करना

डिप्लॉयमेंट पूरा होने के बाद:

✅ Agent Engine created successfully!

   Agent Engine ID: 7917477678498709504
   Resource Name: projects/123456789/locations/us-central1/reasoningEngines/7917477678498709504
   Endpoint: https://us-central1-aiplatform.googleapis.com/v1/...

   ⚠️  IMPORTANT: Save the Agent Engine ID from the output above
   Add it to your .env file as:
   AGENT_ENGINE_ID=7917477678498709504

   This ID is required for:
   - Testing the deployed agent
   - Updating the deployment later
   - Accessing logs and traces

अपनी .env फ़ाइल को तुरंत अपडेट करें:

echo "AGENT_ENGINE_ID=7917477678498709504" >> .env

क्या डिप्लॉय किया गया था

अब आपके एजेंट इंजन डिप्लॉयमेंट में ये शामिल हैं:

✅ तीनों एजेंट (शॉपिंग, कारोबारी या कंपनी, क्रेडेंशियल) मैनेज किए गए रनटाइम में काम कर रहे हों
✅ क्रेडेंशियल चेन का पूरा लॉजिक (इरादा → कार्ट → पेमेंट के निर्देश)
✅ उपयोगकर्ता की सहमति लेने का तरीका, जिसमें पुष्टि करने का वर्कफ़्लो शामिल हो
✅ VertexAiSessionService के ज़रिए सेशन को अपने-आप सेव होने की सुविधा चालू हो
✅ Google की ओर से मैनेज किया जाने वाला ऑटो-स्केलिंग इन्फ़्रास्ट्रक्चर मौजूद हो
✅ पूरी जानकारी पाने के लिए, Cloud Trace इंटिग्रेशन मौजूद हो

चौथा चरण: डिप्लॉय किए गए एजेंट की जांच करना

अपने एनवायरमेंट को अपडेट करना

पुष्टि करें कि आपके .env में एजेंट इंजन आईडी शामिल है:

AGENT_ENGINE_ID=7917477678498709504  # From deployment output
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
STAGING_BUCKET=gs://your-project-id-staging

टेस्ट स्क्रिप्ट चलाना

आपके प्रोजेक्ट में, एजेंट इंजन डिप्लॉयमेंट के लिए खास तौर पर एक टेस्ट स्क्रिप्ट शामिल है.

👉 जांच करें:

python scripts/test_deployed_agent.py

अनुमानित आउटपुट

Testing Agent Engine deployment...
Project: your-project-id
Location: us-central1
Agent Engine ID: 7917477678498709504
Endpoint: https://us-central1-aiplatform.googleapis.com/v1/...

Creating session...
✓ Session created: 4857885913439920384

Sending donation query...
✓ Response received:
  Event 1: I'll help you donate $50 to a children's education charity...
  Event 2: Here are some highly-rated children's education charities...
  Event 3: Which charity would you like to support?...

✅ Test completed successfully!

Session ID: 4857885913439920384

This donation generated a trace in Cloud Trace.
View it in Module 9: Observability

To view traces:
https://console.cloud.google.com/traces/list?project=your-project-id

पुष्टि करने के लिए चेकलिस्ट

जांच करने के बाद, पुष्टि करें कि:

✅ एजेंट, क्वेरी के जवाब देता है
✅ तीनों एजेंट एक के बाद एक काम करते हैं (शॉपिंग → कारोबारी या कंपनी → क्रेडेंशियल)
✅ सहमति लेने की प्रोसेस चालू होती है (पुष्टि करने का अनुरोध किया जाता है)
✅ सेशन, सभी अनुरोधों के लिए बना रहता है
✅ पुष्टि करने से जुड़ी कोई गड़बड़ी नहीं होती है
✅ कनेक्शन टाइमआउट नहीं होता है

अगर आपको गड़बड़ियां मिलती हैं, तो:

  • देखें कि एनवायरमेंट वैरिएबल सही तरीके से सेट किए गए हों
  • पुष्टि करें कि एपीआई चालू हैं: gcloud services list --enabled
  • Vertex AI Console में Agent Engine के लॉग देखना
  • पुष्टि करें कि agent_engine_app.py फ़ाइल, आपके charity_advisor फ़ोल्डर में मौजूद है

पाँचवाँ चरण: Cloud Run पर डिप्लॉय करना (ज़रूरी नहीं)

प्रोडक्शन डिप्लॉयमेंट को स्ट्रीमलाइन करने के लिए, Agent Engine का इस्तेमाल करने का सुझाव दिया जाता है. हालांकि, Cloud Run से आपको ज़्यादा कंट्रोल मिलता है. साथ ही, यह ADK के वेब यूज़र इंटरफ़ेस (यूआई) के साथ काम करता है. यह सेक्शन भरना ज़रूरी नहीं है.

Cloud Run का इस्तेमाल कब करना चाहिए

अगर आपको ये सुविधाएं चाहिए, तो Cloud Run चुनें:

  • उपयोगकर्ता के इंटरैक्शन के लिए ADK का वेब यूज़र इंटरफ़ेस (यूआई)
  • कंटेनर एनवायरमेंट पर पूरा कंट्रोल
  • डेटाबेस के कस्टम कॉन्फ़िगरेशन
  • मौजूदा Cloud Run सेवाओं के साथ इंटिग्रेशन

डिप्लॉयमेंट शुरू करना

chmod +x deploy.sh
./deploy.sh cloud-run

क्या अलग है:

स्क्रिप्ट अपने-आप ये काम करेगी:

  • अपने एजेंट कोड की मदद से Docker कंटेनर बनाना
  • अगर ज़रूरत हो, तो Cloud SQL PostgreSQL डेटाबेस बनाएं
  • डेटाबेस कनेक्शन कॉन्फ़िगर करना
  • ADK के वेब यूज़र इंटरफ़ेस (यूआई) को चालू करके परिनियोजित करना

Cloud SQL प्रोविज़निंग की वजह से, डिप्लॉयमेंट में 10 से 15 मिनट लगते हैं.

सेशन मैनेजमेंट:

  • VertexAiSessionService के बजाय DatabaseSessionService का इस्तेमाल करता है
  • इसके लिए, .env में डेटाबेस क्रेडेंशियल (या अपने-आप जनरेट होने वाले क्रेडेंशियल) ज़रूरी हैं
  • स्टेट, PostgreSQL डेटाबेस में सेव रहती है

यूज़र इंटरफ़ेस (यूआई) के साथ काम करता है:

  • वेब यूज़र इंटरफ़ेस (यूआई) यहां उपलब्ध है: https://charity-advisor-xyz.a.run.app

Cloud Run डिप्लॉयमेंट की टेस्टिंग

अगर आपने --with_ui का इस्तेमाल करके Cloud Run पर डिप्लॉय किया है, तो सीधे अपने ब्राउज़र में टेस्ट करें:

  1. अपने सेवा के यूआरएल पर जाएं (यह यूआरएल, डिप्लॉयमेंट आउटपुट में दिया गया है)
  2. आपको ADK का वेब इंटरफ़ेस दिखेगा. ड्रॉपडाउन से अपना एजेंट चुनें.
  3. जांच के लिए दान करें:
   I want to donate $50 to a children's education charity
  1. एक्ज़ीक्यूशन फ़्लो देखें:
    • ShoppingAgent, दान के लिए उपलब्ध संस्थाओं को ढूंढता है और आपकी पसंद को सेव करता है
    • MerchantAgent, कार्ट मैंडेट बनाता है
    • CredentialsProvider, पेमेंट मैंडेट बनाता है और पुष्टि करने का अनुरोध करता है
    • पुष्टि करने के बाद, पेमेंट प्रोसेस किया जाता है
  2. पुष्टि करें कि जवाब में ये शामिल हैं:
    • दान के लिए सुझाव
    • पुष्टि करने का अनुरोध
    • मंज़ूरी मिलने के बाद दिखने वाला मैसेज

समस्या का हल

आम समस्याएं

समस्या: ERROR: GOOGLE_CLOUD_PROJECT is not set

समाधान: पक्का करें कि आपकी .env फ़ाइल में सही प्रोजेक्ट आईडी हो:

GOOGLE_CLOUD_PROJECT=your-actual-project-id

समस्या: स्टेजिंग बकेट अपने-आप नहीं बनी

समाधान: स्क्रिप्ट को बकेट अपने-आप बनानी चाहिए. अगर ऐसा नहीं है, तो इसे मैन्युअल तरीके से बनाएं:

gsutil mb -p $GOOGLE_CLOUD_PROJECT -l $GOOGLE_CLOUD_LOCATION $STAGING_BUCKET

खास जानकारी

आपने:

✅ deploy.sh
की ओर से उपलब्ध कराए गए डिप्लॉयमेंट इन्फ़्रास्ट्रक्चर को समझ लिया है ✅ एजेंट इंजन रैपर के कॉन्फ़िगरेशन की समीक्षा कर ली है
✅ आपने भरोसेमंद डोनेशन सिस्टम को एजेंट इंजन पर डिप्लॉय कर लिया है (सुझाया गया)
✅ --trace_to_cloud के साथ Cloud Trace इंटिग्रेशन चालू कर लिया है
✅ पुष्टि कर ली है कि एजेंट को ऐक्सेस किया जा सकता है और वह काम कर रहा है
✅ मॉड्यूल 9 में जवाबदेही के लिए ऑडिट ट्रेल बनाने की प्रोसेस शुरू कर दी है

अगले मॉड्यूल में, आपको यह पता चलेगा कि इस फ़्लैग से क्या-क्या अनलॉक होता है: हर दान, सहमति लेने के हर पल, और क्रेडेंशियल चेन के हर चरण की पूरी जानकारी.

9. जांचने की क्षमता

बैनर

ग्राफ़ ट्रेस

पहले मॉड्यूल में, आपने एक बुनियादी समस्या के बारे में जाना: जब कोई एआई एजेंट पैसे मैनेज करता है, तो यह कैसे साबित किया जा सकता है कि क्या हुआ?

कोई उपयोगकर्ता इन पर दावा कर सकता है:

  • "मैंने कभी उस चैरिटी को नहीं चुना!"
  • "मैंने इस पेमेंट को मंज़ूरी नहीं दी!"
  • "सिस्टम ने मेरी सहमति के बिना मुझसे शुल्क लिया!"

ब्लैक-बॉक्स एआई सिस्टम में, आपके पास यह साबित करने का कोई तरीका नहीं होता कि एआई ने गलत फ़ैसला लिया है. हालांकि, दान करने के लिए भरोसेमंद सिस्टम अलग होता है. आपने मॉड्यूल 8 में --trace_to_cloud फ़्लैग का इस्तेमाल करके डिप्लॉय किया था. इसका मतलब है कि अब हर दान, Cloud Trace में पूरी तरह से सुरक्षित ऑडिट ट्रेल बनाता है.

इस मॉड्यूल में, आपको उन ट्रेस को पढ़ने और उन्हें सबूत के तौर पर इस्तेमाल करने का तरीका सिखाया जाता है. आपको इन चीज़ों के बारे में जानकारी मिलेगी:

  • प्रोडक्शन ट्रेस ढूंढने के लिए, Cloud Trace Explorer पर जाएं
  • एक्ज़ीक्यूशन फ़्लो को समझने के लिए, वॉटरफ़ॉल व्यू पढ़ें
  • क्रेडेंशियल चेन ढूंढना (Intent → Cart → Payment mandates)
  • टाइमस्टैंप के सबूत की मदद से, सहमति लेने के समय का पता लगाना
  • विरोध को हल करने के लिए ट्रेस का इस्तेमाल करना
  • अनुपालन और ऑडिट के लिए ट्रेस एक्सपोर्ट करना

भरोसेमंद सिस्टम और बेहतर पर काम करने वाले सिस्टम के बीच यही अंतर होता है: यह साबित करने की क्षमता कि फ़ॉरेंसिक जांच के आधार पर क्या हुआ.

ट्रेस और स्पैन के बारे में जानकारी

Cloud Trace में ट्रेस देखने से पहले, आपको यह समझना होगा कि आपको क्या देखना है.

ट्रेस क्या होता है?

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

हर ट्रेस में यह जानकारी दिखती है:

  • अनुरोध पूरा होने में लगने वाला कुल समय
  • वे सभी कार्रवाइयां जो पूरी हो चुकी हैं
  • ऑपरेशन एक-दूसरे से कैसे जुड़े होते हैं (पैरंट-चाइल्ड रिलेशनशिप)
  • हर ऑपरेशन कब शुरू और खत्म हुआ
  • समीक्षा के सफल या असफल होने की स्थिति

आपके चैरिटी एजेंट के लिए: एक ट्रेस का मतलब है कि "मुझे दान करना है" से लेकर "पेमेंट हो गया" तक, दान करने की पूरी प्रोसेस.

स्पैन क्या होता है?

स्पैन, ट्रेस में काम की एक यूनिट को दिखाता है. स्पैन को ट्रेस के बिल्डिंग ब्लॉक के तौर पर माना जाता है.

आपके दान सिस्टम में स्पैन के सामान्य टाइप:

स्पैन टाइप

यह क्या दिखाता है

उदाहरण

agent_run

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

ShoppingAgent.run, MerchantAgent.run

call_llm

लैंग्वेज मॉडल से किया गया अनुरोध

gemini-2.5-flash चैरिटी चुनने का अनुरोध

execute_tool

टूल फ़ंक्शन को पूरा करना

find_charities, create_payment_mandate

state_read

सेशन मेमोरी से डेटा पढ़ा जा रहा है

राज्य से intent_mandate को वापस पाना

state_write

सेशन की मेमोरी में लिखना

स्टेट में cart_mandate सेव किया जा रहा है

हर स्पैन में यह जानकारी शामिल होती है:

  • नाम: इससे किस कार्रवाई का पता चलता है
  • इसमें कितना समय लगा (शुरू होने का समय → खत्म होने का समय)
  • एट्रिब्यूट: मेटाडेटा, जैसे कि टूल के इनपुट, मॉडल के जवाब, टोकन की संख्या
  • स्टेटस: पूरा हुआ (OK) या गड़बड़ी (ERROR)
  • पैरंट-चाइल्ड रिलेशनशिप: किस ऑपरेशन को किसने ट्रिगर किया

स्पैन से ट्रेस कैसे बनता है

कार्य-कारण दिखाने के लिए, स्पैन एक-दूसरे के अंदर नेस्ट किए जाते हैं:

Root Span: CharityAdvisor.run (entire request)
  └─ Child: DonationPipeline.run (sequential workflow)
      ├─ Child: ShoppingAgent.run
      │   ├─ Grandchild: call_llm (Gemini processes charity search)
      │   ├─ Grandchild: execute_tool (find_charities)
      │   └─ Grandchild: execute_tool (save_user_choice)
      ├─ Child: MerchantAgent.run
      │   ├─ Grandchild: call_llm (Gemini generates cart)
      │   └─ Grandchild: execute_tool (create_cart_mandate)
      └─ Child: CredentialsProvider.run
          ├─ Grandchild: call_llm (Gemini processes payment)
          └─ Grandchild: execute_tool (create_payment_mandate) [CONSENT!]

इस क्रम से यह पता चलता है कि क्या हुआ और किस क्रम में हुआ. यहां देखा जा सकता है कि पेमेंट मैंडेट, कार्ट मैंडेट के बाद बनाया गया था. वहीं, कार्ट मैंडेट, उपयोगकर्ता के किसी चैरिटी को चुनने के बाद बनाया गया था.

पहला चरण: Cloud Trace Explorer को ऐक्सेस करना

अब डिप्लॉय किए गए एजेंट से मिले असली ट्रेस देखते हैं.

  1. Google Cloud Console खोलें: console.cloud.google.com
  2. सबसे ऊपर मौजूद ड्रॉपडाउन से अपना प्रोजेक्ट चुनें. अगर आपने इस प्रोजेक्ट पर काम किया है, तो यह पहले से चुना हुआ होना चाहिए
  3. Cloud Trace Explorer पर जाएं:
    • बाईं ओर मौजूद साइडबार में, Observability सेक्शन पर स्क्रोल करें
    • ट्रेस करें पर क्लिक करें
    • इसके अलावा, इस लिंक का इस्तेमाल करें: console.cloud.google.com/traces/list

आपको क्या दिख रहा है

ट्रेस एक्सप्लोरर में, आपके प्रोजेक्ट के सभी ट्रेस की सूची दिखती है:

कॉलम

यह क्या दिखाता है

अनुरोध

एपीआई अनुरोधों के लिए, एचटीटीपी मेथड और एंडपॉइंट

शुरू होने का समय

अनुरोध कब शुरू हुआ

लेटेंसी

अनुरोध पूरा होने में लगने वाला कुल समय

स्पैन

ट्रेस में मौजूद कार्रवाइयों की संख्या

हर लाइन, डिप्लॉय किए गए एजेंट को भेजी गई एक पूरी रिक्वेस्ट को दिखाती है.

अगर ज़रूरी हो, तो टेस्ट ट्रेस जनरेट करें

अगर आपको अब तक कोई ट्रेस नहीं दिखता है, तो हो सकता है कि सूची खाली हो. इसकी वजह यह हो सकती है:

  • अब तक आपके डिप्लॉय किए गए एजेंट से कोई अनुरोध नहीं किया गया है
  • अनुरोध करने के बाद, ट्रेस दिखने में 1 से 2 मिनट लगते हैं

टेस्ट ट्रेस जनरेट करना:

अगर आपने यूज़र इंटरफ़ेस (यूआई) के साथ Cloud Run पर डिप्लॉय किया है, तो अपनी सेवा के यूआरएल पर जाएं और ब्राउज़र में दान करें.

अगर आपने एजेंट इंजन पर डिप्लॉय किया है, तो मॉड्यूल 8 से टेस्ट स्क्रिप्ट चलाएं:

python scripts/test_deployed_agent.py

एक से दो मिनट इंतज़ार करें. इसके बाद, Cloud Trace Explorer पेज को रीफ़्रेश करें. अब आपको ट्रेस दिखेंगे.

ट्रेस फ़िल्टर करना

किसी खास ट्रेस को ढूंढने के लिए, सबसे ऊपर मौजूद फ़िल्टर विकल्पों का इस्तेमाल करें:

  • समयसीमा: अगर ज़रूरत हो, तो "पिछले घंटे का" से बदलकर "पिछले 24 घंटे का" करें
  • कम से कम लेटेंसी / ज़्यादा से ज़्यादा लेटेंसी: धीमे अनुरोधों के लिए फ़िल्टर
  • अनुरोध फ़िल्टर: किसी खास कार्रवाई के हिसाब से खोजें. जैसे, "DonationPipeline")

इस मॉड्यूल के लिए, ज़्यादा समय (>5 सेकंड) वाले ट्रेस पर फ़ोकस करें. ऐसा इसलिए, क्योंकि ये तीनों एजेंट के साथ डोनेशन के पूरे फ़्लो को दिखाते हैं.

दूसरा चरण: दान करने की पूरी प्रोसेस की जांच करना

वॉटरफ़ॉल व्यू खोलने के लिए, सूची में मौजूद किसी भी ट्रेस पर क्लिक करें. एजेंट के व्यवहार का विश्लेषण करने में, आपको ज़्यादातर समय यहीं बिताना होगा.

झरने के नज़ारे वाली जगह के बारे में जानकारी

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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
              Timeline (horizontal = time) →
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

invocation                           ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 8.2s
  agent_run: CharityAdvisor          ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 8.1s
    agent_run: DonationPipeline      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 7.9s
      agent_run: ShoppingAgent       ▓▓▓▓▓▓ 2.1s
        call_llm: gemini-2.5-flash   ▓▓▓▓ 1.2s
        execute_tool: find_charities ▓▓ 0.5s
        execute_tool: save_user_choice ▓ 0.3s
      agent_run: MerchantAgent       ▓▓▓ 1.8s
        call_llm: gemini-2.5-flash   ▓▓ 0.9s
        execute_tool: create_cart_mandate ▓ 0.7s
      agent_run: CredentialsProvider ▓▓▓▓▓▓▓▓ 4.0s
        call_llm: gemini-2.5-flash   ▓▓ 0.8s
        execute_tool: create_payment_mandate ▓▓▓▓▓ 3.0s [CONSENT]

डेटा के चार्ट को पढ़ना

हर बार एक अवधि को दिखाता है:

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

इस उदाहरण ट्रेस से मिली मुख्य जानकारी:

✅ कुल अवधि: 8.2 सेकंड
✅ क्रम से लागू होना: ShoppingAgent ने MerchantAgent के शुरू होने से पहले काम पूरा कर लिया
✅ MerchantAgent ने काम पूरा कर लिया

before

CredentialsProvider started
 ✅ Consent was the longest operation: 3.0 seconds for create_payment_mandate (because it waited for user confirmation)
✅ LLM calls are visible: Each agent made one Gemini request
✅ Tool calls are captured: All six tools executed successfully

इस विज़ुअल से आपको तुरंत पता चल जाता है कि कितना समय लगा और ऑपरेशन किस क्रम में किए गए.

जानकारी के लिए किसी स्पैन पर क्लिक करें

सबसे ऊपर मौजूद रूट स्पैन invocation पर क्लिक करें. दाईं ओर मौजूद पैनल में, आपको एट्रिब्यूट की पूरी जानकारी दिखेगी:

{
  "http.method": "POST",
  "http.status_code": 200,
  "http.url": "https://charity-advisor-xyz.a.run.app/api/run",
  "user_id": "test_user_123",
  "session_id": "4857885913439920384",
  "trace_id": "a1b2c3d4e5f6...",
  "span_id": "1234567890abcdef"
}

इन एट्रिब्यूट से, पूरे अनुरोध के बारे में जानकारी मिलती है.

तीसरा चरण: क्रेडेंशियल चेन ढूंढना

आपका भरोसेमंद सिस्टम, हर चरण में अनुमति साबित करने के लिए क्रेडेंशियल चेन का इस्तेमाल करता है:

IntentMandate (User chose charity)
    ↓
CartMandate (Merchant created cart, signed IntentMandate)
    ↓
PaymentMandate (Payment provider created payment, signed CartMandate)

आइए, ट्रेस में हर मैंडेट ढूंढते हैं.

IntentMandate ढूंढना

execute_tool: save_user_choice स्पैन (ShoppingAgent में) पर क्लिक करें.

एट्रिब्यूट पैनल में, आपको यह जानकारी दिखेगी:

{
  "tool.name": "save_user_choice",
  "tool.input.charity_name": "Save the Children",
  "tool.input.amount": 50,
  "tool.output.status": "success",
  "tool.output.intent_mandate": {
    "charity_name": "Save the Children",
    "amount": 50,
    "timestamp": "2024-11-08T15:30:12.345Z",
    "signature": "a3f7b9c1d2e4..."
  }
}

इससे यह साबित होता है कि:

  • ✅ उपयोगकर्ता ने "Save the Children" को चुना है
  • ✅ रकम 50 डॉलर थी
  • ✅ विकल्प को 15:30:12 यूटीसी पर रिकॉर्ड किया गया था
  • ✅ हस्ताक्षर जनरेट किया गया (प्रोडक्शन में, यह क्रिप्टोग्राफ़िक होगा)

IntentMandate अब सेशन की स्थिति में है और बाद के एजेंटों के लिए उपलब्ध है.

CartMandate ढूंढना

MerchantAgent में जाकर, execute_tool: create_cart_mandate स्पैन पर क्लिक करें.

एट्रिब्यूट पैनल में जाकर:

{
  "tool.name": "create_cart_mandate",
  "tool.input.intent_mandate": {
    "charity_name": "Save the Children",
    "amount": 50,
    "signature": "a3f7b9c1d2e4..."
  },
  "tool.output.status": "success",
  "tool.output.cart_mandate": {
    "cart_id": "cart_7893",
    "intent_signature": "a3f7b9c1d2e4...",
    "cart_signature": "e8f2a9b3c7d1...",
    "timestamp": "2024-11-08T15:30:14.789Z"
  }
}

इससे यह साबित होता है कि:

  • ✅ MerchantAgent को IntentMandate मिला (इनपुट में यह दिखता है)
  • ✅ "cart_7893" आईडी वाला कार्ट बनाया गया
  • ✅ कार्ट के हस्ताक्षर में IntentMandate के हस्ताक्षर का रेफ़रंस दिया गया है (चेन लिंक!)
  • ✅ 15:30:14 यूटीसी पर बनाया गया (इंटेंट के 2.4 सेकंड बाद)

CartMandate अब IntentMandate को रेफ़रंस करता है, जिससे चेन बनती है.

PaymentMandate ढूंढना

CredentialsProvider में जाकर, execute_tool: create_payment_mandate स्पैन पर क्लिक करें.

एट्रिब्यूट पैनल में जाकर:

{
  "tool.name": "create_payment_mandate",
  "tool.input.cart_mandate": {
    "cart_id": "cart_7893",
    "intent_signature": "a3f7b9c1d2e4...",
    "cart_signature": "e8f2a9b3c7d1..."
  },
  "tool.confirmation_required": true,
  "tool.confirmation_timestamp": "2024-11-08T15:30:17.891Z",
  "tool.user_response": "CONFIRMED",
  "tool.wait_duration_ms": 29168,
  "tool.output.status": "success",
  "tool.output.payment_mandate": {
    "payment_id": "pay_9821",
    "cart_signature": "e8f2a9b3c7d1...",
    "payment_signature": "b4c9e2a7f8d3...",
    "timestamp": "2024-11-08T15:30:47.059Z"
  }
}

इससे पूरी चेन की पुष्टि होती है:

  • ✅ CredentialsProvider को CartMandate मिला (इनपुट से पता चलता है)
  • ✅ पेमेंट में CartMandate के हस्ताक्षर का रेफ़रंस दिया गया हो (चेन लिंक!)
  • ✅ पुष्टि करना ज़रूरी था (confirmation_required: true)
  • ✅ उपयोगकर्ता की पुष्टि 15:30:17 यूटीसी पर की गई
  • ✅ सिस्टम ने उपयोगकर्ता के फ़ैसले के लिए 29.2 सेकंड तक इंतज़ार किया
  • ✅ पुष्टि के बाद पेमेंट किया गया (टाइमस्टैंप: 15:30:47)

चेन को विज़ुअलाइज़ करना

ट्रेस से यह पता चलता है कि क्रेडेंशियल चेन सही तरीके से लागू की गई है:

15:30:12 UTC → IntentMandate created (signature: a3f7...)
                  ↓
15:30:14 UTC → CartMandate created (references: a3f7...)
                  ↓
15:30:17 UTC → User consent requested
                  ↓
15:30:47 UTC → PaymentMandate created (references: e8f2...)

हर मैंडेट में, पिछले मैंडेट के हस्ताक्षर का रेफ़रंस होता है. यह टैंपर-एविडेंट है. हस्ताक्षर मैच करके, चेन की पुष्टि की जा सकती है.

चौथा चरण: परफ़ॉर्मेंस और रुकावटों का विश्लेषण करना

Cloud Trace से सिर्फ़ यह पता नहीं चलता कि क्या हुआ, बल्कि यह भी पता चलता है कि किस काम में कितना समय लगा, ताकि आप उसे ऑप्टिमाइज़ कर सकें.

क्रिटिकल पाथ की पहचान करना

वॉटरफ़ॉल व्यू में, वर्टिकल स्टैक में सबसे लंबे स्पैन ढूंढें. ये आपकी परफ़ॉर्मेंस से जुड़ी समस्याएं हैं.

हमारे उदाहरण ट्रेस से:

Total: 8.2 seconds

Breakdown:
  - ShoppingAgent:         2.1s (26%)
  - MerchantAgent:         1.8s (22%)
  - CredentialsProvider:   4.0s (49%)  ← Bottleneck
  - Other overhead:        0.3s (3%)

अहम जानकारी: CredentialsProvider को कुल समय का 49% हिस्सा लगता है. क्यों?

CredentialsProvider स्पैन में ड्रिल करें:

CredentialsProvider: 4.0s
  - call_llm:              0.8s (20%)
  - create_payment_mandate: 3.0s (75%)  ← User consent wait
  - Other:                 0.2s (5%)

तीन सेकंड की देरी सामान्य है और अच्छी है - इसका मतलब है कि उपयोगकर्ता पुष्टि करने से पहले सोच-विचार कर रहा है. यह परफ़ॉर्मेंस से जुड़ी समस्या नहीं है. यह इस बात का सबूत है कि उपयोगकर्ता ने सोच-समझकर सहमति दी है.

एलएलएम की लागत को ट्रैक करना

टोकन के इस्तेमाल की जानकारी देखने के लिए, किसी भी call_llm स्पैन पर क्लिक करें:

{
  "llm.model": "gemini-2.5-flash",
  "llm.usage.prompt_tokens": 487,
  "llm.usage.completion_tokens": 156,
  "llm.usage.total_tokens": 643,
  "llm.response_time_ms": 1243
}

इसका इस्तेमाल इन कामों के लिए किया जा सकता है:

  • हर अनुरोध की लागत (टोकन × मॉडल की कीमत) को ट्रैक करना
  • ज़रूरत से ज़्यादा लंबे प्रॉम्प्ट की पहचान करना
  • मॉडल की परफ़ॉर्मेंस की तुलना करना (Flash बनाम Pro)
  • स्पीड और क्वालिटी के लिए ऑप्टिमाइज़ करना

कैलकुलेशन का उदाहरण:

Gemini 2.5 Flash pricing (as of Nov 2024):
  Input:  $0.075 per 1M tokens
  Output: $0.30 per 1M tokens

This request:
  Input:  487 tokens × $0.075 / 1M = $0.000037
  Output: 156 tokens × $0.30 / 1M  = $0.000047
  Total:                            = $0.000084 (~$0.00008)

For 10,000 donations/month:
  10,000 × 3 agents × $0.00008 = $2.40/month in LLM costs

डेटा के आधार पर मॉडल चुनने के लिए, यह ज़्यादा जानकारी उपलब्ध कराता है.

अलग-अलग ट्रेस की तुलना करना

एक से ज़्यादा ट्रेस के लिए फ़िल्टर करें और उनकी अवधि की तुलना करें:

Trace 1: 8.2s  (with consent wait: 3.0s)
Trace 2: 12.5s (with consent wait: 7.8s)  ← User took longer
Trace 3: 5.1s  (with consent wait: 0.2s)  ← User clicked fast
Trace 4: 6.3s  (with consent wait: 1.5s)

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

इससे पता चलता है कि सिस्टम भरोसेमंद तरीके से काम कर रहा है.

प्रोडक्शन सिस्टम के लिए, सूचनाएँ पाने की सुविधा सेट अप करें, ताकि उपयोगकर्ताओं की शिकायत करने से पहले ही समस्याओं का पता लगाया जा सके.

गड़बड़ी की दर ज़्यादा होने पर सूचना

जब 5% से ज़्यादा ट्रेस में गड़बड़ियां हों, तब सूचना पाने के लिए यह क्वेरी लिखें:

  1. Cloud Monitoring पर जाएं
  2. "सूचनाएं" → "नीति बनाएं" पर क्लिक करें
  3. कॉन्फ़िगर करें: 
    Resource: Cloud Trace Span
Metric: Span error count
Condition: Rate > 5% over 5 minutes
Notification: Email your-team@example.com

अनुरोध पूरा होने में ज़्यादा समय लगने पर सूचना

जब p95 लेटेंसी 15 सेकंड से ज़्यादा हो, तब सूचना पाने के लिए यह क्वेरी चलाएं:

Resource: Cloud Trace
Metric: Span duration (95th percentile)
Condition: > 15000ms for 5 minutes
Notification: PagerDuty

इससे परफ़ॉर्मेंस में गिरावट का पता चलता है. इससे पहले कि इसका असर उपयोगकर्ता अनुभव पर पड़े.

अगर बिना पुष्टि के कोई पेमेंट प्रोसेस होता है, तो सूचना बनाएं:

Resource: Cloud Trace Span
Filter: tool.name="create_payment_mandate" AND tool.confirmation_required!=true
Condition: Any match
Notification: Critical alert to security team

यह सुरक्षा से जुड़े उल्लंघन का पता लगाने वाला टूल है. अगर यह ट्रिगर होता है, तो इसका मतलब है कि सहमति लेने के तरीके में कोई गंभीर समस्या है.

आपने क्या सीखा

Cloud Trace की मदद से, अब आपको इन कामों को करने का तरीका पता चल गया है:

✅ प्रोडक्शन ट्रेस ढूंढने के लिए, Cloud Trace Explorer पर जाएं
✅ एक्ज़ीक्यूशन का पूरा फ़्लो देखने के लिए, वॉटरफ़ॉल व्यू पढ़ें
✅ IntentMandate → CartMandate → PaymentMandate के ज़रिए, क्रेडेंशियल चेन को ट्रेस करें ✅ विवाद सुलझाने के लिए, ट्रेस को सबूत के तौर पर इस्तेमाल करें
✅ परफ़ॉर्मेंस का विश्लेषण करें, ताकि रुकावटों का पता लगाया जा सके
✅ एलएलएम की लागत को ट्रैक करें

इससे क्या फ़र्क़ पड़ता है

एक ही "मैंने इसकी अनुमति कभी नहीं दी!" शिकायत को मैनेज करने वाले दो सिस्टम की तुलना करें:

जांचने की सुविधा के बिना सिस्टम

User: "I never authorized that $50 donation!"
You:  "Our logs show the transaction completed successfully."
User: "But I didn't approve it!"
You:  "The system requires confirmation before processing."
User: "I never saw any confirmation!"
You:  "..." [no way to prove what happened]

Result: Refund issued, trust lost, user never returns.

Cloud Trace की सुविधा वाला सिस्टम

User: "I never authorized that $50 donation!"
You:  "Let me pull up the trace from your session..."
      [Shows waterfall with consent span]
You:  "Here's the evidence:
       - 15:30:17 UTC: System asked for confirmation
       - Message shown: 'You are about to donate $50...'
       - 15:30:47 UTC: You clicked 'CONFIRM'
       - Wait time: 29.2 seconds
       
       The system waited almost 30 seconds for your decision.
       Here's the exact timestamp of your confirmation."
       
User: "Oh... I remember now. My mistake. Sorry!"

Result: Trust preserved, no refund needed, user continues using service.

यह जवाबदेही के ऑडिट ट्रेल की ताकत है. आप "हम पर भरोसा करें" से "हम आपको बताते हैं कि असल में क्या हुआ" पर स्विच करते हैं.

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

आपने भरोसेमंद एजेंट बनाने की तकनीकी प्रक्रिया पूरी कर ली है:

✅ मॉड्यूल 1 से 6: भरोसेमंद आर्किटेक्चर (भूमिकाएं, क्रेडेंशियल, सहमति) डिज़ाइन किया गया
✅ मॉड्यूल 7: जटिल वर्कफ़्लो (सीक्वेंशियल एजेंट) व्यवस्थित किए गए
✅ मॉड्यूल 8: निगरानी की सुविधा के साथ डिप्लॉय किया गया
✅ मॉड्यूल 9: जवाबदेही से जुड़े डेटा को पढ़ने और इस्तेमाल करने का तरीका सीखा

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

10. आपका आगे का सफ़र

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

आपने इस वर्कशॉप की शुरुआत एक सवाल से की थी: "मैं ऐसे एआई एजेंट कैसे बनाऊं जिन पर मैं भरोसे के साथ पैसे खर्च कर सकूं?"

अब आपको जवाब मिल गया है.

आपने कहाँ से शुरुआत की (मॉड्यूल 3):

simple_agent = Agent(
    model="gemini-2.5-flash",
    instruction="Find charities and donate",
    tools=[google_search]
)

आप अभी कहां हैं (मॉड्यूल 10):

  • ✅ भूमिका के हिसाब से अलग-अलग काम करने वाले तीन विशेषज्ञ एजेंट
  • ✅ पुष्टि किए जा सकने वाले तीन क्रेडेंशियल (इरादा → कार्ट → पेमेंट के निर्देश)
  • ✅ हर चरण में क्रेडेंशियल चेन की पुष्टि की जाती है और यह भी देखा जाता है कि क्रेडेंशियल की समयसीमा खत्म तो नहीं हो गई है
  • ✅ टाइमस्टैंप के सबूत के साथ सहमति देने का तरीका
  • ✅ निगरानी की सुविधा के साथ एजेंट इंजन को प्रॉडक्शन में डिप्लॉय करना
  • ✅ Cloud Trace में जवाबदेही से जुड़ी पूरी जानकारी
  • ✅ विवाद सुलझाने के लिए फ़ॉरेंसिक सबूत

वर्कशॉप बनाम प्रोडक्शन: अंतर

आपके सिस्टम में सही आर्किटेक्चर और पैटर्न दिखाए गए हैं. हालांकि, इसमें शिक्षा से जुड़ी ऐसी चीज़ें शामिल हैं जिन्हें असली पैसे और असली उपयोगकर्ताओं के लिए अपग्रेड करना होगा.

यहां बताया गया है कि किस चीज़ को आसान बनाया गया है और प्रोडक्शन के लिए क्या ज़रूरी है:

कॉम्पोनेंट

वर्कशॉप लागू करना

प्रोडक्शन से जुड़ी ज़रूरी शर्तें

हस्ताक्षर

डेमो के लिए SHA-256 हैश (SIG_abc123)

निजी पासकोड के साथ पीकेआई या JWT का इस्तेमाल करके, असली क्रिप्टोग्राफ़िक हस्ताक्षर

पेमेंट प्रोसेस करना

नकली रिटर्न (simulation: True फ़्लैग)

पेमेंट की सुविधा देने वाले एपीआई (Stripe, PayPal, Square) के साथ इंटिग्रेशन

उपयोगकर्ता की पुष्टि करना

भरोसेमंद (लॉगिन करने की ज़रूरत नहीं है)

OAuth 2.0, WebAuthn या सेशन मैनेजमेंट

सीक्रेट मैनेज करना

.env फ़ाइल में एनवायरमेंट वैरिएबल

Google Secret Manager या Cloud KMS के साथ एन्क्रिप्शन

चैरिटी का डेटाबेस

नौ दान-पुण्य वाली संस्थाओं की जानकारी वाली मॉक JSON फ़ाइल

लाइव एपीआई इंटिग्रेशन (आईआरएस टैक्स छूट वाली संस्थाओं को खोजने की सुविधा, Charity Navigator API)

गड़बड़ी ठीक करना

गड़बड़ी के मैसेज के साथ बुनियादी try-catch

एक्स्पोनेंशियल बैकऑफ़, सर्किट ब्रेकर, और डेड लेटर क्यू के साथ फिर से कोशिश करने की सुविधा

साइट टेस्ट करना

स्क्रिप्ट की मदद से मैन्युअल तरीके से पुष्टि करना

CI/CD के साथ यूनिट/इंटिग्रेशन/E2E टेस्ट सुइट

सेशन बनाए रखना

मेमोरी में (स्थानीय) या अपने-आप (एजेंट इंजन)

बैकअप और आपदा के बाद डेटा वापस पाने की सुविधा वाला प्रोडक्शन डेटाबेस

Rate Limiting

कोई नहीं (शिक्षा से जुड़ा एनवायरमेंट)

हर उपयोगकर्ता के लिए दर की सीमाएं, आईपी के आधार पर थ्रॉटलिंग, और गलत इस्तेमाल का पता लगाना

आर्किटेक्चर के मुख्य पैटर्न, जिनके बारे में आपको अच्छी जानकारी है

इस वर्कशॉप में आपने जो पैटर्न सीखे हैं वे प्रोडक्शन पैटर्न हैं. उन पर शक न करें.

भूमिकाएं अलग-अलग होना (AP2 का सिद्धांत #1)

हर एजेंट को एक काम सौंपा जाता है और उसे सिर्फ़ वही जानकारी दिखती है जिसकी उसे ज़रूरत होती है. अगर किसी एक एजेंट के साथ छेड़छाड़ की जाती है, तो हमलावर अन्य एजेंटों का डेटा ऐक्सेस नहीं कर सकता. इससे, सूचना पाने वाले लोगों की संख्या सीमित हो जाती है.

इस सुविधा का इस्तेमाल करने वाले प्रोडक्शन सिस्टम: पेमेंट प्रोसेस करना, दस्तावेज़ों के वर्कफ़्लो, अनुमति देने की चेन, पुष्टि करने वाले गेट के साथ कई चरणों वाले फ़ॉर्म.

पुष्टि किए जा सकने वाले क्रेडेंशियल (AP2 सिद्धांत #2)

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

प्रोडक्शन वैल्यू: इसमें यह पूरी जानकारी होती है कि क्या हुआ, कब हुआ, और किस क्रम में हुआ. विवाद सुलझाने और कानूनी नियमों का पालन करने के लिए ज़रूरी है.

टाइमस्टैंप से यह साबित होता है कि उपयोगकर्ता ने कार्रवाई को मंज़ूरी दी है. इसके ख़िलाफ़ विवाद नहीं किया जा सकता.

प्रोडक्शन वैल्यू: वित्तीय लेन-देन के लिए कानूनी तौर पर ज़रूरी है. इससे उपयोगकर्ता और कंपनी, दोनों को सुरक्षा मिलती है.

सीक्वेंशियल ऑर्केस्ट्रेशन (ADK पैटर्न)

इससे सही क्रम में कोड को लागू किया जाता है. इससे चरणों को स्किप नहीं किया जा सकता. इससे यह पक्का किया जाता है कि हर एजेंट को पिछले एजेंट का आउटपुट दिखे.

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

जांचने की पूरी क्षमता (OpenTelemetry + Cloud Trace)

हर फ़ैसला, टूल कॉल, सहमति का समय, और क्रेडेंशियल हैंडऑफ़ अपने-आप कैप्चर हो जाता है.

प्रोडक्शन वैल्यू: विवादों के लिए फ़ॉरेंसिक सबूत. परफ़ॉर्मेंस ऑप्टिमाइज़ेशन का डेटा. नीति के पालन से जुड़ी ऑडिट ट्रेल. प्रोडक्शन से जुड़ी समस्याओं को सटीक तरीके से डीबग करें.

सीखते रहने के लिए संसाधन

ADK के दस्तावेज़:

AP2 और इससे जुड़े स्टैंडर्ड:

Google Cloud की सेवाएं:

क्लीनअप के संसाधन

शुल्क से बचने के लिए, डिप्लॉयमेंट मिटाएं:

एजेंट इंजन: एजेंट इंजन के दस्तावेज़ में दिया गया तरीका अपनाएं

Cloud Run (अगर डिप्लॉय किया गया है):

gcloud run services delete charity-advisor \
    --region=$GOOGLE_CLOUD_LOCATION

स्टोरेज बकेट:

gsutil -m rm -r gs://$GOOGLE_CLOUD_PROJECT-staging
gsutil -m rm -r gs://$GOOGLE_CLOUD_PROJECT-artifacts

आपका सफ़र जारी है

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

सिद्धांत ट्रांसफ़र हो जाते हैं. भरोसे का मॉडल काम करता है.

अब भरोसेमंद कुछ बनाएं! ❤️

बैनर