Agent Identity और Auth Manager की मदद से, ऐसा एआई एजेंट बनाना जो उपयोगकर्ता की ओर से काम करे

1. परिचय

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

इसे Google Agent Development Kit (ADK) और Gemini Enterprise की मदद से बनाया जाएगा.

खास तौर पर, आपको ड्यूअल-आइडेंटिटी आर्किटेक्चर डिज़ाइन करने का तरीका बताया जाएगा. इसमें:

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

Dual Identity Architecture

इसके लिए, आपको इनके बारे में जानकारी मिलेगी:

  1. एक ऐसा एडीके एजेंट बनाएं जो GitHub के मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर से कनेक्ट हो.
  2. Google Cloud Auth Manager का इस्तेमाल करके, एजेंट के टूल को स्टैटिक GitHub PAT (निजी ऐक्सेस टोकन) से 3-लेग्ड OAuth (3LO) फ़्लो में अपडेट करें.
  3. एजेंट को एजेंट रनटाइम में सुरक्षित तरीके से डिप्लॉय करें और एजेंट आइडेंटिटी को ऐक्सेस या अनुमति दें.
  4. उपयोगकर्ता की ओर से, एजेंट की पहचान को टोकन वॉल्ट का ऐक्सेस देने के लिए, IAM भूमिकाएं कॉन्फ़िगर करें.
  5. Google Cloud में Auth Manager के लिए, 3LO के पूरे फ़्लो को समझें.

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

शुरू करने से पहले, पक्का करें कि आपके पास ये चीज़ें हों:

  • बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट.
  • आपके कंप्यूटर पर Google Cloud SDK (gcloud CLI) इंस्टॉल किया गया हो और आपके प्रोजेक्ट के लिए पुष्टि की गई हो. 586.0.0 या इसके बाद का वर्शन ज़रूरी है — gcloud components update चलाएं.
  • डिवाइस पर Python 3.10 से 3.13 इंस्टॉल होना चाहिए.
  • uv पैकेज मैनेजर इंस्टॉल किया गया हो (pip install uv).
  • OAuth ऐप्लिकेशन रजिस्टर करने और टोकन बनाने के लिए, GitHub खाता. अगर आपके पास GitHub खाता नहीं है, तो तीसरे पक्ष के किसी ऐसे MCP सर्वर का इस्तेमाल किया जा सकता है जो तीन लेग वाले OAuth 2.0 को सपोर्ट करता हो.

2. प्रोजेक्ट सेटअप करना

1. Google Cloud में पुष्टि करना

अपने लोकल कमांड लाइन से Google Cloud में पुष्टि करें. इससे यह पक्का किया जा सकेगा कि आपके एनवायरमेंट के पास, इस लैब के दौरान Agent Runtime में डिप्लॉय करने, एजेंट की पहचान देने, और Auth Manager को कॉन्फ़िगर करने के लिए ज़रूरी अनुमतियां हैं:

ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (एडीसी) कॉन्फ़िगर करने के लिए, अपने Google Cloud खाते में लॉगिन करने के लिए, यहां दिए गए कमांड चलाएं:

gcloud auth login
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. ज़रूरी ADK एक्स्ट्रा जोड़ना

जनरेट किए गए pyproject.toml में google-adk[gcp,otel-gcp] शामिल है. हालांकि, इसमें दो चीज़ें मौजूद नहीं हैं, जिनकी इस एजेंट को ज़रूरत है: 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. एजेंट बनाना

अपने प्रोजेक्ट में, 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 पर मौजूद समस्याओं को हल करने के लिए, Assistant को स्कोप किया जाता है. इसके अलावा, सुरक्षा से जुड़े सख्त नियम लागू किए जाते हैं. जैसे, सिर्फ़ पढ़ने का ऐक्सेस देना और गड़बड़ियां होने पर, उपयोगकर्ताओं को पुष्टि करने के लिए कहना.
  • एजेंट कॉन्फ़िगरेशन (root_agent): यह gemini-3.8-flash मॉडल का इस्तेमाल करके, ADK Agent को इंस्टैंटिएट करता है. साथ ही, एचटीटीपी फिर से कोशिश करने की सुविधा को कॉन्फ़िगर करता है और एजेंट को GitHub टूलसेट से लैस करता है.
  • ऐप्लिकेशन रैपर (app): यह रूट एजेंट को ADK App कंटेनर में शामिल करता है, ताकि इसे एजेंट रनटाइम में डिप्लॉय किया जा सके.

