יצירת סוכן AI שפועל בשם המשתמש באמצעות Agent Identity ו-Auth Manager

1. מבוא

סוכן עם פרטי כניסה משלו והרשאה רחבה יכול לראות את הנתונים של כולם. ב-codelab הזה תיצרו סוכן שקורא ל-API של צד שלישי עם פרטי הכניסה של המשתמש המחובר, כך שהסוכן יראה בדיוק את מה שהמשתמש יכול לראות ולא יותר מזה.

תבנו אותו באמצעות הערכה לפיתוח סוכנים (ADK) של Google ו-Gemini Enterprise.

בפרט, תלמדו איך לתכנן ארכיטקטורה של זהות כפולה שבה:

  1. הסוכן פועל בשמו (Agent Identity): באמצעות Agent Identity שמגובה על ידי SPIFFE, הסוכן מפעיל את Auth Manager, מאחסן טלמטריה וקורא ל-Cloud APIs.
  2. הסוכן פועל בשם המשתמש (זהות שהוקצתה למשתמש): כדי לגשת למשאבים חיצוניים כמו GitHub, הסוכן מפעיל תהליך הסכמה של OAuth עם 3 רגליים (3LO) כדי לשלוח שאילתות בבטחה לכלי באמצעות פרטי הכניסה של המשתמש.

ארכיטקטורה של זהות כפולה

כדי להשיג את זה, תלמדו איך:

  1. איך ליצור סוכן ADK שמתחבר לשרת Model Context Protocol‏ (MCP) של GitHub.
  2. מעדכנים את הכלי של הסוכן מאסימון גישה אישי (PAT) סטטי ב-GitHub לזרימת OAuth עם 3 רגליים (3LO) באמצעות Google Cloud Auth Manager.
  3. פורסים את הסוכן בצורה מאובטחת ל-Agent Runtime ומקצים Agent Identity.
  4. מגדירים תפקידים ב-IAM כדי לספק לסוכן גישה לזהות שלו בכספת האסימונים בשם המשתמש.
  5. הסבר על התהליך המלא של 3LO ב-Auth Manager ב-Google Cloud.

דרישות מוקדמות

לפני שמתחילים, חשוב לוודא שיש לכם:

  • פרויקט ב-Google Cloud שהחיוב בו מופעל.
  • ‫Google Cloud SDK (gcloud CLI) מותקן ומאומת בפרויקט במחשב המקומי. נדרשת גרסה 586.0.0 או גרסה חדשה יותר – מריצים את הפקודה gcloud components update.
  • ‫Python 3.10 עד 3.13 מותקן באופן מקומי.
  • הכלי לניהול חבילות uv הותקן (pip install uv).
  • חשבון ב-GitHub כדי לרשום אפליקציית OAuth וליצור אסימונים. אם אין לכם חשבון ב-GitHub, אתם יכולים להשתמש בשרת MCP של צד שלישי שתומך ב-OAuth תלת-רגלי.

2. הגדרת הפרויקט

1. אימות ב-Google Cloud

במהלך השיעור הזה, תצטרכו לבצע אימות ל-Google Cloud משורת הפקודה המקומית כדי לוודא שלסביבה שלכם יש את ההרשאות הנדרשות לפריסה ב-Agent Runtime, להקצאת Agent Identity ולהגדרה של Auth Manager:

מריצים את הפקודות הבאות כדי להיכנס לחשבון Google Cloud ולהגדיר את פרטי הכניסה ב-Application Default Credentials ‏ (ADC):

gcloud auth login
gcloud auth application-default login

2. הפעלת שירותי Google Cloud הנדרשים

כדי להריץ את שיעור ה-Lab הזה, צריך להפעיל את ממשקי ה-API הנדרשים בפרויקט בענן ב-Google Cloud. מריצים את הפקודה הבאה במסוף:

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

הפעלת הפקודה הזו עשויה להימשך דקה. בסיום, תופיע שורת הפקודה עם אישור שה-API פעיל.

3. התקנת CLI של סוכנים והגדרת הפרויקט

‫agents-cli הוא כלי שורת פקודה שמשמש ליצירת תבניות, לניהול, לבדיקה ולפריסה של סוכני ADK ב-Gemini Enterprise. מתקינים אותו באופן מקומי:

uvx google-agents-cli setup

אימות ההתקנה:

agents-cli --help

תפריט העזרה של ה-CLI אמור להופיע עם הפקודות הזמינות (כמו deploy,‏ run ו-status).

יצירת הפיגום הראשוני של הפרויקט. תתחילו עם אב טיפוס מקומי ותשפרו אותו בהמשך כדי לפרוס אותו ב-Agent Runtime:

