1. परिचय
इस कोडलैब में, रिमोट Google Cloud मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर को ऐक्सेस करने वाले एआई एजेंट के लिए, एजेंट गेटवे इग्रेस गवर्नेंस के बारे में बताया गया है.
एआई ऐप्लिकेशन, स्टैंडअलोन चैटबॉट से लेकर कई एजेंट वाले वर्कफ़्लो वाले ऑटोनॉमस सिस्टम तक, बाहरी टूल को डाइनैमिक तरीके से चालू कर सकते हैं. एजेंट को डेटाबेस से क्वेरी करने, वेब कॉन्टेंट फ़ेच करने, और कार्रवाइयां करने के लिए, सीमित ऐक्सेस देना ज़रूरी है. इससे एजेंट सुरक्षित और ज़्यादा असरदार तरीके से काम कर पाते हैं. हालांकि, एंटरप्राइज़ एनवायरमेंट में, एजेंट टूल के एक्ज़ीक्यूशन को सुरक्षित करना एक चुनौती है. अगर किसी एजेंट के पास नेटवर्क का सीधा ऐक्सेस है, तो प्रॉम्प्ट इंजेक्शन के हमलों या मॉडल के भ्रम की वजह से, एजेंट संवेदनशील डेटा को बाहर निकाल सकता है या नुकसान पहुंचाने वाले कमांड चला सकता है.
बड़े पैमाने पर ऑटोनॉमस एजेंट मैनेज करने के लिए, Agent Gateway एक ऐसा पॉइंट उपलब्ध कराता है जहां से सभी एजेंट को मैनेज किया जा सकता है. यह ज़ीरो-ट्रस्ट सिद्धांत पर काम करता है. इसे सीधे तौर पर Agent Platform के आर्किटेक्चर में इंटिग्रेट किया गया है. हर ऐप्लिकेशन या एजेंट कोड के लिए, कस्टम तरीके से लागू करने के बजाय, एजेंट गेटवे प्लैटफ़ॉर्म लेवल पर नेटवर्क राउटिंग, एजेंट गवर्नेंस, और रनटाइम सुरक्षा उपलब्ध कराता है.
जब एजेंट गेटवे, इग्रेस (एजेंट-टू-एनीवेयर) मोड में काम करता है, तो यह गेटवे का इस्तेमाल करने के लिए कॉन्फ़िगर किए गए एजेंट से किए गए सभी आउटबाउंड अनुरोधों को प्रॉक्सी करता है. एजेंट के हर वर्कलोड अनुरोध की पुष्टि, यूनीक एजेंट आइडेंटिटी का इस्तेमाल करके की जाती है. साथ ही, Identity-Aware Proxy (IAP) की नीतियों का इस्तेमाल करके, अनुरोध को अनुमति दी जाती है. MCP टूल के कॉल को डाइनैमिक तरीके से डिकोड किया जाता है. साथ ही, नीति लागू करने के लिए उनकी जांच की जाती है. सुरक्षा एडमिन, ग्रेन्यूलर अनुमतियों को केंद्रीय रूप से लागू कर सकते हैं. इससे यह पक्का किया जा सकता है कि एजेंट सिर्फ़ मंज़ूरी वाले एंडपॉइंट और तरीकों का इस्तेमाल कर सकें.
आपने क्या बनाया है
- एजेंट गेटवे, इग्रेस (agent-to-anywhere) मोड में
- Identity-Aware Proxy (IAP) ऑथराइज़ेशन एक्सटेंशन
- एजेंट की पहचान के साथ एजेंट रनटाइम ADK एजेंट
- Google API और एमसीपी एंडपॉइंट के साथ एजेंट रजिस्ट्री
- आईएएम ऐक्सेस कंट्रोल के साथ अनुमति से जुड़ी नीतियां
- एमसीपी का इस्तेमाल करके क्वेरी करने के लिए BigQuery डेटासेट
पहली इमेज. कोडलैब का स्ट्रक्चर
आपको ये सब सीखने को मिलेगा
- स्ट्रक्चर्ड कॉन्फ़िगरेशन सीक्वेंस में एजेंट गेटवे को डिप्लॉय करने का तरीका
- अनुमति देने से जुड़ी नीतियों को ड्राय-रन मोड से लागू किए गए मोड में कैसे बदला जाता है
- एजेंट रजिस्ट्री में Google API एंडपॉइंट और एमसीपी सर्वर रजिस्टर करने का तरीका
- एजेंट गेटवे के लॉग का ऑडिट करके, इग्रेस डेटा ट्रैफ़िक से जुड़ी नीतियों की पुष्टि कैसे करें
आपको इन चीज़ों की ज़रूरत पड़ेगी
- बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट
- नेटवर्किंग सेवाएं, BigQuery डेटासेट, और एजेंट प्लैटफ़ॉर्म के संसाधन उपलब्ध कराने के लिए IAM अनुमतियां
- Google Cloud CLI (
gcloudऔरbqकॉम्पोनेंट) इंस्टॉल किया गया हो, साथ ही POSIX के साथ काम करने वाला शेल (bashयाzsh) - कमांड-लाइन टूल:
git,curl,jq(JSON प्रोसेसर), Python 3, औरuv(Python पैकेज मैनेजर)
2. कॉन्सेप्ट
डिप्लॉयमेंट का क्रम
गवर्नेंस कंट्रोल के साथ एजेंट गेटवे को डिप्लॉय करते समय, कॉन्फ़िगरेशन के क्रम का पालन करना ज़रूरी है. इससे एजेंट को शुरू होने पर ज़रूरी संसाधनों का ऐक्सेस मिल पाएगा और नेटवर्क अनुरोध पूरे हो पाएंगे.
इस कोडलैब में, डिप्लॉयमेंट के लिए इस क्रम का इस्तेमाल किया गया है:
- ड्राई-रन मोड में शुरू करें: अगर एजेंट रनटाइम को, गेटवे के पूरी तरह से चालू होने से पहले ही आउटबाउंड कॉल को गेटवे पर रूट करने के लिए कॉन्फ़िगर किया जाता है, तो वर्कलोड शुरू नहीं हो पाएगा.
DRY_RUNमोड में गेटवे ऑथराइज़ेशन एक्सटेंशन को कॉन्फ़िगर करने से यह पक्का होता है कि जब एजेंट ट्रैफ़िक गेटवे पर पहुंचता है, तो कोई भी अनुरोध नहीं छोड़ा जाता है. - सभी सेवाओं को रजिस्टर करें: एजेंट गेटवे का इस्तेमाल करने वाले सभी एजेंट, एमसीपी सर्वर, और एंडपॉइंट को एजेंट रजिस्ट्री में रजिस्टर करना होगा. रजिस्टर न किए गए किसी भी सोर्स या डेस्टिनेशन के लिए अनुरोध अस्वीकार कर दिए जाते हैं. Agent Runtime और Google MCP सर्वर पर डिप्लॉय किए गए एजेंट अपने-आप रजिस्टर हो जाते हैं. Google API के किसी भी एंडपॉइंट या कस्टम MCP सर्वर को मैन्युअल तरीके से रजिस्टर करना होगा.
- अनुमति देने से जुड़ी नीतियों को लागू करें: अनुमति देने से जुड़ी नीतियों का इस्तेमाल, रजिस्टर किए गए एजेंट को एजेंटिक कॉम्पोनेंट का ऐक्सेस देने के लिए किया जाता है. इसके लिए, एजेंट की पहचान करने वाले प्रिंसिपल को
roles/iap.egressorकी भूमिका दी जाती है और उसे टारगेट रजिस्ट्री रिसोर्स से बाइंड किया जाता है. ड्राई-रन मोड का इस्तेमाल करके, एजेंट के व्यवहार का आकलन करें. इसके बाद, नीतियां तय करें, ताकि चुने गए इग्रेस ट्रैफ़िक को गेटवे से होकर जाने की अनुमति दी जा सके. नीतियों को लागू करने के बाद,ENFORCEDमोड पर स्विच करें, ताकि गेटवे, गवर्नेंस की नीतियों को लागू कर सके.
दूसरी इमेज. डिप्लॉयमेंट का क्रम
इग्रेस रूटिंग टोपोलॉजी
आम तौर पर, गेटवे बैकएंड सेवाओं के लिए, आने वाले ट्रैफ़िक (इनग्रेस) को मैनेज करते हैं. एजेंट गेटवे, इग्रेस (एजेंट-टू-एनीवेयर) मोड में काम करता है. यह एजेंटिक वर्कलोड के लिए, सेंट्रलाइज़्ड और ज़ीरो-ट्रस्ट आउटबाउंड प्रॉक्सी के तौर पर काम करता है.
जब कोई एआई ऐप्लिकेशन या एजेंटिक वर्कलोड, किसी बाहरी टूल या एपीआई को चालू करने की कोशिश करता है, तो आउटबाउंड अनुरोध को एजेंट गेटवे इंटरसेप्ट करता है. इसके बाद, इसे गवर्नेस से जुड़ी नीतियों के हिसाब से जांचा जाता है. इसके बाद, इसे मंज़िल तक भेजा जाता है:
- निजी नेटवर्क (वीपीसी): आउटबाउंड ट्रैफ़िक, जो एंटरप्राइज़ के इंटरनल एपीआई, माइक्रोसेवाओं, निजी वीपीसी में होस्ट किए गए डेटाबेस, और हाइब्रिड कनेक्टिविटी के ज़रिए ऐक्सेस किए जा सकने वाले कंपनी की इमारत में या क्रॉस-क्लाउड नेटवर्क को टारगेट करता है.
- बाहरी नेटवर्क (इंटरनेट): आउटबाउंड ट्रैफ़िक, तीसरे पक्ष की वेब सेवाओं, SaaS API या सार्वजनिक एंडपॉइंट को टारगेट करता है.
- एआई सेवाएं और एजेंट प्लैटफ़ॉर्म: मैनेज किए गए Google Cloud API, फ़ाउंडेशन मॉडल, Google MCP एंडपॉइंट (जैसे कि BigQuery), और प्लैटफ़ॉर्म गवर्नेंस सेवाओं (जैसे कि एजेंट रजिस्ट्री और IAP नीतियां) को टारगेट करने वाला आउटबाउंड ट्रैफ़िक.
तीसरी इमेज. एजेंट गेटवे से बाहर निकलने वाले ट्रैफ़िक की राउटिंग टोपोलॉजी
इस कोडलैब में, Agent Runtime पर मौजूद कस्टम एजेंट से BigQuery के लिए रिमोट Google एमसीपी सर्वर एंडपॉइंट को टारगेट करने वाले आउटबाउंड ट्रैफ़िक पर फ़ोकस किया गया है.
3. सेटअप
ज़रूरी IAM भूमिकाएं
इस कोडलैब में संसाधन बनाने के लिए, इन भूमिकाओं की ज़रूरत होती है:
कैटगरी | ज़रूरी IAM भूमिका (आईडी) | ब्यौरा |
एपीआई मैनेजमेंट |
| Google Cloud की एपीआई सेवाएं चालू करना |
नेटवर्किंग और गेटवे |
| एजेंट गेटवे को चालू करना |
सेवा एक्सटेंशन |
| रूटिंग एक्सटेंशन कॉन्फ़िगर करना |
नेटवर्क सिक्योरिटी |
| अनुमति से जुड़ी नीतियां डिप्लॉय करना |
एजेंट रजिस्ट्री |
| कैटलॉग के लिए अनुमति मिला हुआ होस्ट |
Vertex AI और एजेंट |
| एजेंट रनटाइम वर्कलोड डिप्लॉय करना |
इग्रेस नीतियां |
|
|
BigQuery |
| स्कीमा सेट अप करना और डेटासेट की जांच करना |
Cloud Storage |
| डिप्लॉयमेंट के लिए स्टेजिंग बकेट मैनेज करना |
लॉग और ऑडिटिंग |
| ट्रेस और ऑडिट लॉग की जांच करना |
इसके अलावा, roles/admin या लेगसी भूमिका roles/owner जैसी सामान्य भूमिका का इस्तेमाल करें.
अपने प्रोजेक्ट को ऐक्सेस करना
इस कोडलैब में, Google Cloud के किसी एक प्रोजेक्ट का इस्तेमाल किया जाता है. कॉन्फ़िगरेशन के चरणों में, gcloud सीएलआई और Linux शेल कमांड का इस्तेमाल किया जाता है.
सबसे पहले, अपने Google Cloud प्रोजेक्ट की कमांड लाइन ऐक्सेस करें:
- Cloud Shell में
shell.cloud.google.comपर जाएं या gcloudसीएलआई इंस्टॉल किया गया लोकल टर्मिनल
प्रोजेक्ट आईडी सेट करना
gcloud config set project SET_YOUR_PROJECT_ID_HERE
सेशन की पुष्टि करना
# login to gcloud cli
gcloud auth login
# login for gcloud api
gcloud auth application-default login
शेल एनवायरमेंट वैरिएबल सेट करना
# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}
# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-dj"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
# create local dir for config files
mkdir -p cfg
एपीआई सेवाएं चालू करना
# enable google apis (agent platform bundle, part 1)
gcloud services enable \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com \
apptopology.googleapis.com \
cloudapiregistry.googleapis.com \
cloudtrace.googleapis.com \
compute.googleapis.com \
dataform.googleapis.com \
iam.googleapis.com \
iamconnectors.googleapis.com \
iap.googleapis.com \
logging.googleapis.com \
modelarmor.googleapis.com \
monitoring.googleapis.com \
networksecurity.googleapis.com \
networkservices.googleapis.com \
notebooks.googleapis.com \
observability.googleapis.com
# enable google apis (agent platform bundle, part 2)
gcloud services enable \
securitycenter.googleapis.com \
saasservicemgmt.googleapis.com \
storage.googleapis.com \
telemetry.googleapis.com \
texttospeech.googleapis.com \
discoveryengine.googleapis.com
सेटअप का हिस्सा यहीं खत्म होता है... अब गेटवे सेक्शन पर जाएं.
4. गेटवे
ऐक्सेस कंट्रोल लागू करने से पहले, एजेंट गेटवे को डिप्लॉय करें. साथ ही, DRY_RUN मोड में इसके अनुमति एक्सटेंशन को कॉन्फ़िगर करें. इससे ऑडिट के लिए, आकलन के नतीजों को लॉग करते समय, आउटबाउंड टूल कॉल पूरे किए जा सकते हैं.
यहां Agent Gateway, क्षेत्रीय Agent Runtime संसाधनों के साथ काम करने के लिए, क्षेत्रीय रजिस्ट्री का इस्तेमाल करता है.
गेटवे बनाना
# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
- MCP
googleManaged:
governedAccessPath: AGENT_TO_ANYWHERE
registries:
- "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF
# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
--source="cfg/${AGW_NAME}.yaml" \
--location=${REGION}
# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
--location=${REGION}
गेटवे का हिस्सा यहीं खत्म होता है... अब अनुमति सेक्शन पर जाएं.
5. अनुमति देना
पहचान के बारे में जानकारी रखने वाली प्रॉक्सी (IAP) के लिए एजेंट गेटवे ऑथराइज़ेशन एक्सटेंशन, एक तरह का सेवा एक्सटेंशन है. इसका इस्तेमाल, सभी एजेंट प्लैटफ़ॉर्म कम्यूनिकेशन के लिए, ऑथराइज़ेशन से जुड़े फ़ैसले लेने के अधिकार को सौंपने के लिए किया जाता है.
- डेलिगेशन फ़्लो: जब कोई एजेंट किसी बाहरी एंडपॉइंट या एमसीपी सर्वर को चालू करने की कोशिश करता है, तो यह अनुरोध को एजेंट गेटवे पर भेज देता है. ऐक्सेस का आकलन स्थानीय तौर पर करने के बजाय, गेटवे, अनुमति देने वाले एक्सटेंशन का इस्तेमाल करके, IAP की आकलन सेवा को कॉलआउट भेजता है. आईएपी, एजेंट (एसपीआईएफ़ई पर आधारित) की पहचान की पुष्टि करता है. इसके लिए, एजेंट रजिस्ट्री में मौजूद टारगेट रिसॉर्स की आईएएम नीति का इस्तेमाल किया जाता है. IAP, गेटवे को
ALLOWयाDENYका फ़ैसला वापस भेजता है. इसके बाद, गेटवे ट्रैफ़िक को आगे भेजता है या एचटीटीपी403 Forbiddenस्टेटस कोड के साथ उसे ब्लॉक कर देता है. - लागू करने के मोड:
DRY_RUNमोड में, IAP अनुरोधों का आकलन करता है और Cloud Logging में फ़ैसलों को लॉग करता है. हालांकि, इस दौरान ट्रैफ़िक को ब्लॉक नहीं किया जाता.ENFORCEमोड में, बिना अनुमति वाले एजेंट से किए गए किसी भी अनुरोध या बिना रजिस्टर किए गए टारगेट को तुरंत ब्लॉक कर दिया जाता है. - बाइंडिंग लेयर: सेवा एक्सटेंशन, Agent Gateway से कनेक्ट होता है. इसके लिए,
REQUEST_AUTHZप्रोफ़ाइल के साथ कॉन्फ़िगर की गई अनुमति देने की नीति का इस्तेमाल किया जाता है.
पुष्टि करने वाला एक्सटेंशन
अनुमति देने वाला एक्सटेंशन बनाना
# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
iamEnforcementMode: "DRY_RUN"
iapPolicyVersion: "V1"
EOF
# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
--source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
--location=${REGION}
# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
--location=${REGION}
प्राधिकरण नीति
अनुमति देने से जुड़ी नीति, सुरक्षा सेवा देने वाली कंपनी (IAP) को टारगेट गेटवे रिसॉर्स से जोड़ती है. साथ ही, इंटरसेप्शन प्रोफ़ाइल (REQUEST_AUTHZ) के बारे में बताती है.
अनुमति देने की नीति बनाना
# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
resources:
- "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
authzExtension:
resources:
- "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF
# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
--source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
--location=${REGION}
# show authz policy details (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
--location=${REGION}
ऑथराइज़ेशन से जुड़ा हिस्सा यहीं खत्म होता है... अब कोडबेस सेक्शन पर जाएं.
6. कोडबेस
इस कोडलैब के लिए इस्तेमाल किया गया एजेंट कोड, BigQuery डेटासेट, और रजिस्ट्रेशन स्क्रिप्ट, रिमोट Google Cloud GitHub रिपॉज़िटरी में सेव की जाती है. इन चरणों को पूरा करने पर, रिपॉज़िटरी को स्थानीय तौर पर क्लोन किया जाएगा. इसके बाद, ज़रूरी फ़ाइलों को मौजूदा वर्किंग डायरेक्ट्री स्ट्रक्चर में कॉपी किया जाएगा. इसके बाद, गैर-ज़रूरी अस्थायी फ़ाइलों को मिटा दिया जाएगा.
एजेंट रनटाइम के लिए, स्टोरेज का एक स्टैगिंग बकेट बनाया जाता है. इसका इस्तेमाल, पैकेज किए गए एजेंट ऐप्लिकेशन कोड और उसकी डिपेंडेंसी आर्टफ़ैक्ट को अपलोड, बिल्ड, और डिप्लॉय करने के लिए किया जाता है.
रिमोट आर्टफ़ैक्ट फ़ेच करना
# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_gmcp
# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints
# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp
BigQuery डेटासेट बनाना
# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
--use_legacy_sql=false < agent-dj/setup.sql
स्टेजिंग बकेट बनाना
# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}
# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"
कोडबेस का हिस्सा यहीं खत्म होता है... अब रजिस्ट्री सेक्शन पर जाएं.
7. रजिस्ट्री
एजेंट रजिस्ट्री, एआई के पूरे नेटवर्क में मौजूद सभी एजेंट, एमसीपी सर्वर, और एंडपॉइंट (एपीआई) की एक सेंट्रलाइज़्ड इन्वेंट्री होती है. यह एक कैटलॉग भी है. इसका इस्तेमाल, एआई ऐप्लिकेशन के लिए रजिस्टर किए गए अन्य टूल और सेवाओं को खोजने, उनकी सूची बनाने, और उन्हें ढूंढने के लिए किया जा सकता है. एजेंट गेटवे इग्रेस (agent-to-anywhere) मोड, इग्रेस ऐक्सेस कंट्रोल लागू करने के लिए, रजिस्ट्री डेटा मॉडल का इस्तेमाल करता है. प्रिंसिपल कॉलिंग एजेंट के लिए IAM रोल की अनुमतियों की जांच, रजिस्ट्री संसाधन से जुड़ी नीति के हिसाब से की जाती है.
एजेंट को अलग-अलग Google API और सेवाओं का इस्तेमाल करने की सुविधा देने के लिए, एनवायरमेंट को बूटस्ट्रैप किया जाता है. इसके लिए, एक स्क्रिप्ट का इस्तेमाल किया जाता है. यह स्क्रिप्ट, endpoints/googleapis.txt से होस्टनेम और लोकेशन का इस्तेमाल करके, एपीआई एंडपॉइंट के सामान्य सेट को तुरंत रजिस्टर करती है.
एंडपॉइंट रजिस्टर करना
# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
--multi-region=${MREGION} \
--region=${REGION} \
--mtls-endpoints=include
एंडपॉइंट की पुष्टि करना
# list regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
--format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"
रजिस्ट्री वाला सेक्शन यहीं खत्म होता है... अब रनटाइम सेक्शन पर जाएं.
8. रनटाइम
Agent Runtime में डिप्लॉय किए गए agent-dj ADK एजेंट को, Agent Platform के साथ इंटिग्रेट करने के लिए डिप्लॉयमेंट स्क्रिप्ट में इन सेटिंग के साथ कॉन्फ़िगर किया जाता है:
"identity_type": types.IdentityType.AGENT_IDENTITYएजेंट के लिए, SPIFFE पर आधारित यूनीक प्रिंसिपल आइडेंटिटी उपलब्ध कराने के लिए"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }का इस्तेमाल करके, एजेंट की ओर से शुरू किए गए सभी आउटबाउंड ट्रैफ़िक को नीति के उल्लंघन का आकलन करने और उसे लागू करने के लिए, एजेंट गेटवे पर भेजें
एजेंट को डिप्लॉय करना
# deploy agent runtime workload
uv --directory agent-dj run python3 deploy_agent.py \
--project=${PROJ_ID} \
--region=${REGION} \
--src-dir=./agent \
--staging-bucket=${STAGING_BUCKET} \
--display-name="${RE_AGENT_NAME}" \
--description="agent for dj contact info" \
--enable-telemetry \
--enable-agent-identity \
--agent-gateway-egress=${AGW_URI} \
--allow-token-sharing
डिप्लॉयमेंट की परफ़ॉर्मेंस से जुड़ी अहम जानकारी फ़ेच करना
# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
"https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
jq -r --arg name "${RE_AGENT_NAME}" \
'.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}
# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
--location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
--format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}
# fetch agent registry uid for agent
export AGENT_UID=$(gcloud agent-registry agents list \
--location=${REGION} \
--filter="displayName=${RE_AGENT_NAME}" \
--format="value(uid)")
echo ${AGENT_UID}
रजिस्ट्री एंट्री की पुष्टि करना
# show agent resource registry details
gcloud agent-registry agents describe ${AGENT_UID} --location=${REGION}
agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
agentregistry.googleapis.com/system/Framework:
framework: google-adk
agentregistry.googleapis.com/system/RuntimeIdentity:
principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
agentregistry.googleapis.com/system/RuntimeReference:
uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
- protocolBinding: HTTP_JSON
url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
- protocolBinding: HTTP_JSON
url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
गेटवे के कॉन्फ़िगरेशन की पुष्टि करना
# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
| jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'
संसाधनों के लिए एजेंट को IAM भूमिकाएं असाइन करना
संसाधनों के लिए IAM रोल असाइन करने की सुविधा की मदद से, एजेंट प्रिंसिपल आइडेंटिटी को BigQuery, MCP टूल (Google API के लिए), और अन्य ज़रूरी एआई प्लैटफ़ॉर्म सेवाओं को ऐक्सेस करने की अनुमति मिलती है. इन नीतियों को संसाधन लेवल पर IAM का इस्तेमाल करके लागू किया जाता है.
# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/bigquery.user"
# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/bigquery.dataViewer"
# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/mcp.toolUser"
# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/aiplatform.user"
# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/aiplatform.agentDefaultAccess"
# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/agentregistry.viewer"
# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/logging.logWriter"
# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/monitoring.metricWriter"
# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="roles/browser"
संसाधनों के लिए एजेंट की IAM भूमिकाओं की पुष्टि करना
# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
--flatten="bindings[].members" \
--filter="bindings.members:${RE_AGENT_IDENTITY}" \
--format="value(bindings.role)"
यह रनटाइम वाला हिस्सा पूरा हुआ... अब नीतियों वाले सेक्शन पर चलते हैं.
9. नीतियां
एजेंट गवर्नेंस की अनुमति देने वाली नीतियां, एआई एजेंट से एजेंट गेटवे के ज़रिए और डेस्टिनेशन (जैसे, BigQuery के लिए Google Cloud MCP सर्वर एंडपॉइंट) तक ट्रैफ़िक की अनुमति देती हैं. जब ट्रैफ़िक डेस्टिनेशन तक पहुंच जाता है, तब IAM की सामान्य अनुमतियां, डेटा का ऐक्सेस करने की अनुमति देती हैं. इन्हें पिछले सेक्शन में चालू किया गया था.
एजेंट गेटवे से डेटा बाहर भेजने के लिए IAM रोल की अनुमतियां, ऐक्सेस की ऐसी नीतियां लागू करती हैं जिनसे एजेंट प्रिंसिपल आइडेंटिटी को, रजिस्टर किए गए डेस्टिनेशन संसाधनों का ऐक्सेस मिल जाता है. यह ऐक्सेस, एजेंट गेटवे के ज़रिए मिलता है. नीतियों को एजेंट गेटवे लेवल पर लागू किया जाता है. साथ ही, Identity-Aware Proxy (IAP) की IAM नीतियों का इस्तेमाल करके इनकी पुष्टि की जाती है.
एजेंट गेटवे से बाहर निकलने के लिए, एजेंट को IAM भूमिकाएं असाइन करना
Agent Gateway, आने वाले अनुरोधों की जांच करता है. इससे यह पुष्टि की जाती है कि कॉल करने वाले एजेंट की पहचान की पुष्टि हो गई है और उसके पास टारगेट संसाधन पर iap.webServiceVersions.egressViaIAP अनुमति है. यह अनुमति, roles/iap.egressor की भूमिका के तहत दी जाती है.
चुने गए डेस्टिनेशन रिसॉर्स पर, एजेंट आइडेंटिटी या एजेंट रनटाइम प्रिंसिपल सेट को roles/iap.egressor की अनुमति देने से, इस इग्रेस ट्रैफ़िक की अनुमति मिल जाती है. इस कोडलैब में, भूमिका को मुख्य सेट पर लागू किया जाता है. इससे प्रोजेक्ट में मौजूद सभी एजेंट रनटाइम एजेंट आइडेंटिटी को अनुमति मिल जाती है.
IAM नीतियां, डेस्टिनेशन रिसॉर्स से जुड़ी होती हैं. इनके बारे में एजेंट रजिस्ट्री के डेटा मॉडल में बताया गया है. iap_web/agentRegistry संसाधन, IAM हैरारकी में "रजिस्ट्री-वाइड" लेवल को दिखाता है. यहां agentRegistry, agents, mcpServers, और endpoints के लिए अलग-अलग चाइल्ड रिसॉर्स के पैरंट के तौर पर काम करता है. इस कोडलैब में, IAM नीति को रजिस्ट्री लेवल पर बाइंड किया गया है. इससे सभी चाइल्ड रिसॉर्स को अनुमति मिलती है.
IAP की रीजनल रजिस्ट्री के लिए IAM नीति कॉन्फ़िगर करना
# show iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}
# retrieve active etag on policy for regional registry
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
echo ${IAP_ETAG}
# create policy config file
cat > cfg/iap-policy-re-agent-set-to-registry-${REGION}.json << EOF
{
"bindings": [
{
"role": "roles/iap.egressor",
"members": [
"${RE_AGENT_ID_SET}"
]
}
],
"etag": "${IAP_ETAG}"
}
EOF
# import policy file (bind iam policy)
gcloud beta iap web set-iam-policy cfg/iap-policy-re-agent-set-to-registry-${REGION}.json \
--resource-type=agent-registry \
--region=${REGION}
# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}
नीतियों से जुड़ा सेक्शन यहीं खत्म होता है... अब ऑडिट सेक्शन पर चलते हैं.
10. ऑडिट
Agent Gateway authorization एक्सटेंशन, DRY_RUN मोड में काम कर रहा है. आउटबाउंड अनुरोधों को देखा और लॉग किया जाता है, लेकिन उन्हें ब्लॉक नहीं किया जाता.
एजेंट की क्वेरी की जांच करना
Google Cloud Console के यूज़र इंटरफ़ेस (यूआई) के लिए ब्राउज़र विंडो खोलें और यहां जाएं:
- Agent Platform → Agents → Deployments →
agent-dj - प्लेग्राउंड टैब चुनें
इसके अलावा, इस टर्मिनल कमांड को गूंजें और एजेंट के प्लेग्राउंड पर जाने के लिए लिंक पर क्लिक करें:
# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"
कुछ टेस्ट क्वेरी सबमिट करें....
How many DJs do we have on file?What is the phone number of DJ Cosmopup?
पुष्टि करें कि क्वेरी से मान्य जवाब मिलते हों. जैसे, "फ़ाइल में 12 डीजे हैं".
ऑडिट लॉग का विश्लेषण करना
लॉग देखें और नीति के उल्लंघन की जांच करने के लिए, ड्राई-रन के तौर पर किए गए आकलन की जांच करें.
# query gateway logs for dry run
gcloud logging read \
"resource.type=\"networkservices.googleapis.com/Gateway\" \
AND httpRequest.requestUrl:*" \
--project=${PROJ_ID} \
--limit=10 \
--format="table(
timestamp.date(tz=LOCAL):label=TIMESTAMP,
httpRequest.requestMethod:label=METHOD,
httpRequest.status:label=STATUS,
jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
httpRequest.requestUrl:label=URL
)"
TIMESTAMP METHOD STATUS IAP_AUTHZ MCP_METHOD URL
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED tools/call https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED tools/call https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS POST 200 ALLOWED tools/call https://bigquery.googleapis.com/mcp
ऑडिट का यह हिस्सा यहीं खत्म होता है... अब लागू करें सेक्शन पर जाएं.
11. लागू करें
एजेंट, DRY_RUN मोड में गेटवे के ज़रिए अनुरोध कर सका. अनुमति देने की नीति को अपडेट करके, Agent Gateway IAP के लिए अनुमति देने वाले एक्सटेंशन को ENFORCE मोड में बदलें.
अनुमति देने वाले एक्सटेंशन को अपडेट करना
# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
iapPolicyVersion: "V1"
EOF
# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
--source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
--location=${REGION}
# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}
अनुमति से जुड़ी नीति अपडेट करना
# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
resources:
- "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
authzExtension:
resources:
- "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF
# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
--source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
--location=${REGION}
# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
--location=${REGION}
एनफ़ोर्समेंट की पुष्टि करना
कंसोल के यूज़र इंटरफ़ेस (यूआई) में, एजेंट Playground पर वापस जाएं.
जांच के लिए कोई और क्वेरी सबमिट करें...
What DJ Fishfry's credit card number?
ध्यान दें कि Gemini foundation मॉडल (${REGION}-aiplatform.googleapis.com/...) और एमसीपी सर्वर एंडपॉइंट (bigquery.googleapis.com/mcp) को भेजे गए एजेंट के अनुरोध, एचटीटीपी 200 OK स्टेटस कोड के साथ पास किए जाते हैं.
# show gateway logs for http requests
gcloud logging read \
"resource.type=\"networkservices.googleapis.com/Gateway\" \
AND httpRequest.requestUrl:*" \
--project=${PROJ_ID} \
--limit=10 \
--format="table(
timestamp.date(tz=LOCAL):label=TIMESTAMP,
httpRequest.requestMethod:label=METHOD,
httpRequest.status:label=STATUS,
jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
httpRequest.requestUrl:label=URL)"
देखें कि कोई अनुरोध ब्लॉक न किया गया हो. गेटवे के ऑडिट लॉग में, एचटीटीपी 403 Forbidden स्टेटस कोड के साथ, बाहर निकलने के किसी भी ऐसे अनुरोध को ढूंढें जिसे अस्वीकार कर दिया गया हो.
# show gateway logs for authz denies
gcloud logging read \
"resource.type=\"networkservices.googleapis.com/Gateway\" \
AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
--project=${PROJ_ID} \
--limit=10 \
--format="table(
timestamp.date(tz=LOCAL):label=TIMESTAMP,
httpRequest.requestMethod:label=METHOD,
httpRequest.status:label=STATUS,
jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
)"
नीति उल्लंघन ठीक करने से जुड़ा सेक्शन यहां खत्म होता है... अब सफ़ाई सेक्शन पर चलते हैं.
12. साफ़-सफ़ाई सेवा
# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
# next
# remove agent resource iam bindings
for ROLE in \
"roles/bigquery.user" \
"roles/bigquery.dataViewer" \
"roles/mcp.toolUser" \
"roles/aiplatform.user" \
"roles/aiplatform.agentDefaultAccess" \
"roles/agentregistry.viewer" \
"roles/logging.logWriter" \
"roles/monitoring.metricWriter" \
"roles/browser"; do
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
--member="${RE_AGENT_IDENTITY}" \
--role="${ROLE}"
done
# next
# delete storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}
# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds
# next
# reset/clear iap regional registry iam policy
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
"bindings": [],
"etag": "${IAP_ETAG}"
}
EOF
gcloud beta iap web set-iam-policy cfg/iap-policy-empty.json \
--resource-type=agent-registry \
--region=${REGION}
# next
# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}
gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION}
gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION}
# next
# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints
# end
सफ़ाई का काम यहीं खत्म होता है... अब निष्कर्ष पर आते हैं!
13. नतीजा
बधाई हो! आपने Agent Gateway का इस्तेमाल करके टूल ऐक्सेस करने वाले एजेंट के लिए, आउटबाउंड कम्यूनिकेशन को सफलतापूर्वक डिप्लॉय और मैनेज कर लिया है!

Cosmopup को Codelabs बहुत पसंद हैं!
आगे क्या करना है?
- ज़्यादा सुविधाओं और ट्यूटोरियल के लिए, Gemini Enterprise Agent Platform के दस्तावेज़ देखें
- एआई को ज़्यादा सुरक्षित रखने के लिए, Agent Gateway पर Model Armor के गार्डरेल कॉन्फ़िगर करना
- नैचुरल लैंग्वेज क्वेरी के लिए, कारोबार के नियमों और अनुपालन को लागू करने के लिए, सिमेंटिक गवर्नेंस की नीतियां देखें
इस फ़ीडबैक फ़ॉर्म का इस्तेमाल करके, बेझिझक कोई टिप्पणी करें, सवाल पूछें या सुधार के बारे में बताएं
धन्यवाद!