2. GitHub MCP टूल जोड़ना

यह एजेंट, मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) की मदद से GitHub से कनेक्ट होता है. एमसीपी गेटवे कनेक्शन के पैरामीटर रजिस्टर करने के लिए, 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 के एमसीपी सर्वर को कॉल करने वाला टूल बनाता है:

  • MCP टूलसेट (McpToolset): यह GitHub की सुविधाओं को, कॉल किए जा सकने वाले एजेंट टूल के तौर पर डाइनैमिक तरीके से ढूंढता है और रजिस्टर करता है.
  • कनेक्शन पैरामीटर (StreamableHTTPConnectionParams): यह टूलसेट को GitHub के सार्वजनिक एमसीपी गेटवे पर ले जाता है.
  • Authorization हेडर: GITHUB_TOKEN को Bearer टोकन के तौर पर इंजेक्ट करता है और ट्रांसपोर्ट लेयर पर सीधे तौर पर सिर्फ़ पढ़ने वाला मोड (X-MCP-Readonly: true) लागू करता है.

3. GitHub PAT (निजी ऐक्सेस टोकन) का इस्तेमाल करके, स्थानीय तौर पर टेस्ट करना

स्थैतिक क्रेडेंशियल के साथ एजेंट को स्थानीय तौर पर चलाने के लिए:

  1. GitHub का निजी ऐक्सेस टोकन बनाएं. उसे अपनी रिपॉज़िटरी का डेटा पढ़ने का ऐक्सेस दें. ऐसा न करने पर, एजेंट सिर्फ़ सार्वजनिक डेटा देख पाएगा और नीचे दिया गया प्रॉम्प्ट कोई नतीजा नहीं देगा.
  2. इसे अपने एनवायरमेंट में सेट करें: 
    export GITHUB_TOKEN="your_github_pat_here"
  3. secure-agent-demo फ़ोल्डर पर जाएं. रन: 
    cd secure-agent-demo
agents-cli playground
  4. प्लेग्राउंड इंटरफ़ेस खोलें. इसके बाद, ड्रॉपडाउन से "ऐप्लिकेशन" फ़ोल्डर चुनें. चैटबॉक्स में "Fetch my contributions across my private repositories over the last 6 months" टाइप करें. इसके बाद, पुष्टि करें कि एजेंट, GitHub टूल को कॉल करता है और आपकी निजी रिपॉज़िटरी से डेटा वापस लाता है.

4. Auth Manager को कॉन्फ़िगर करना

प्रोटोटाइप बनाने के लिए, स्टैटिक क्रेडेंशियल (जैसे कि PAT) को हार्डकोड करना आसान होता है. हालांकि, इससे प्रोडक्शन ऐप्लिकेशन में क्रेडेंशियल लीक होने का खतरा बढ़ जाता है. साथ ही, टोकन को मैन्युअल तरीके से रीफ़्रेश करने में लगने वाला समय बढ़ जाता है. इसके अलावा, क्लाउड-नेटिव ऐक्सेस कंट्रोल की कमी हो जाती है.

इस समस्या को हल करने के लिए, Google Cloud Agent Identity Auth Manager उपलब्ध कराता है. एजेंट आइडेंटिटी ऑथ मैनेजर, क्रेडेंशियल वॉल्ट है. इसे क्रेडेंशियल को सुरक्षित रखने के लिए डिज़ाइन किया गया है. इससे एजेंट, एपीआई पासकोड या OAuth क्लाइंट आईडी और सीक्रेट का इस्तेमाल करके पुष्टि कर सकते हैं. इसके अलावा, वे असली उपयोगकर्ता के ऐक्सेस टोकन का इस्तेमाल करके, OAuth डेलिगेशन के ज़रिए किसी उपयोगकर्ता की ओर से पुष्टि कर सकते हैं.