agents-cli create secure-agent-demo --prototype --yes

פעולה זו יוצרת את הספרייה secure-agent-demo שמכילה את קוד הסוכן הבסיסי, התלויות וקבצי הבדיקה.

4. הוספת התוספים הנדרשים ל-ADK

ה-pyproject.toml שנוצר google-adk[gcp,otel-gcp], חסרים שני תוספים שהסוכן הזה צריך: mcp לערכת הכלים של GitHub ו-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, ומחילות כללי בטיחות מחמירים (כמו גישת קריאה בלבד והנחיית משתמשים לאימות אם מתרחשות שגיאות).
  • ‫Agent Configuration (הגדרת הסוכן) (root_agent): יוצר מופע של ADK‏ Agent באמצעות מודל gemini-3.8-flash, מגדיר לוגיקה של ניסיון חוזר של HTTP ומצייד את הסוכן בערכת הכלים של GitHub.
  • ‫App Wrapper (app): עוטף את סוכן הבסיס במאגר ADK App, וכך מאפשר פריסה ל-Agent Runtime.

2. הוספת כלי MCP של GitHub

הסוכן מתחבר ל-GitHub באמצעות Model Context Protocol‏ (MCP). יוצרים קובץ חדש בשם tools.py בתיקייה app/ כדי לרשום את פרמטרי החיבור של שער ה-MCP. מעתיקים ומדביקים את הקוד הבא:

# 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",
            },
        )
    )

הפונקציה הזו יוצרת כלי שמפעיל את שרת ה-MCP של GitHub:

  • ‫MCP Toolset (McpToolset): גילוי ורישום דינמיים של יכולות GitHub ככלים של סוכנים שאפשר להפעיל.
  • פרמטרים של חיבור (StreamableHTTPConnectionParams): מצביעים על ערכת הכלים לשער ה-MCP הציבורי של GitHub.
  • כותרות הרשאה: מוסיף את GITHUB_TOKEN כטוקן מסוג Bearer ומחיל מצב קריאה בלבד (X-MCP-Readonly: true) ישירות בשכבת התעבורה.

3. בדיקה מקומית באמצעות PAT (אסימון גישה אישית) של GitHub

כדי להריץ את הסוכן באופן מקומי עם פרטי כניסה סטטיים:

  1. יוצרים אסימון גישה אישי ב-GitHub. צריך לתת לו הרשאת קריאה למאגרי המידע, אחרת הסוכן יוכל לראות רק נתונים ציבוריים וההנחיה שלמטה לא תחזיר כלום.
  2. מגדירים אותו בסביבה: 
    export GITHUB_TOKEN="your_github_pat_here"
  3. עוברים לתיקייה secure-agent-demo. ריצה: 
    cd secure-agent-demo
agents-cli playground
  4. פותחים את הממשק של סביבת המשחקים, בוחרים את התיקייה app מהתפריט הנפתח. בתיבת הצ'אט, מקלידים "Fetch my contributions across my private repositories over the last 6 months" ומוודאים שהסוכן קורא לכלי GitHub ומחזיר נתונים מהמאגרים הפרטיים שלכם.

4. הגדרת Auth Manager

קידוד קשיח של פרטי כניסה סטטיים (כמו PAT) הוא נוח ליצירת אב טיפוס, אבל הוא חושף אפליקציות בסביבת הייצור לדליפת פרטי כניסה, להשבתה של רענון אסימונים ידני ולחוסר אמצעי בקרה על גישה שמותאמים לענן.

כדי לפתור את הבעיה הזו, Google Cloud מספקת את מנהל האימות של Agent Identity. מנהל האימות של Agent Identity הוא כספת לאחסון פרטי כניסה שנועדה לעזור בהגנה על פרטי הכניסה. הוא מאפשר לסוכנים לבצע אימות באמצעות מפתח API או מזהה לקוח וסוד לקוח ב-OAuth, או מטעם משתמש באמצעות העברת הרשאות ב-OAuth באמצעות אסימוני גישה של משתמשי קצה.

במרכז ניהול ההרשאות, אתם מגדירים ספקי אימות שמגדירים את סוג האימות ואת פרטי הכניסה לאפליקציות ספציפיות של צד שלישי. ספקי אימות הם אזוריים, והאזור חייב להיות זהה לאזור שבו אתם פורסים את הסוכן. תהליך העבודה מקצה לקצה של Auth Manager פועל באופן הבא:

