1. परिचय
अगर किसी एजेंट के पास अपने क्रेडेंशियल हैं और उसे ज़्यादा अनुमतियां मिली हैं, तो वह सभी का डेटा देख सकता है. इस कोडलैब में, आपको एक ऐसा एजेंट बनाना होगा जो साइन इन किए हुए उपयोगकर्ता के क्रेडेंशियल का इस्तेमाल करके, तीसरे पक्ष के एपीआई को कॉल करे. इससे एजेंट को सिर्फ़ वही जानकारी दिखेगी जो उस व्यक्ति को दिखती है.
इसे Google Agent Development Kit (ADK) और Gemini Enterprise की मदद से बनाया जाएगा.
खास तौर पर, आपको ड्यूअल-आइडेंटिटी आर्किटेक्चर डिज़ाइन करने का तरीका पता चलेगा. इसमें:
- एजेंट अपनी ओर से काम करता है (एजेंट की पहचान): SPIFFE की मदद से एजेंट की पहचान का इस्तेमाल करके, एजेंट Auth Manager को शुरू करता है, टेलीमेट्री को सेव करता है, और Google Cloud API को कॉल करता है.
- एजेंट, उपयोगकर्ता की ओर से काम करता है (यूज़र-डेलिगेटेड आइडेंटिटी): GitHub जैसे बाहरी संसाधनों को ऐक्सेस करने के लिए, एजेंट 3-लेग्ड OAuth (3LO) सहमति फ़्लो को ट्रिगर करता है. इससे उपयोगकर्ता के क्रेडेंशियल का इस्तेमाल करके, टूल को सुरक्षित तरीके से क्वेरी की जा सकती है.