पुष्टि करने वाले मैनेजर में, पुष्टि करने वाले ऐसे प्रोवाइडर कॉन्फ़िगर किए जाते हैं जो तीसरे पक्ष के कुछ ऐप्लिकेशन के लिए, पुष्टि करने का टाइप और क्रेडेंशियल तय करते हैं. पुष्टि करने की सेवा देने वाली कंपनियां, क्षेत्र के हिसाब से काम करती हैं. इसलिए, यह ज़रूरी है कि सेवा देने वाली कंपनी का क्षेत्र, एजेंट को डिप्लॉय करने के क्षेत्र से मेल खाता हो. एंड-टू-एंड Auth Manager वर्कफ़्लो इस तरह काम करता है:

Auth Manager Workflow

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

पहला चरण: GitHub को पुष्टि करने की सेवा देने वाली कंपनी के तौर पर कॉन्फ़िगर करना

अपने Google Cloud प्रोजेक्ट में GitHub ऑथराइज़ेशन प्रोवाइडर बनाने के लिए, यह gcloud कमांड चलाएं. क्लाइंट आईडी और सीक्रेट बाद में उपलब्ध कराएं: GitHub, इन्हें तब तक जारी नहीं करेगा, जब तक उसे इस प्रोवाइडर के कॉलबैक यूआरएल के बारे में पता नहीं चल जाता.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${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="${PROJECT_ID}" \
    --location="us-central1"

यह फ़ील्ड redirectUrl है और इसे authProviderTypeParams.threeLeggedOauth में नेस्ट किया गया है. इसे सीधे तौर पर पढ़ने के लिए:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${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 ऐप्लिकेशन रजिस्टर करना

  1. GitHub डेवलपर सेटिंग पेज पर जाएं और नया OAuth ऐप्लिकेशन रजिस्टर करें पर क्लिक करें.
  2. होम पेज का यूआरएल के लिए, अपने फ़्रंटएंड ऐप्लिकेशन का यूआरएल डालें. उदाहरण के लिए, लोकल प्रोटोटाइपिंग के लिए http://localhost:8501. बाद में, इसे प्रोडक्शन में डिप्लॉय किए गए यूआरएल में बदला जा सकता है.
  3. रीडायरेक्ट यूआरआई को पिछले चरण में वापस लाए गए redirectUrl पर सेट करें.
  4. Register application पर क्लिक करें. इसके बाद, Generate a new client secret पर क्लिक करें. साथ ही, क्लाइंट आईडी और क्लाइंट सीक्रेट, दोनों को सेव करें.

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

अपने प्रोजेक्ट आईडी, क्लाइंट आईडी, और क्लाइंट सीक्रेट को बदलें और यह कमांड चलाएं:

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. PAT टोकन को Auth Manager पर स्विच करना

Auth Manager को पूरी तरह से कॉन्फ़िगर करने के बाद, अगला चरण एजेंट के टूल कोड को अपडेट करना है. अपने 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 आईडी मिलता है.

आइए, प्रोजेक्ट के लिए डिप्लॉयमेंट कॉन्फ़िगरेशन को शुरू करें. टर्मिनल में यह कमांड चलाएं:

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 की अन्य सेवाओं से पुष्टि करने के लिए करता है.

👉 इन कमांड को चलाने से पहले, YOUR_PROJECT_ID को बदलें:

# Request 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 कमांड चलाएं. इससे आपके एजेंट को सिर्फ़ वे अनुमतियां मिलती हैं जिनकी उसे वॉल्ट से उपयोगकर्ता टोकन का अनुरोध करने के लिए ज़रूरत होती है.

👉 YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER, और YOUR_ENGINE_ID को बदलें. इंजन आईडी, ऊपर दिए गए डिप्लॉय आउटपुट में मौजूद है.

YOUR_ORG_ID पाने के लिए, यहां दिया गया निर्देश चलाएं:

gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

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"

अब सेवा देने वाली कंपनी के खाते में, अपने खाते को वही भूमिका असाइन करें. अगले चरण में, यूज़र इंटरफ़ेस (यूआई) क्लाइंट, क्रेडेंशियल-फ़ाइनलाइज़ेशन एपीआई को आपके ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल के साथ कॉल करता है. इसलिए, इसके बिना सहमति लेने की प्रोसेस पूरी नहीं हो पाती और 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 हैंडशेक, क्लाइंट ऐप्लिकेशन पर निर्भर करता है, ताकि इस अंतर को कम किया जा सके:

  1. जब कोई उपयोगकर्ता GitHub ऐप्लिकेशन को अनुमति देता है, तो GitHub उसे वापस एजेंट की पहचान की पुष्टि करने वाले redirectUrl पर रीडायरेक्ट करता है.
  2. इसके बाद, Auth Manager, उपयोगकर्ता के ब्राउज़र के पॉप-अप को वापस क्लाइंट-साइड कॉलबैक यूआरएल (continue_uri) पर रीडायरेक्ट कर देता है.
  3. इस रीडायरेक्ट को रोकना, क्लाइंट ऐप्लिकेशन की ज़िम्मेदारी है. साथ ही, ब्राउज़र की कुकी से नॉनस पढ़ना और हैंडशेक पूरा करने के लिए, Google Cloud के credentials:finalize एंडपॉइंट को कॉल करना भी क्लाइंट ऐप्लिकेशन की ज़िम्मेदारी है.
  4. क्लाइंट के एक्सचेंज को फ़ाइनल करने के बाद, Google Cloud टोकन को पुष्टि करने वाले सेवा देने वाली कंपनी के वॉल्ट में सुरक्षित तरीके से सेव करता है. इससे एजेंट, GitHub टूल को कॉल कर सकता है.

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

इंटरैक्टिव OAuth 3LO फ़्लो, कई लेयर में फैला होता है. यहां टूल के अनुरोध को पूरा करने के लाइफ़साइकल की पूरी जानकारी दी गई है. हम इस बारे में नीचे दी गई जानकारी और अगले चरण में बताएंगे.

👉 इमेज को बड़ा करने के लिए, उस पर क्लिक करें.

3 लेग्ड OAuth सीक्वेंस फ़्लो

हैंडशेक में क्लाइंट की मुख्य ज़िम्मेदारियां

  • सहमति से जुड़ी चुनौती को रिले करना (पांचवां और छठा चरण): एजेंट, adk_request_credential को जारी करता है. इसमें सहमति का यूआरएल और एक बार इस्तेमाल किया जा सकने वाला नॉन्स होता है. क्लाइंट, पॉप-अप खोलता है और नॉन्स को कुकी के तौर पर सेव करता है.
  • रीडायरेक्ट कॉलबैक को होस्ट करें (चरण 10-11): /validateUserId, जहां Auth Manager, सहमति मिलने के बाद पॉप-अप भेजता है.
  • टोकन को फ़ाइनल करें (12 से 14 चरण): रीडायरेक्ट से मिली पुष्टि की स्थिति को कैश किए गए नॉनस के साथ मिलाएं और credentials:finalize को कॉल करें. यह टोकन को वॉल्ट में सेव करता है.

अपना क्लाइंट बनाना

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

8. यूज़र इंटरफ़ेस (यूआई) क्लाइंट को स्थानीय तौर पर चलाना

हमने 3LO सहमति फ़्लो के क्रम आरेख में बताया है कि Auth Manager को ब्राउज़र पॉप-अप को क्लाइंट-साइड कॉलबैक एंडपॉइंट पर रीडायरेक्ट करना होता है. सैंपल क्लाइंट, /validateUserId पर उस एंडपॉइंट को होस्ट करता है. इसे लोकल तौर पर चलाकर देखते हैं.

क्लाइंट फ़ाइलों को लोकल में कॉपी करना

adk-python GitHub रिपॉज़िटरी में मौजूद gcp_auth/client फ़ोल्डर पर जाएं. इस फ़ोल्डर में, चैट क्लाइंट कंटेनर बनाने के लिए ज़रूरी ऐसेट होती हैं.

👉 gcp_auth/client में मौजूद सभी फ़ाइलों को अपने लोकल एनवायरमेंट में कॉपी करें:

  • main.py: यह FastAPI ऐप्लिकेशन स्क्रिप्ट है. इसमें टोकन फ़ाइनलाइज़ेशन कॉलबैक (/validateUserId) शामिल है, जिसके बारे में हमने पिछले सेक्शन में बात की थी.
  • static/: इसमें एचटीएमएल पेज होते हैं.

इसके अलावा, फ़ोल्डर का स्पार्स चेकआउट भी किया जा सकता है:

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

क्लाइंट को चलाना

  1. उस client फ़ोल्डर पर जाएं जिसे आपने अभी कॉपी किया है: 
    cd adk-python/contributing/samples/integrations/gcp_auth/client
  2. वर्चुअल एनवायरमेंट बनाएं और क्लाइंट की डिपेंडेंसी इंस्टॉल करें. फ़ोल्डर में requirements.txt मौजूद है, लेकिन pyproject.toml नहीं है. इसलिए, uv run uvicorn ... अपने-आप Failed to spawn: uvicorn के साथ काम नहीं करता: 
    uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
  3. क्लाइंट को उस एजेंट पर पॉइंट करें जिसे आपने डिप्लॉय किया है. इसके बाद, उसे पोर्ट 8501 पर शुरू करें: 
    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
  4. पुष्टि करें कि सर्वर सही तरीके से शुरू हो गया है और http://localhost:8501 पर सुन रहा है.

9. OAuth फ़्लो की जांच करना

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

पहला चरण: टूल का इस्तेमाल शुरू करना

  1. ब्राउज़र टैब खोलें और अपने क्लाइंट यूआरएल पर जाएं: http://localhost:8501.
  2. बाएं पैनल में, एजेंट टाइप को Remote Agent Engine पर सेट करें.
  3. Google Cloud प्रोजेक्ट और जगह की जानकारी टाइप करें. Load Remote Agents पर क्लिक करें. इससे आपके प्रोजेक्ट में डिप्लॉय किए गए सभी एजेंट लोड हो जाने चाहिए.
  4. ड्रॉपडाउन से सही एजेंट चुनें और सेटिंग सेव करें.
  5. चैट बॉक्स में, यह टाइप करें: 
    Fetch my contributions across my private repositories over the last 6 months
    टाइप करें और Enter दबाएं.
  6. चैट यूज़र इंटरफ़ेस (यूआई) को देखें: एजेंट के पास अब तक आपके उपयोगकर्ता सेशन के लिए कोई क्रेडेंशियल नहीं है. इसलिए, उसे पुष्टि करने की चुनौती मिलती है. साथ ही, वह बातचीत के थ्रेड में 'पुष्टि करना ज़रूरी है' कार्ड दिखाता है.
  1. एक अलग ब्राउज़र पॉप-अप विंडो खुलेगी. यह आपको Google Cloud के Auth Manager के ज़रिए, GitHub OAuth के अनुमति वाले पेज पर रीडायरेक्ट करेगी.
  2. अनुरोध की गई अनुमतियों की समीक्षा करें और अनुमति दें पर क्लिक करें.
  3. GitHub, आपको वापस Google Cloud पर रीडायरेक्ट करेगा. इसके बाद, पॉप-अप को आपके localhost कॉलबैक यूआरएल /validateUserId पर रीडायरेक्ट कर दिया जाएगा.
  4. कॉलबैक सेवा, क्रेडेंशियल हैंडशेक को प्रोसेस करती है और उसे पूरा करती है.

तीसरा चरण: फिर से शुरू करें

  1. पॉप-अप विंडो बंद होने के बाद, माता-पिता के चैट टैब में अपने-आप पता चल जाता है कि चैट बंद हो गई है.
  2. फ़्रंटएंड, एजेंट को फिर से शुरू करने का पेलोड वापस भेजता है.
  3. यह एजेंट, Google Cloud Auth Manager से नए टोकन को सुरक्षित तरीके से वापस पाता है. इसके बाद, आपकी ओर से GitHub MCP टूल को कॉल करता है. साथ ही, आपकी निजी रिपॉज़िटरी से डेटा को सीधे तौर पर चैट विंडो में स्ट्रीम करता है. यह ऐसा डेटा होता है जिसे एजेंट खुद से ऐक्सेस नहीं कर सकता.

चरण D: Cloud Logs की जांच करना

यह पुष्टि करने के लिए कि टोकन एक्सचेंज और फ़ाइनलाइज़ेशन की प्रोसेस सुरक्षित तरीके से पूरी हुई है:

  1. Google Cloud Console के Logs Explorer पर जाएं.
  2. सर्वर लॉग में, नॉन्स निकालने और उसकी पुष्टि होने की जानकारी देने वाले लॉग ढूंढें: 
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
  3. एजेंट के रनटाइम लॉग की जांच करना: इसके अलावा, एजेंट प्लैटफ़ॉर्म कंसोल में सीधे तौर पर एक्ज़ीक्यूशन लॉग देखे जा सकते हैं:
    • 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

डिवाइस पर मौजूद फ़ाइलों से स्टोरेज में जगह बनाएं

अगर आपको अपने लोकल एनवायरमेंट को पूरी तरह से साफ़ करना है, तो यह तरीका अपनाएं. हालांकि, ऐसा करना ज़रूरी नहीं है:

  1. लोकल uvicorn सर्वर को बंद करने के लिए, उस टर्मिनल में Ctrl+C दबाएं जहां वह चल रहा है.
  2. इस लैब के दौरान बनाई गई प्रोजेक्ट डायरेक्ट्री हटाएं:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. बधाई हो!

आपने साइन इन किए हुए उपयोगकर्ता की ओर से कार्रवाई करने वाला एजेंट बना लिया है और उसे सुरक्षित कर लिया है!

आपको यह जानकारी मिली:

  • एजेंट सिस्टम की पहचान: एजेंट, अपने खाते की पहचान के तहत कैसे काम करता है, ताकि GCP इन्फ़्रास्ट्रक्चर के साथ सुरक्षित तरीके से इंटरफ़ेस किया जा सके, टेलीमेट्री लॉग मैनेज किए जा सकें, और क्रेडेंशियल फ़ाइनलाइज़ेशन एपीआई कॉल किए जा सकें.
  • उपयोगकर्ता की सौंपी गई पहचान: एजेंट, बाहरी प्लैटफ़ॉर्म (जैसे कि GitHub) पर उपयोगकर्ता की ओर से कार्रवाई करने के लिए, अनुमति का अनुरोध कैसे करता है. इसके लिए, वह तीन चरणों वाले OAuth (3LO) सहमति फ़्लो को ट्रिगर करता है.
  • टूल को सुरक्षित तरीके से इंटिग्रेट करना: Google Cloud Auth Manager का इस्तेमाल करके, एडीके एजेंट को मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर से कैसे कनेक्ट करें, ताकि हार्डकोड किए गए सीक्रेट का इस्तेमाल करने के बजाय, उपयोगकर्ता के टोकन को डाइनैमिक तरीके से फ़ेच किया जा सके.
  • IAM नीति का कॉन्फ़िगरेशन: अनुमति देने वाले व्यक्ति के खाते और एजेंट रनटाइम आइडेंटिटी, दोनों को अनुमति देने वाले व्यक्ति के खाते पर अनुमति देने के लिए, अनुमति से जुड़ी सेटिंग को कैसे सेट अप करें.

इस बारे में और पढ़ें