תהליך העבודה של Auth Manager

  1. יירוט דינמי של הסכמה: כשהסוכן מנסה להפעיל כלי בשם המשתמש, ה-ADK בודק אם יש פרטי כניסה קיימים ותקינים במנהל ההרשאות. אם לא קיים כזה, Auth Manager מחזיר כתובת URL להרשאה כדי להתחיל תהליך הסכמה של OAuth עם 3 רגליים (3LO).
  2. אחסון מאובטח ב-Vault: אחרי שמשתמש הקצה מאשר את האפליקציה, Auth Manager מיירט באופן אוטומטי את הקריאה החוזרת של OAuth ומאחסן את טוקני הגישה והרענון של המשתמש שנוצרו ב-Vault מאובטח שמנוהל על ידי Google.
  3. מחזור חיים אוטומטי של טוקנים: Auth Manager מנהל באופן מלא את התפוגה והרוטציה של הטוקנים ברקע, כך שלא צריך לוגיקה ידנית לרענון הטוקנים או השבתה.
  4. ביצוע פעולות בכלי ללא סודות: בפעולות הבאות, הסוכן (שמבצע אימות באמצעות Agent Identity ב-SPIFFE) מבקש באופן דינמי את אסימון הגישה המוקצית של המשתמש ממנהל ההרשאות בזמן הריצה, כך שגם קוד הלקוח וגם קוד הסוכן נשארים ללא סודות.

שלב א': הגדרת GitHub כספק אימות

מריצים את הפקודה gcloud הבאה כדי ליצור ספק אימות של GitHub בפרויקט Google Cloud. תצטרכו לספק את מזהה הלקוח ואת הסוד שלו בהמשך: GitHub לא ינפיק אותם עד שהוא יקבל את כתובת ה-URL של הקריאה החוזרת של הספק הזה.

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"

מתארים את הספק כדי לאחזר את כתובת ה-URL להפניה אוטומטית ב-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.