ऐसा करने के लिए, आपको इनके बारे में जानकारी मिलेगी:
- एक ऐसा एडीके एजेंट बनाएं जो GitHub के मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर से कनेक्ट हो.
- एजेंट के टूल को स्टैटिक GitHub PAT (पर्सनल ऐक्सेस टोकन) से 3-लेग्ड OAuth (3LO) फ़्लो पर अपडेट करें. इसके लिए, Google Cloud Auth Manager का इस्तेमाल करें.
- एजेंट को एजेंट रनटाइम में सुरक्षित तरीके से डिप्लॉय करें और एजेंट आइडेंटिटी को ऐक्सेस या अनुमति दें.
- आईएएम की भूमिकाएं कॉन्फ़िगर करें, ताकि एजेंट की पहचान को उपयोगकर्ता की ओर से टोकन वॉल्ट का ऐक्सेस दिया जा सके.
- Google Cloud में Auth Manager के लिए, 3LO फ़्लो को शुरू से लेकर आखिर तक समझें.
ज़रूरी शर्तें
शुरू करने से पहले, पक्का करें कि आपके पास ये चीज़ें हों:
- बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट.
- आपके कंप्यूटर पर Google Cloud SDK (
gcloudसीएलआई) इंस्टॉल हो और आपके प्रोजेक्ट के लिए इसकी पुष्टि की गई हो. इसके लिए, 586.0.0 या इसके बाद का वर्शन ज़रूरी है —gcloud components updateचलाएं. - आपके डिवाइस पर Python 3.10 से 3.13 इंस्टॉल होना चाहिए.
uvपैकेज मैनेजर इंस्टॉल किया गया हो (pip install uv).- OAuth ऐप्लिकेशन को रजिस्टर करने और टोकन बनाने के लिए, GitHub खाता. अगर आपके पास GitHub खाता नहीं है, तो तीसरे पक्ष के किसी ऐसे एमसीपी सर्वर का इस्तेमाल किया जा सकता है जो थ्री-लेग्ड OAuth 2.0 के साथ काम करता हो.
2. प्रोजेक्ट सेटअप
1. Google Cloud पर पुष्टि करना
अपनी लोकल कमांड लाइन से Google Cloud में पुष्टि करें. इससे यह पक्का किया जा सकेगा कि आपके एनवायरमेंट के पास, इस लैब के दौरान Agent Runtime में डिप्लॉय करने, एजेंट की पहचान की जानकारी देने, और Auth Manager को कॉन्फ़िगर करने के लिए ज़रूरी अनुमतियां हों.
अपने Google Cloud खाते में साइन इन करने, अपना ऐक्टिव क्लाउड प्रोजेक्ट सेट करने (YOUR_PROJECT_ID को अपने Google Cloud प्रोजेक्ट आईडी से बदलें), और ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) को कॉन्फ़िगर करने के लिए, ये कमांड चलाएं:
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. Google Cloud की ज़रूरी सेवाएं चालू करना
इस लैब को चलाने के लिए, अपने Google Cloud प्रोजेक्ट में ज़रूरी एपीआई चालू करें. अपने टर्मिनल में यह कमांड चलाएं:
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
इस निर्देश को लागू होने में एक मिनट लग सकता है. इसके बाद, यह कमांड प्रॉम्प्ट पर वापस आ जाएगा. इससे पुष्टि होगी कि एपीआई चालू हैं.
3. एजेंट सीएलआई इंस्टॉल करना और प्रोजेक्ट सेट अप करना
agents-cli एक कमांड-लाइन टूल है. इसका इस्तेमाल, Gemini Enterprise में ADK एजेंट को स्कैफ़ोल्ड, मैनेज, टेस्ट, और डिप्लॉय करने के लिए किया जाता है. इसे स्थानीय तौर पर इंस्टॉल करें:
uvx google-agents-cli setup
इंस्टॉलेशन की पुष्टि करना:
agents-cli --help
आपको सीएलआई का सहायता मेन्यू दिखेगा. इसमें उपलब्ध कमांड दिखेंगे, जैसे कि deploy, run, और status.
प्रोजेक्ट का शुरुआती ढांचा जनरेट करना. आपको लोकल प्रोटोटाइप से शुरुआत करनी होगी. इसके बाद, एजेंट रनटाइम डिप्लॉयमेंट के लिए इसे बेहतर बनाना होगा:
agents-cli create secure-agent-demo --prototype --yes
इससे secure-agent-demo डायरेक्ट्री बन जाती है. इसमें आपके एजेंट का बुनियादी कोड, डिपेंडेंसी, और टेस्ट फ़ाइलें होती हैं.
4. एडीके की ज़रूरी अतिरिक्त सुविधाएं जोड़ें
जनरेट किए गए pyproject.toml में, मौजूद नहीं होने वाले दो एक्स्ट्रा जोड़ें: GitHub टूलसेट के लिए mcp और लैब में बाद में इस्तेमाल किए जाने वाले Auth Manager के लिए agent-identity. secure-agent-demo/pyproject.toml खोलें और पूरा कोड बदलें
google-adk
डिपेंडेंसी लाइन:
"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",
इसके बाद, इन्हें इंस्टॉल करें:
cd secure-agent-demo
agents-cli install
3. एजेंट को बनाना और उसकी जांच करना
1. एजेंट बनाएं
अपने प्रोजेक्ट में, secure-agent-demo/app/agent.py में मौजूद कोड को बदलें और उसकी जगह यह कोड डालें:
# app/agent.py
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from app.tools import github_toolset
import os
import google.auth
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.
Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""
root_agent = Agent(
name="root_agent",
model=Gemini(
model="gemini-3.8-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=INSTRUCTION,
tools=[github_toolset()],
)
app = App(
root_agent=root_agent,
name="app",
)
इस फ़ाइल में, एजेंट के तीन मुख्य कॉम्पोनेंट के बारे में बताया गया है:
- सिस्टम से जुड़े निर्देश (
INSTRUCTION): इससे असिस्टेंट की पर्सनैलिटी सेट होती है और उसका दायरा GitHub के ट्राइएज तक सीमित होता है. साथ ही, सुरक्षा से जुड़े सख्त नियम लागू होते हैं. जैसे, रीड-ओनली ऐक्सेस और गड़बड़ियां होने पर उपयोगकर्ताओं को पुष्टि करने के लिए गाइड करना. - एजेंट कॉन्फ़िगरेशन (
root_agent): यहgemini-3.8-flashमॉडल का इस्तेमाल करके, ADKAgentको इंस्टैंशिएट करता है. साथ ही, एचटीटीपी अनुरोध को फिर से भेजने के लॉजिक को कॉन्फ़िगर करता है और एजेंट को GitHub टूलसेट से लैस करता है. - ऐप्लिकेशन रैपर (
app): यह रूट एजेंट को ADKAppकंटेनर में शामिल करता है, ताकि उसे एजेंट रनटाइम में डिप्लॉय किया जा सके.
2. GitHub MCP टूल जोड़ना
एजेंट, मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) का इस्तेमाल करके GitHub से कनेक्ट करता है. एमसीपी गेटवे कनेक्शन के पैरामीटर रजिस्टर करने के लिए, secure-agent-demo/app/tools.py पर एक नई फ़ाइल बनाएं. इस कोड को कॉपी करके चिपकाएं:
# app/tools.py
from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
def github_toolset() -> McpToolset:
"""Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url=GITHUB_MCP_URL,
headers={
"Authorization": f"Bearer {GITHUB_TOKEN}",
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
)
)
यह फ़ंक्शन एक ऐसा टूल बनाता है जो GitHub के एमसीपी सर्वर को कॉल करता है:
- एमसीपी टूलसेट (
McpToolset): यह GitHub की सुविधाओं को डाइनैमिक तौर पर खोजता है और उन्हें कॉल किए जा सकने वाले एजेंट टूल के तौर पर रजिस्टर करता है. - Connection Parameters (
StreamableHTTPConnectionParams): यह टूलसेट को GitHub के सार्वजनिक एमसीपी गेटवे पर ले जाता है. - अनुमति देने वाले हेडर: यह
GITHUB_TOKENको धारक टोकन के तौर पर इंजेक्ट करता है. साथ ही, सीधे ट्रांसपोर्ट लेयर पर सिर्फ़ पढ़ने वाला मोड (X-MCP-Readonly: true) लागू करता है.
3. GitHub पीएटी (पर्सनल ऐक्सेस टोकन) की मदद से, स्थानीय तौर पर टेस्ट करना
स्टैटिक क्रेडेंशियल के साथ एजेंट को लोकल लेवल पर चलाने के लिए:
- GitHub के Personal Access Tokens पेज पर जाकर, Fine-grained personal access token बनाएं:
- नया टोकन जनरेट करें पर क्लिक करें और अपने टोकन को कोई नाम दें.
- Repository access में जाकर, All repositories को चुनें. इसके अलावा, डेटा स्टोर करने की वे जगहें चुनें जिन्हें आपको टेस्ट करना है.
- अनुमतियां > रिपॉज़िटरी में जाकर, +अनुमतियां जोड़ें पर क्लिक करें. इसके बाद, कॉन्टेंट, समस्याएं, और पुल के अनुरोध को सिर्फ़ पढ़ने के लिए पर सेट करें. मेटाडेटा, सिर्फ़ पढ़ने के लिए पर अपने-आप सेट हो जाता है.
- टोकन जनरेट करें पर क्लिक करें और जनरेट किए गए टोकन की वैल्यू को कॉपी करें. (इसके अलावा, अगर Personal access token (classic) का इस्तेमाल किया जाता है, तो
repoस्कोप चुनें.)
- इसे अपने एनवायरमेंट में सेट करें:
export GITHUB_TOKEN="your_github_pat_here" secure-agent-demoफ़ोल्डर पर जाएं (अगर आप पहले से उसमें नहीं हैं) और लोकल प्लेग्राउंड शुरू करें:cd secure-agent-demo agents-cli playground- प्लेग्राउंड इंटरफ़ेस खोलें और ड्रॉप-डाउन से फ़ोल्डर
appचुनें. चैटबॉक्स में,"Get the last 2 GitHub issues reported against my name"या"List my 3 most recently updated repositories"जैसा कोई टारगेट किया गया प्रॉम्प्ट आज़माएं. साथ ही, पुष्टि करें कि एजेंट, GitHub एमसीपी टूलसेट को कॉल करता है और आपका GitHub डेटा दिखाता है. अगर आपको यह जांच करनी है कि एजेंट आपकी ओर से कार्रवाई करने के लिए, आपके पीएटी टोकन का इस्तेमाल कर रहा है या नहीं, तो उससे अपनी निजी रिपॉज़िटरी या योगदान के बारे में पूछें.
4. Auth Manager को कॉन्फ़िगर करना
प्रोटोटाइपिंग के लिए, पीएटी जैसे स्टैटिक क्रेडेंशियल को हार्डकोड करना आसान होता है. हालांकि, इससे प्रोडक्शन ऐप्लिकेशन के क्रेडेंशियल लीक होने, मैन्युअल तरीके से टोकन रीफ़्रेश करने के दौरान डाउनटाइम होने, और क्लाउड-नेटिव ऐक्सेस कंट्रोल की कमी होने का खतरा रहता है.
इस समस्या को हल करने के लिए, Google Cloud Agent Identity Auth Manager उपलब्ध कराता है. Agent Identity auth manager, क्रेडेंशियल वॉल्ट है. इसे क्रेडेंशियल सुरक्षित रखने के लिए डिज़ाइन किया गया है. इसकी मदद से, एजेंट एपीआई पासकोड या OAuth क्लाइंट आईडी और सीक्रेट का इस्तेमाल करके अपनी पहचान की पुष्टि कर सकते हैं. इसके अलावा, असली उपयोगकर्ता के ऐक्सेस टोकन का इस्तेमाल करके, OAuth डेलिगेशन के ज़रिए किसी उपयोगकर्ता की ओर से भी पहचान की पुष्टि की जा सकती है.
Auth Manager में, पुष्टि करने की सेवा देने वाली कंपनियों को कॉन्फ़िगर किया जाता है. ये कंपनियां, तीसरे पक्ष के खास ऐप्लिकेशन के लिए, पुष्टि करने के तरीके और क्रेडेंशियल तय करती हैं. पुष्टि करने की सुविधा देने वाली कंपनियां, क्षेत्र के हिसाब से होती हैं. इसलिए, यह ज़रूरी है कि एजेंट को उसी क्षेत्र में डिप्लॉय किया जाए जहां पुष्टि करने की सुविधा देने वाली कंपनी मौजूद है. Auth Manager का एंड-टू-एंड वर्कफ़्लो इस तरह काम करता है:

- डाइनैमिक सहमति इंटरसेप्शन: जब एजेंट किसी उपयोगकर्ता की ओर से कोई टूल इस्तेमाल करने की कोशिश करता है, तो ADK, Auth Manager में जाकर यह देखता है कि उपयोगकर्ता के पास मान्य क्रेडेंशियल है या नहीं. अगर कोई क्रेडेंशियल मौजूद नहीं है, तो Auth Manager एक अनुमति यूआरएल दिखाता है. इससे 3-legged OAuth (3LO) सहमति फ़्लो शुरू होता है.
- वॉल्ट में सुरक्षित स्टोरेज: असली उपयोगकर्ता से ऐप्लिकेशन को अनुमति मिलने के बाद, Auth Manager अपने-आप OAuth कॉलबैक को इंटरसेप्ट करता है. साथ ही, उपयोगकर्ता के ऐक्सेस और रीफ़्रेश टोकन को Google के मैनेज किए जाने वाले सुरक्षित क्रेडेंशियल वॉल्ट में सेव करता है.
- टोकन लाइफ़साइकल अपने-आप मैनेज होने की सुविधा: Auth Manager, बैकग्राउंड में टोकन की समयसीमा खत्म होने और उसे रोटेट करने की प्रोसेस को पूरी तरह से मैनेज करता है. इससे टोकन को मैन्युअल तरीके से रीफ़्रेश करने या डाउनटाइम की ज़रूरत नहीं पड़ती.
- सीक्रेट-फ़्री टूल एक्ज़ीक्यूशन: बाद की कार्रवाइयों के लिए, एजेंट (अपनी SPIFFE एजेंट आइडेंटिटी के ज़रिए पुष्टि करने वाला) रनटाइम के दौरान, Auth Manager से उपयोगकर्ता के ऐक्सेस टोकन का अनुरोध करता है. इससे क्लाइंट और एजेंट, दोनों का कोड पूरी तरह से सीक्रेट-फ़्री रहता है.
पहला चरण: GitHub को पुष्टि करने वाले प्रोवाइडर के तौर पर कॉन्फ़िगर करना
अपने Google क्लाउड प्रोजेक्ट में GitHub से पुष्टि करने की सुविधा देने वाली सेवा बनाने के लिए, यह gcloud निर्देश चलाएं. क्लाइंट आईडी और सीक्रेट बाद में सबमिट किए जा सकते हैं: GitHub इन्हें तब तक जारी नहीं करेगा, जब तक उसे इस प्रोवाइडर के कॉलबैक यूआरएल की जानकारी नहीं मिल जाती.
gcloud agent-identity auth-providers create github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
--three-legged-oauth-token-url="https://github.com/login/oauth/access_token"
जनरेट किए गए OAuth रीडायरेक्ट यूआरएल को वापस पाने के लिए, सेवा देने वाली कंपनी के बारे में बताएं:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1"
यह फ़ील्ड redirectUrl है, जो authProviderTypeParams.threeLeggedOauth में नेस्ट किया गया है. इसे सीधे पढ़ने के लिए:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" --location="us-central1" \
--format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"
ऐसा लगता है कि https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.
दूसरा चरण: GitHub में OAuth ऐप्लिकेशन को रजिस्टर करना
- GitHub डेवलपर सेटिंग पेज पर जाएं. इसके बाद, बाईं ओर मौजूद साइडबार में OAuth ऐप्लिकेशन को चुनें और नया OAuth ऐप्लिकेशन पर क्लिक करें. अगर आपने पहले कोई ऐप्लिकेशन नहीं बनाया है, तो नया ऐप्लिकेशन रजिस्टर करें पर क्लिक करें.
- OAuth ऐप्लिकेशन फ़ॉर्म के फ़ील्ड भरें:
- ऐप्लिकेशन का नाम: अपने ऐप्लिकेशन का नाम डालें (उदाहरण के लिए,
secure-agent-demo). - होम पेज का यूआरएल: अपने फ़्रंटएंड ऐप्लिकेशन का यूआरएल डालें (लोकल प्रोटोटाइपिंग के लिए
http://localhost:8501; प्रोडक्शन में, इसे डिप्लॉय किए गए यूआरएल पर अपडेट किया जा सकता है). - ऐप्लिकेशन का ब्यौरा: ज़रूरी नहीं (इसे खाली छोड़ा जा सकता है).
- अनुमति देने के लिए कॉलबैक यूआरएल (रीडायरेक्ट यूआरआई): पहले चरण में मिले
redirectUrlको चिपकाएं. - Enable Device Flow: इस विकल्प से सही का निशान हटाएं.
- ऐप्लिकेशन का नाम: अपने ऐप्लिकेशन का नाम डालें (उदाहरण के लिए,
- Register application पर क्लिक करें.
- इसके बाद खुलने वाले ऐप्लिकेशन पेज पर, क्लाइंट आईडी को कॉपी करें. इसके बाद, नया क्लाइंट सीक्रेट जनरेट करें पर क्लिक करें और जनरेट किए गए क्लाइंट सीक्रेट को कॉपी करें. दोनों वैल्यू सेव करें — अगले चरण में, इनका इस्तेमाल
YOUR_GITHUB_CLIENT_IDऔरYOUR_GITHUB_CLIENT_SECRETके तौर पर किया जाएगा.
तीसरा चरण: पुष्टि करने वाली सेवा देने वाली कंपनी में GitHub क्रेडेंशियल जोड़ना
YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID, और YOUR_GITHUB_CLIENT_SECRET को अपनी वैल्यू से बदलें और यह कमांड चलाएं:
gcloud agent-identity auth-providers update github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
--three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"
कमांड, सेवा देने वाली कंपनी को clientId के साथ वापस भेजता है; सीक्रेट को वापस नहीं भेजा जाता.
👉 इस चरण को पूरा करने के बाद, आपका Google Cloud Auth Manager अब आपके GitHub OAuth ऐप्लिकेशन क्रेडेंशियल के साथ पूरी तरह से कॉन्फ़िगर हो गया है. इससे Google Cloud को एक सुरक्षित वॉल्ट के तौर पर सेट अप किया जाता है, जो सहमति और टोकन की लाइफ़साइकल को मैनेज करता है.
5. पीएटी टोकन को Auth Manager पर स्विच करना
Auth Manager को पूरी तरह से कॉन्फ़िगर करने के बाद, एजेंट के टूल कोड को अपडेट करें. secure-agent-demo/app/tools.py के कॉन्टेंट की जगह यह कोड डालें.
👉 नीचे दिए गए OAUTH_PROVIDER_NAME वैरिएबल में, प्रोजेक्ट आईडी और जगह की जानकारी बदलें.
# app/tools.py
from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())
# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"
# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
"OAUTH_CONTINUE_URI",
"http://localhost:8501/validateUserId"
)
def github_toolset() -> McpToolset:
"""Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
auth_scheme = GcpAuthProviderScheme(
name=OAUTH_PROVIDER_NAME,
# Required to read private repositories. Auth Manager currently supports a
# single scope for GitHub.
scopes=["repo"],
continue_uri=OAUTH_CONTINUE_URI,
)
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://api.githubcopilot.com/mcp/",
headers={
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
),
auth_scheme=auth_scheme,
)
टूल कोड को समझना
मुख्य बदलाव auth_scheme है. इसे टूलसेट से अटैच करने का मतलब है कि जब भी एजेंट GitHub को कॉल करेगा, तो ADK सबसे पहले Auth Manager से उस उपयोगकर्ता का टोकन मांगेगा. अगर अब तक कोई टोकन नहीं है, तो यह उपयोगकर्ता को साइन इन करने के लिए कहेगा. हार्डकोड किया गया GITHUB_TOKEN पूरी तरह से हटा दिया गया है.
6. एजेंट को एजेंट रनटाइम में डिप्लॉय करना
अब हमने GitHub MCP टूल को अपडेट कर दिया है, ताकि Auth Manager का इस्तेमाल किया जा सके. अगला चरण, एजेंट को Agent Runtime पर डिप्लॉय करना है. एजेंट आइडेंटिटी की सुविधा चालू करके इसे डिप्लॉय करने पर, एजेंट के लिए एक यूनीक SPIFFE आईडी जनरेट होता है.
प्रोजेक्ट के लिए डिप्लॉयमेंट कॉन्फ़िगरेशन को शुरू करें. पक्का करें कि आपका टर्मिनल, secure-agent-demo प्रोजेक्ट की रूट डायरेक्ट्री में हो. इसके बाद, यह कमांड चलाएं:
agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes
यह निर्देश, आपके प्रोजेक्ट के स्ट्रक्चर की जांच करता है, ताकि यह पता चल सके कि वह ADK के साथ काम करता है या नहीं. साथ ही, यह कंटेनर पैकेजिंग के कॉन्फ़िगरेशन तैयार करता है और आपके प्रोजेक्ट रूट में एक agents-cli-manifest.yaml फ़ाइल जनरेट करता है. इस फ़ाइल में, डिप्लॉयमेंट की डिफ़ॉल्ट सेटिंग अपने-आप जानकारी भरी होती हैं.
👉 नई बनाई गई agents-cli-manifest.yaml फ़ाइल खोलें. इसके बाद, region फ़ील्ड की पुष्टि करें या उसे us-central1 पर अपडेट करें. इससे यह पक्का किया जा सकेगा कि आपका एजेंट उसी इलाके में डिप्लॉय किया गया है जहां पुष्टि करने की सुविधा देने वाली सेवा मौजूद है:
region: "us-central1"
एजेंट की पहचान के साथ एजेंट को डिप्लॉय करना
adk deploy agent_engine की मदद से डिप्लॉय करें. इससे एजेंट को अपनी एजेंट आइडेंटिटी मिलती है. यह इस डिप्लॉयमेंट से जुड़ी एक यूनीक, SPIFFE-बैक्ड क्रिप्टोग्राफ़िक आइडेंटिटी होती है. एजेंट इसका इस्तेमाल, Auth Manager और Google Cloud की अन्य सेवाओं में अपनी पहचान की पुष्टि करने के लिए करता है.
👉 secure-agent-demo डायरेक्टरी में जाकर, YOUR_PROJECT_ID को बदलें और ये कमांड चलाएं:
# Write a config file inside the `app/` folder instructing Agent Runtime to provision a SPIFFE-backed `AGENT_IDENTITY` for this deployment.
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json
# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
--output-file app/requirements.txt
uv run adk deploy agent_engine app \
--project="YOUR_PROJECT_ID" \
--region="us-central1"
डिप्लॉयमेंट में, कंटेनर को बनाने और अपलोड करने में कुछ मिनट लगते हैं. इसके बाद, सीएलआई डिप्लॉय किए गए संसाधन का नाम दिखाता है. reasoningEngines/ENGINE_ID वैल्यू को नोट कर लें, क्योंकि आपको अपने एजेंट को अनुमति देने और यूज़र इंटरफ़ेस (यूआई) क्लाइंट को इस पर ले जाने के लिए इसकी ज़रूरत पड़ेगी.
एजेंट की पहचान की पुष्टि करना
अब आपका एजेंट क्लाउड में चल रहा है. इसलिए, उसे Auth Manager में सेव किए गए क्रेडेंशियल स्टोरेज ऐक्सेस करने की अनुमति चाहिए. डिफ़ॉल्ट रूप से, एजेंट की SPIFFE आइडेंटिटी के पास बाहरी क्लाउड संसाधनों का ऐक्सेस नहीं होता.
पुष्टि करने वाली सेवा देने वाली कंपनी के संसाधन पर, अपने एजेंट की पहचान को roles/agentidentity.user भूमिका देने के लिए, यहां दिया गया gcloud कमांड चलाएं. इससे आपके एजेंट को वे अनुमतियां मिलती हैं जो उसे वॉल्ट से उपयोगकर्ता टोकन का अनुरोध करने के लिए ज़रूरी हैं. इससे ज़्यादा अनुमतियां नहीं मिलतीं.
# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
--filter="type=organization" \
--format="value(id)"
# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
--format="value(projectNumber)"
इसके बाद, IAM नीति को पुष्टि करने वाली सेवा से बाइंड करें. इसके लिए, YOUR_PROJECT_ID और --member प्रिंसिपल को बदलें:
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"
👉 डिप्लॉय किए गए एजेंट के लिए, --member="principal://..." की पूरी वैल्यू Google Cloud Console से भी हासिल की जा सकती है: Agent Runtime कंसोल पर जाएं, डिप्लॉय किया गया एजेंट चुनें, पहचान टैब पर जाएं, और पूरी principal://... स्ट्रिंग को सीधे कॉपी करें.
अब सेवा देने वाली कंपनी के प्लैटफ़ॉर्म पर, अपने खाते को भी वही भूमिका असाइन करें. अगले चरण में चलाया जाने वाला यूज़र इंटरफ़ेस (यूआई) क्लाइंट, आपके ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल के साथ क्रेडेंशियल-फ़ाइनलाइज़ेशन एपीआई को कॉल करता है. इसलिए, इसके बिना सहमति का फ़्लो agentidentity.authProviders.retrieveCredentials पर 403 गड़बड़ी के साथ पूरा नहीं हो पाता:
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="user:YOUR_EMAIL_ADDRESS"
7. 3LO सहमति फ़्लो को समझना
अब एजेंट को सुरक्षित एजेंट आइडेंटिटी के साथ एजेंट रनटाइम पर डिप्लॉय कर दिया गया है. अगला चरण, उपयोगकर्ताओं को कस्टम फ़्रंटएंड इंटरफ़ेस उपलब्ध कराना है, ताकि वे एजेंट के साथ चैट कर सकें. सबसे ज़रूरी बात यह है कि Google Cloud Auth Manager को पुष्टि करने की प्रोसेस पूरी करने के लिए, क्लाइंट ऐप्लिकेशन कॉलबैक हैंडलर की ज़रूरत होती है.
Google Cloud Auth Manager, उपयोगकर्ता के क्रेडेंशियल को वॉल्ट में सुरक्षित तरीके से मैनेज करता है. हालांकि, यह OAuth टोकन एक्सचेंज को खुद पूरा नहीं कर सकता. 3LO हैंडशेक, क्लाइंट ऐप्लिकेशन पर निर्भर करता है, ताकि गैप को कम किया जा सके:
- जब कोई उपयोगकर्ता GitHub ऐप्लिकेशन को अनुमति देता है, तो GitHub उसे एजेंट की पहचान की पुष्टि करने वाली सेवा देने वाली कंपनी के
redirectUrlपर वापस रीडायरेक्ट कर देता है. - इसके बाद, Auth Manager उपयोगकर्ता के ब्राउज़र पॉप-अप को क्लाइंट-साइड कॉलबैक यूआरएल (
continue_uri) पर रीडायरेक्ट करता है. - इस रीडायरेक्ट को इंटरसेप्ट करना, ब्राउज़र की कुकी से नॉन्स को पढ़ना, और हैंडशेक को पूरा करने के लिए Google Cloud के
credentials:finalizeएंडपॉइंट को कॉल करना, क्लाइंट ऐप्लिकेशन की ज़िम्मेदारी है. - जब क्लाइंट एक्सचेंज की प्रोसेस पूरी कर लेता है, तब Google Cloud, टोकन को पुष्टि करने वाली सेवा देने वाली कंपनी के वॉल्ट में सुरक्षित तरीके से सेव कर लेता है. इससे एजेंट, GitHub टूल को कॉल कर पाता है.
कॉलबैक एंडपॉइंट को होस्ट करने वाले इस कस्टम क्लाइंट के बिना, हैंडशेक की प्रोसेस पूरी नहीं होती. साथ ही, वॉल्ट में क्रेडेंशियल सेव नहीं किए जा सकते.
इंटरैक्टिव OAuth 3LO फ़्लो, कई लेयर में फैला होता है. टूल के अनुरोध को पूरा करने की पूरी लाइफ़साइकल यहां दी गई है. हम यहां और अगले चरण में, इसके बारे में ज़्यादा जानकारी देंगे.
👉 इमेज को बड़ा करने के लिए, उस पर क्लिक करें.
हैंडशेक में क्लाइंट की मुख्य ज़िम्मेदारियां
- सहमति की चुनौती को रिले करना (पांचवां और छठा चरण): एजेंट, सहमति वाले यूआरएल और एक बार इस्तेमाल होने वाले नॉन्स के साथ
adk_request_credentialभेजता है. इसके बाद, क्लाइंट पॉप-अप खोलता है और नॉन्स को कुकी के तौर पर सेव करता है. - रीडायरेक्ट कॉलबैक को होस्ट करना (चरण 10-11):
/validateUserId, जहां सहमति मिलने के बाद, Auth Manager पॉप-अप भेजता है. - टोकन को फ़ाइनलाइज़ करना (चरण 12 से 14): रीडायरेक्ट से मिली पुष्टि की स्थिति को कैश मेमोरी में सेव किए गए नॉन्स के साथ जोड़ें. इसके बाद,
credentials:finalizeको कॉल करें, जो टोकन को वॉल्ट में सेव करता है.
अपना क्लाइंट बनाना
आपको लैब के लिए यह क्लाइंट लिखने की ज़रूरत नहीं है — अगले चरण में, पहले से बना क्लाइंट चलता है. अपने ऐप्लिकेशन में इसे लागू करने के लिए, इन दो रेफ़रंस का इस्तेमाल करें:
- Auth Manager के दस्तावेज़ में, अपने क्लाइंट-साइड ऐप्लिकेशन को अपडेट करें. इसमें, सहमति से जुड़ी समस्या को हल करने और
credentials:finalizeको कॉल करने के बारे में बताया गया है. - adk-python रिपॉज़िटरी में मौजूद सैंपल क्लाइंट को चलाया जा सकता है. ऊपर बताई गई तीनों ज़िम्मेदारियों को पूरी तरह से लागू करने के लिए,
main.pyपढ़ें.
8. यूज़र इंटरफ़ेस (यूआई) क्लाइंट को स्थानीय तौर पर चलाना
3LO सहमति फ़्लो के क्रम वाले डायग्राम में दिखाए गए तरीके के मुताबिक, Auth Manager ब्राउज़र विंडो को क्लाइंट-साइड कॉलबैक एंडपॉइंट पर वापस रीडायरेक्ट करता है. adk-python रिपॉज़िटरी में मौजूद सैंपल क्लाइंट, उस एंडपॉइंट को /validateUserId पर होस्ट करता है. इसे डाउनलोड करें और स्थानीय तौर पर चलाएं. इसके लिए, यह तरीका अपनाएं.
क्लाइंट फ़ाइलें डाउनलोड करना
adk-python में मौजूद contributing/samples/integrations/gcp_auth/client डायरेक्ट्री में, तीन मुख्य ऐसेट होती हैं:
main.py: FastAPI बैकएंड, जो आपके डिप्लॉय किए गए एजेंट इंजन से कनेक्ट होता है और OAuth टोकन को फ़ाइनलाइज़ करने के लिए,/validateUserIdकॉलबैक एंडपॉइंट को होस्ट करता है.static/: ब्राउज़र चैट यूज़र इंटरफ़ेस (यूआई) के लिए एचटीएमएल और JavaScript फ़ाइलें.requirements.txt: क्लाइंट सर्वर को चलाने के लिए ज़रूरी Python पैकेज.
adk-python एक बड़ी रिपॉज़िटरी है. इसलिए, सिर्फ़ contributing/samples/integrations/gcp_auth/client फ़ोल्डर डाउनलोड करने के लिए, Git की स्पार्स चेकआउट सुविधा का इस्तेमाल करें:
- सबसे पहले,
secure-agent-demoसे बाहर एक डायरेक्ट्री ऊपर जाएं, ताकि आप क्लाइंट को सिबलिंग फ़ोल्डर में क्लोन कर सकें:cd .. - सभी फ़ाइलें (
--no-checkout) डाउनलोड किए बिना, रिपॉज़िटरी के मेटाडेटा को क्लोन करने के लिए, ये निर्देश चलाएं. साथ ही, चेकआउट पाथ कोcontributing/samples/integrations/gcp_auth/clientतक सीमित करें और सिर्फ़ उस फ़ोल्डर को चेकआउट करें:git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git cd adk-python git sparse-checkout init --cone git sparse-checkout set contributing/samples/integrations/gcp_auth/client git checkout
क्लाइंट को चलाना
- आपने जिस
adk-pythonडायरेक्ट्री में अभी-अभी एंट्री की है उसमें मौजूदclientफ़ोल्डर पर जाएं:cd contributing/samples/integrations/gcp_auth/client - Python वर्चुअल एनवायरमेंट बनाएं और उसे चालू करें. इसके बाद,
requirements.txtसे क्लाइंट की डिपेंडेंसी इंस्टॉल करें:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - क्लाइंट को आपके Google Cloud प्रोजेक्ट, क्षेत्र (
us-central1), और डिप्लॉय किए गए Agent Engine आईडी (YOUR_ENGINE_ID) पर ले जाने वाले एनवायरमेंट वैरिएबल सेट करें. इसके बाद, पोर्ट8501पर लोकल FastAPI सर्वर को चालू करें:export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID export GOOGLE_CLOUD_LOCATION=us-central1 export AGENT_ID=YOUR_ENGINE_ID .venv/bin/uvicorn main:app --port 8501 - पुष्टि करें कि सर्वर सही तरीके से शुरू हो गया है और
http://localhost:8501पर सुन रहा है.
9. OAuth फ़्लो की जांच करना
अब सभी सेवाएं डिप्लॉय हो गई हैं, आईएएम बाइंडिंग कॉन्फ़िगर हो गई हैं, और एनवायरमेंट वैरिएबल सेट हो गए हैं. अब आपके पास असली उपयोगकर्ता को सुरक्षित तरीके से ऐक्सेस देने की प्रोसेस को टेस्ट करने का विकल्प है!
पहला चरण: टूल का इस्तेमाल शुरू करना
- कोई ब्राउज़र टैब खोलें और अपने क्लाइंट यूआरएल पर जाएं:
http://localhost:8501. - बाईं ओर मौजूद पैनल में, कॉन्फ़िगरेशन सेटिंग में जाकर, एजेंट टाइप को
Remote Agent (Vertex AI)(याRemote Agent Engine) पर सेट करें. - अपना Google Cloud प्रोजेक्ट आईडी और जगह (
us-central1) डालें. इसके बाद, रिमोट एजेंट लोड करें पर क्लिक करें. इससे आपके प्रोजेक्ट में डिप्लॉय किए गए एजेंट लोड होते हैं. - इंजन चुनें ड्रॉप-डाउन से, डिप्लॉय किया गया
appएजेंट चुनें. इसके बाद, सेटिंग सेव करें और लागू करें पर क्लिक करें. - चैट बॉक्स में, टारगेट की जाने वाली क्वेरी टाइप करें. जैसे, हाल ही की समस्याएं या रिपॉज़िटरी फ़ेच करना:
(याGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") और Enter दबाएं. - चैट यूज़र इंटरफ़ेस (यूआई) देखें: एजेंट के पास आपके उपयोगकर्ता सेशन के लिए अभी तक कोई क्रेडेंशियल नहीं है. इसलिए, उसे पुष्टि करने की चुनौती मिलती है. साथ ही, बातचीत के थ्रेड में 'पुष्टि करना ज़रूरी है' कार्ड दिखता है.
दूसरा चरण: थ्री-लेग्ड OAuth सहमति की प्रोसेस पूरी करना
- एक अलग ब्राउज़र पॉप-अप विंडो खुलेगी. यह आपको Google Cloud के Auth Manager के ज़रिए, GitHub OAuth के अनुमति वाले पेज पर रीडायरेक्ट करेगी.
- मांगी गई अनुमतियों की समीक्षा करें और अनुमति दें पर क्लिक करें.
- GitHub, Google Cloud पर रीडायरेक्ट करेगा. इसके बाद, Google Cloud पॉप-अप को आपके
localhostकॉलबैक यूआरएल/validateUserIdपर रीडायरेक्ट करेगा. - कॉलबैक सेवा, क्रेडेंशियल हैंडशेक को प्रोसेस और पूरा करती है.
तीसरा चरण: फिर से शुरू करना
- पॉप-अप विंडो बंद होने पर, पैरंट चैट टैब को अपने-आप पता चल जाता है कि विंडो बंद हो गई है.
- फ़्रंटएंड, एजेंट को फिर से शुरू करने का पेलोड भेजता है.
- एजेंट, Google Cloud Auth Manager से नए टोकन को सुरक्षित तरीके से हासिल करता है. इसके बाद, वह आपकी ओर से GitHub MCP टूल को कॉल करता है और आपके GitHub डेटा को सीधे चैट विंडो में स्ट्रीम करता है. यह ऐसा डेटा होता है जिसे एजेंट खुद ऐक्सेस नहीं कर सकता.
चौथा चरण: क्लाउड लॉग की जांच करना
यह पुष्टि करने के लिए कि टोकन एक्सचेंज और फ़ाइनलाइज़ेशन की प्रोसेस सुरक्षित तरीके से पूरी हुई है:
- Google Cloud Console के Logs Explorer पर जाएं.
- नॉन्स निकालने और पुष्टि होने की पुष्टि करने वाले सर्वर लॉग ढूंढें:
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - एजेंट के रनटाइम लॉग की जांच करना: इसके अलावा, सीधे Agent Platform Console में जाकर, एक्ज़ीक्यूशन लॉग देखे जा सकते हैं:
- Agent Runtime Console पर जाएं.
- सूची में से, डिप्लॉय किए गए एजेंट पर क्लिक करें.
- Playground टैब पर स्विच करें. इससे आपको सबसे नीचे मौजूद पैनल में, लाइव एजेंट के लॉग दिखेंगे. इनमें आपको एजेंट के रीज़निंग लूप, टूल के इस्तेमाल की जानकारी, और टोकन वापस पाने की लाइफ़साइकल की जानकारी रीयल टाइम में दिखेगी.
10. स्टोरेज में जगह बनाएं
Google Cloud पर लगातार लगने वाले शुल्कों से बचने के लिए, डिप्लॉय किए गए संसाधनों को हटाएं:
# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3
# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
--project=YOUR_PROJECT_ID --location=us-central1
# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.
# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID
# Optionally, delete the GitHub PAT Token and the OAuth app:
# https://github.com/settings/personal-access-tokens
डिवाइस पर मौजूद फ़ाइलें मिटाना
अगर आपको अपने लोकल एनवायरमेंट को पूरी तरह से क्लीन करना है, तो:
- लोकल uvicorn सर्वर को बंद करने के लिए, उस टर्मिनल में Ctrl+C दबाएं जहां यह चल रहा है.
- इस लैब के दौरान बनाई गई प्रोजेक्ट डायरेक्ट्री हटाएं:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. बधाई हो!
आपने साइन इन किए हुए उपयोगकर्ता की ओर से कार्रवाई करने वाला एजेंट बना लिया है और उसे सुरक्षित कर लिया है!
आपने क्या सीखा:
- एजेंट सिस्टम की पहचान: एजेंट, अपने खाते की पहचान के तहत कैसे काम करता है, ताकि वह जीसीपी इन्फ़्रास्ट्रक्चर के साथ सुरक्षित तरीके से इंटरफ़ेस कर सके, टेलीमेट्री लॉग मैनेज कर सके, और क्रेडेंशियल को फ़ाइनल करने वाले एपीआई को कॉल कर सके.
- उपयोगकर्ता की ओर से दी गई अनुमति: एजेंट, GitHub जैसे बाहरी प्लैटफ़ॉर्म पर उपयोगकर्ता की ओर से कार्रवाई करने की अनुमति कैसे मांगता है. इसके लिए, वह थ्री-लेग्ड OAuth (3LO) सहमति फ़्लो को ट्रिगर करता है.
- टूल का सुरक्षित इंटिग्रेशन: Google Cloud Auth Manager का इस्तेमाल करके, एडीके एजेंट को Model Context Protocol (MCP) सर्वर से कनेक्ट करने का तरीका. इससे हार्डकोड किए गए सीक्रेट इस्तेमाल करने के बजाय, उपयोगकर्ता के टोकन डाइनैमिक तौर पर फ़ेच किए जा सकते हैं.
- IAM नीति का कॉन्फ़िगरेशन: अनुमति देने वाली कंपनी के पास, एजेंट रनटाइम की पहचान और आपके खाते, दोनों की पुष्टि करने के लिए, बारीकी से अनुमति देने वाली बाइंडिंग सेट अप करने का तरीका.
इस बारे में और पढ़ें
- Agent Identity Auth Manager, ताकि पुष्टि करने के फ़्लो के कॉन्फ़िगरेशन और स्कोप को समझा जा सके.
- एजेंट रनटाइम के बारे में खास जानकारी
- एडीके से जुड़े दस्तावेज़
- मॉडल कॉन्टेक्स्ट प्रोटोकॉल