שלב ב': רישום אפליקציית OAuth ב-GitHub

  1. עוברים אל דף הגדרות הפיתוח ב-GitHub ולוחצים על Register a new OAuth app (רישום אפליקציית OAuth חדשה).
  2. בשדה כתובת ה-URL של דף הבית, מזינים את כתובת ה-URL של אפליקציית ה-Frontend (לדוגמה, http://localhost:8501 ליצירת אב טיפוס מקומי). אפשר לשנות את זה מאוחר יותר לכתובת ה-URL שפרסתם בסביבת הייצור.
  3. מגדירים את כתובת ה-URI להפניה אוטומטית לערך 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 מוגדר במלואו עם פרטי הכניסה של אפליקציית ה-OAuth של GitHub, ומערכת Google Cloud מוגדרת לפעול ככספת מאובטחת שמטפלת במחזור החיים של ההסכמה והאסימונים.

5. העברת אסימון PAT אל 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 מבקש קודם ממנהל ההרשאות את האסימון של המשתמש. אם עדיין אין אסימון כזה, המערכת מבקשת מהמשתמש להיכנס במקום להיכשל. הערך GITHUB_TOKEN שמוגדר בהארדקוד כבר לא קיים.

6. פריסת סוכן ל-Agent Runtime

אחרי שעדכנו את כלי ה-MCP של GitHub כדי להשתמש ב-Auth Manager במקום, השלב הבא הוא לפרוס את הסוכן אל Agent Runtime. פריסת הסוכן עם Agent Identity מופעלת מספקת מזהה SPIFFE ייחודי לסוכן.

נתחיל בהפעלת ההגדרה של הפריסה לפרויקט. מריצים בטרמינל:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

הפקודה הזו בודקת את מבנה הפרויקט כדי לוודא שהוא תואם ל-ADK, מכינה את הגדרות האריזה של הקונטיינר הבסיסי ומייצרת קובץ agents-cli-manifest.yaml ברמה הבסיסית של הפרויקט, עם הגדרות פריסה שמוגדרות כברירת מחדל.

‫👈 פותחים את קובץ agents-cli-manifest.yaml שנוצר ומוודאים שהשדה region הוא us-central1, או מעדכנים אותו ל-us-central1, כדי לוודא שהסוכן נפרס באותו אזור כמו ספק האימות:

region: "us-central1"

פריסת הסוכן עם Agent Identity

פריסה באמצעות 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"

תהליך הפריסה נמשך כמה דקות, עד שהמאגר נוצר ומועלה. בסיום, ה-CLI מדפיס את שם המשאב שנפרס. חשוב לשים לב לערך של reasoningEngines/ENGINE_ID, כי תצטרכו אותו כדי לתת הרשאה לסוכן שלכם ולכוון אליו את לקוח ממשק המשתמש.

אישור הזהות של הסוכן

עכשיו שהסוכן פועל בענן, הוא צריך הרשאה לגשת לפרטי הכניסה שמאוחסנים ב-Auth Manager. כברירת מחדל, לזהות ה-SPIFFE של הסוכן אין גישה למשאבי ענן חיצוניים.

מריצים את הפקודה gcloud הבאה כדי להעניק את התפקיד roles/agentidentity.user לזהות של הסוכן במשאב של ספק האימות. כך מעניקים לסוכן את ההרשאות המדויקות שהוא צריך כדי לבקש אסימוני משתמשים מהכספת, ולא הרשאות רחבות יותר.

‫👈 מחליפים את 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"

עכשיו מקצים לחשבון שלכם את אותו תפקיד אצל הספק. לקוח ממשק המשתמש שמופעל בשלב הבא קורא ל-API של סיום האימות עם Application Default Credentials, ולכן בלי זה תהליך ההסכמה ייכשל עם שגיאה 403 ב-agentidentity.authProviders.retrieveCredentials:

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

עכשיו, אחרי שהסוכן נפרס ב-Agent Runtime עם Agent Identity מאובטח, השלב הבא הוא לספק למשתמשים ממשק קצה קדמי מותאם אישית כדי לשוחח איתו. חשוב מכך, מנהל האימות של Google Cloud דורש גורם מטפל בקריאה חוזרת של אפליקציית לקוח כדי להשלים את לולאת האימות.

מנהל האימות של Google Cloud מנהל בצורה מאובטחת את פרטי הכניסה של המשתמשים בכספת, אבל הוא לא יכול להשלים את החלפת טוקן ה-OAuth בעצמו. התהליך של 3LO מסתמך על אפליקציית הלקוח כדי לגשר על הפער:

  1. כשמשתמש מאשר את אפליקציית GitHub, ‏ GitHub מפנה אותו בחזרה אל ספק האימות של Agent Identity redirectUrl.
  2. לאחר מכן, Auth Manager מפנה אוטומטית את החלון הקופץ בדפדפן של המשתמש בחזרה אל כתובת URL של קריאה חוזרת בצד הלקוח (continue_uri).
  3. באחריות אפליקציית הלקוח ליירט את ההפניה הזו, לקרוא את המספר האקראי מקובצי ה-Cookie של הדפדפן ולהתקשר לנקודת הקצה credentials:finalize של Google Cloud כדי להשלים את הלחיצת יד.
  4. אחרי שהלקוח משלים את ההחלפה, Google Cloud שומרת את האסימון בצורה מאובטחת בכספת של ספק האימות, וכך הסוכן יכול להפעיל את הכלי של GitHub.

אם אין אירוח לקוח מותאם אישית לנקודת הקצה של הקריאה החוזרת, הלחיצת יד לא תושלם ולא תהיה אפשרות לאחסן את פרטי הכניסה בכספת.

תהליך OAuth 3LO האינטראקטיבי מתפרס על פני כמה שכבות. כאן מפורט מחזור החיים המלא של בקשה לשימוש בכלי. הסבר מפורט על כך מופיע בהמשך ובשלב הבא.

‫👈 כדי להגדיל את התמונה, לוחצים עליה.

תהליך הרשאה באמצעות OAuth תלת-רגלי

תחומי האחריות העיקריים של הלקוח בתהליך ההסכמה

  • העברת אתגר ההסכמה (שלבים 5-6): הסוכן שולח את adk_request_credential עם כתובת ה-URL של ההסכמה וערך חד-פעמי (nonce). הלקוח פותח את החלון הקופץ ושומר את הערך החד-פעמי כקובץ Cookie.
  • אירוח של קריאה חוזרת להפניה אוטומטית (שלבים 10-11): /validateUserId, שבה כלי ניהול ההרשאות שולח את החלון הקופץ אחרי קבלת ההסכמה.
  • משלימים את האסימון (שלבים 12-14): משלבים את מצב האימות מההפניה האוטומטית עם ה-nonce ששמור במטמון ומפעילים את credentials:finalize, ששומר את האסימון בכספת.

יצירת לקוח משלכם

אין צורך לכתוב את הלקוח הזה למעבדה – בשלב הבא מופעל לקוח מוכן מראש. כשמיישמים את זה באפליקציה שלכם, אלה שני המקורות שאפשר להסתמך עליהם:

8. הפעלת לקוח ממשק המשתמש באופן מקומי

כפי שניתן לראות בתרשים הרצף של תהליך קבלת ההסכמה 3LO, Auth Manager צריך להפנות את החלון הקופץ בדפדפן בחזרה לנקודת קצה של קריאה חוזרת (callback) בצד הלקוח. הלקוח לדוגמה מארח את נקודת הקצה הזו בכתובת /validateUserId. נריץ אותו באופן מקומי.

העתקת קבצים של לקוחות למיקום מקומי

עוברים לתיקייה gcp_auth/client במאגר GitHub של adk-python. התיקייה הזו מכילה את הנכסים שנדרשים לבניית מאגר של לקוח הצ'אט שלנו.

‫👈 מעתיקים את כל הקבצים בתיקייה gcp_auth/client לסביבה המקומית:

  • ‫main.py: סקריפט האפליקציה של FastAPI שמכיל את פונקציית הקריאה החוזרת (callback) לסיום האסימון (/validateUserId) שדיברנו עליה בקטע הקודם.
  • ‫static/: מכיל את דפי ה-HTML.

אפשרות נוספת היא לבצע sparse checkout של התיקייה:

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

עכשיו, אחרי שפרסתם את כל השירותים, הגדרתם את הקישורים של IAM והגדרתם את משתני הסביבה, אתם מוכנים לבדוק את תהליך ההרשאה המאובטח מקצה לקצה עם הרשאת משתמש.

שלב א: הפעלת הכלי

  1. פותחים כרטיסייה בדפדפן ועוברים לכתובת ה-URL של הלקוח: 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 לדף ההרשאות של GitHub OAuth.
  2. בודקים את ההרשאות המבוקשות ולוחצים על אישור.
  3. מערכת GitHub תפנה אתכם בחזרה אל Google Cloud, ו-Google Cloud תפנה את החלון הקופץ אל localhost כתובת ה-URL של הקריאה החוזרת /validateUserId.
  4. שירות הקריאה החוזרת מעבד ומסיים את לחיצת היד של פרטי הכניסה.

שלב ג': חידוש המינוי

  1. אחרי שהחלון הקופץ נסגר, הכרטיסייה הראשית של הצ'אט מזהה את הסגירה באופן אוטומטי.
  2. החלק הקדמי של האתר שולח מטען ייעודי (payload) של קורות חיים בחזרה לסוכן.
  3. הסוכן מאחזר בצורה מאובטחת את האסימון החדש שהוחלף מ-Google Cloud Auth Manager, קורא לכלי GitHub MCP בשמכם ומזרים נתונים מהמאגרים הפרטיים שלכם ישירות בחזרה לחלון הצ'אט – נתונים שהסוכן לא יכול היה להגיע אליהם בעצמו.

שלב ד': בודקים את יומני הענן

כדי לוודא שהחלפת האסימון והסופיות עובדו בצורה מאובטחת:

  1. נכנסים אל Logs Explorer במסוף Google Cloud.
  2. מאתרים את יומני השרת שמאשרים את חילוץ ה-nonce והאימות המוצלח: 
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
  3. בדיקת יומני Agent Runtime: אפשר גם לצפות ביומני הביצוע ישירות במסוף של Agent Platform:
    • עוברים אל מסוף Agent Runtime.
    • לוחצים על הסוכן הפרוס ברשימה.
    • עוברים לכרטיסייה 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. מסירים את ספריות הפרויקט שנוצרו במהלך שיעור ה-Lab הזה:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

‫11. מעולה!

יצרתם סוכן מאובטח שפועל בשם המשתמש שמחובר לחשבון.

מה למדתם:

  • זהות מערכת הסוכן: איך הסוכן פועל תחת זהות החשבון שלו כדי ליצור ממשק מאובטח עם תשתית GCP, לנהל יומני טלמטריה ולקרוא ל-APIs של סיום אימות.
  • זהות שהוקצתה למשתמש: איך הסוכן מבקש הרשאה לפעול בשם המשתמש בפלטפורמות חיצוניות (כמו GitHub) על ידי הפעלת תהליך הסכמה של OAuth עם 3 רגליים (3LO).
  • שילוב מאובטח של כלים: איך לקשר סוכני ADK לשרתים של Model Context Protocol‏ (MCP) באמצעות Google Cloud Auth Manager כדי לאחזר באופן דינמי טוקנים של משתמשים במקום להשתמש בסודות שמוצפנים בהארדקוד.
  • הגדרת מדיניות IAM: איך מגדירים קשרי הרשאות מפורטים כדי להעניק הרשאה גם לזהות של Agent Runtime וגם לחשבון שלכם בספק האימות.

קריאה נוספת