כדי להעניק לסוכן גישה לכלים ולשירותים חיצוניים (כמו משימות ב-Jira או מאגרי GitHub) בשם משתמש קצה ספציפי, צריך להגדיר ספק אימות OAuth תלת-רגלי במנהל האימות של זהות הסוכן.
ספקי אימות OAuth תלת-רגלי מאפשרים לנהל את פרטי הכניסה והטוקנים, וכך לא צריך להשתמש בקוד מותאם אישית כדי לטפל בתהליכי אימות.
תהליך עבודה של OAuth תלת-רגלי
ספקי אימות OAuth 3.0 דורשים הסכמה מהמשתמש כי הסוכן ניגש למשאבים בשם המשתמש.
- בקשה להרשמה והפניה אוטומטית: ממשק הצ'אט מבקש מהמשתמש להיכנס לחשבון ואז מפנה אותו לדף ההסכמה של אפליקציית הצד השלישי.
- הסכמה ואחסון: אחרי שהמשתמש מעניק הרשאה, מנהל האימות של זהות הסוכן מאחסן את אסימוני ה-OAuth שנוצרו בכספת פרטי הכניסה שמנוהלת על ידי Google.
- החדרה: כשמשתמשים בערכה לפיתוח סוכנים (ADK), הסוכן מאחזר באופן אוטומטי את הטוקן מספק האימות ומחדיר אותו לכותרות של הפעלת הכלי.
לפני שמתחילים
- מוודאים שבחרתם את שיטת האימות הנכונה.
-
מפעילים את Agent Identity API, אם הוא עדיין לא מופעל.
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, נדרשת ההרשאה
serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים - יצירה ופריסה של סוכן.
- צריך לוודא שיש לכם אפליקציית קצה קדמי שתטפל בהנחיות לכניסה של משתמשים ובהפניה לדפי הסכמה של צד שלישי.
- מוודאים שיש לכם את התפקידים הנדרשים כדי להשלים את המשימה הזו.
התפקידים הנדרשים
כדי לקבל את ההרשאות שדרושות ליצירה ולשימוש בספק אימות עם 3 רגליים, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
-
כדי ליצור ספקי אימות:
- אדמין של זהויות סוכנים (
roles/agentidentity.admin) - עורך זהויות של סוכנים (
roles/agentidentity.editor)
- אדמין של זהויות סוכנים (
-
כדי להשתמש בספקי אימות:
- משתמש ב-Agent Identity (
roles/agentidentity.user) - משתמש Vertex AI (
roles/aiplatform.user) - צרכן שימוש בשירות (
roles/serviceusage.serviceUsageConsumer)
- משתמש ב-Agent Identity (
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
התפקידים המוגדרים מראש כוללים את ההרשאות שנדרשות ליצירה ולשימוש בספק אימות עם 3 רגליים. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:
ההרשאות הנדרשות
כדי ליצור ספק אימות עם 3 רגליים ולהשתמש בו, נדרשות ההרשאות הבאות:
-
כדי ליצור ספקי אימות:
agentidentity.authProviders.create -
כדי להשתמש בספקי אימות:
-
agentidentity.authProviders.retrieveCredentials -
aiplatform.endpoints.predict -
aiplatform.sessions.create
-
יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
יצירת ספק אימות עם 3 רגליים
יוצרים ספק אימות כדי להגדיר את ההגדרות ופרטי הכניסה של אפליקציות צד שלישי.
כדי ליצור ספק אימות עם 3 רגליים, משתמשים במסוף Google Cloud או ב-Google Cloud CLI.
המסוף
- נכנסים לדף Agent Registry במסוף Google Cloud .
- לוחצים על השם של הסוכן שרוצים ליצור עבורו ספק אימות.
- לוחצים על זהות.
- בקטע Auth Providers (ספקי אימות), לוחצים על Add auth provider (הוספת ספק אימות).
-
בחלונית הוספת ספק אימות, מזינים שם ותיאור.
השם יכול להכיל רק אותיות קטנות, מספרים או מקפים, הוא לא יכול להסתיים במקף והוא חייב להתחיל באות קטנה.
- מהרשימה סוג OAuth בוחרים באפשרות OAuth (תלת-רגלי) .
- לוחצים על Create and continue.
- כדי לתת לסוכן הרשאה להשתמש בספק האימות, לוחצים על Grant access (מתן גישה).
במהלך התהליך הזה, התפקיד משתמש ב-Agent Identity (
roles/agentidentity.user) מוקצה באופן אוטומטי לזהות הסוכן במשאב של ספק האימות. - מעתיקים את כתובת ה-URL להתקשרות חזרה.
- בכרטיסייה נפרדת, רושמים את כתובת ה-URL של הקריאה החוזרת באפליקציית לקוח ה-OAuth של הצד השלישי.
- בקטע Auth provider credentials (פרטי כניסה של ספק אימות), מזינים את הפרטים הבאים:
- Client ID
- סוד לקוח
- כתובת URL לטוקן
- כתובת URL של הרשאה
- URI ברירת המחדל להמשך: אופציונלי. מזינים URI של הפניה אוטומטית כברירת מחדל כדי להפנות את המשתמשים אחרי שהם מביעים הסכמה, אם לא מסופק URI של המשך בזמן הריצה.
- לוחצים על Add provider config (הוספת הגדרת ספק).
ספק האימות החדש שנוצר מופיע ברשימה ספקי אימות.
CLI של gcloud
-
מגדירים את אפליקציית הלקוח ב-OAuth כדי לרשום את הלקוח ולקבל מזהה לקוח וסוד לקוח. מציינים את ה-URI של ההפניה באמצעות התבנית בקטע הזה.
-
יוצרים את ספק האימות באמצעות פרטי הכניסה של הלקוח:
gcloud agent-identity auth-providers create
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --three-legged-oauth-client-id="CLIENT_ID" \ --three-legged-oauth-client-secret="CLIENT_SECRET" \ --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \ --three-legged-oauth-token-url="TOKEN_URL" \ --three-legged-oauth-default-continue-uri="DEFAULT_CONTINUE_URI"מחליפים את מה שכתוב בשדות הבאים:
-
AUTH_PROVIDER_NAME: השם של ספק האימות. -
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
LOCATION: האזור שבו נוצר ספק האימות. -
CLIENT_ID: מזהה הלקוח של אפליקציית הלקוח ב-OAuth. -
CLIENT_SECRET: סוד הלקוח של אפליקציית לקוח OAuth. -
AUTHORIZATION_URL: נקודת הקצה של שרת ההרשאות שאליה המשתמשים מופנים כדי לתת הסכמה. -
TOKEN_URL: נקודת הקצה להחלפת אסימונים בשרת ההרשאות. -
DEFAULT_CONTINUE_URI: אופציונלי. כתובת ה-URI להפניה אוטומטית שמוגדרת כברירת מחדל, שאליה המשתמשים מופנים אחרי שהם מעניקים הסכמה. נעשה בה שימוש אם לא מסופקת כתובת URI להמשך בזמן הריצה.
-
- מוודאים שספק האימות מופיע ברשימה והסטטוס שלו הוא
ENABLED:gcloud agent-identity auth-providers list \ --project="
PROJECT_ID" \ --location="LOCATION" -
נותנים הרשאות גישה כדי לאפשר לסוכן ולסביבת הפיתוח המקומית לאחזר פרטי כניסה מספק האימות. כדי לאפשר לסוכן הפרוס ולחשבון המשתמש האישי שלכם לגשת לספק האימות, צריך להקצות את התפקיד משתמש בזהות הסוכן (
roles/agentidentity.user) במשאב של ספק האימות:-
הענקת גישה למזהה SPIFFE של הסוכן שפרסתם (Agent Identity):
gcloud agent-identity auth-providers add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/agentidentity.user" \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID" -
מתן גישה לחשבון המשתמש האישי לצורך פיתוח ובדיקה מקומיים (
adk web):gcloud agent-identity auth-providers add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/agentidentity.user" \ --member="user:USER_EMAIL"
-
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
LOCATION: המיקום שבו ספק האימות והסוכן שלכם נפרסים (לדוגמה,us-west1). -
AUTH_PROVIDER_NAME: השם של ספק האימות (לדוגמה,bigquery-mcp-3lo-authprovider). -
AUTHORIZATION_URL: כתובת ה-URL של שרת ההרשאות (לדוגמה,https://accounts.google.com/o/oauth2/v2/auth). -
TOKEN_URL: כתובת ה-URL של שרת האסימונים (לדוגמה,https://oauth2.googleapis.com/token). -
CLIENT_ID: מזהה הלקוח ב-OAuth שנוצר משירות הצד השלישי. -
CLIENT_SECRET: סוד לקוח OAuth שנוצר משירות הצד השלישי. -
ORGANIZATION_ID: מזהה הארגון ב- Google Cloud . -
PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud . -
ENGINE_ID: המזהה של סוכן מנוע ההסקה שנפרס. -
USER_EMAIL: כתובת האימייל בחשבון המשתמש האישי שלכם.
הגדרת אפליקציית לקוח OAuth
לפני שרושמים את פרטי הכניסה של לקוח OAuth, צריך לקבל מזהה לקוח וסוד לקוח משרת ההרשאות של הצד השלישי (לדוגמה, Google, GitHub או Jira).
אם אתם מתחברים לשירות של צד שלישי מחוץ ל-Google Cloud, אתם צריכים לקבל את פרטי הכניסה של לקוח OAuth מפורטל המפתחים של השירות הזה ולדלג על השלבים שבקטע הזה.
רישום ה-URI של ההפניה האוטומטית
כשמגדירים את פרטי הכניסה של לקוח OAuth, צריך לרשום את כתובת ה-URI הייעודית להפניה אוטומטית של ספק האימות.
יוצרים את ה-URI של ההפניה האוטומטית באמצעות התבנית הבאה:
https://agentidentitycredentials.googleapis.com/v1/projects/
PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/oauthcallbackמחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
LOCATION: האזור שבו ספק האימות יופעל (לדוגמה,us-west1). -
AUTH_PROVIDER_NAME: השם של ספק האימות.
לדוגמה:
https://agentidentitycredentials.googleapis.com/v1/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback
-
אם אתם מתחברים ל Google Cloud שירותים (כמו BigQuery), אתם יכולים להגדיר את מסך ההסכמה וליצור פרטי כניסה של לקוח OAuth ב Google Cloud מסוף:
-
מגדירים את מסך ההסכמה ל-OAuth:
- במסוף Google Cloud , נכנסים לדף APIs & Services > מסך הסכמת OAuth.
- בקטע App information, מזינים שם לאפליקציה (למשל BigQuery Manager Application) וכתובת אימייל לתמיכה.
- בקטע קהל, בוחרים באפשרות פנימי או חיצוני.
- מזינים את הפרטים ליצירת קשר כדי לקבל התראות.
- קוראים ומאשרים את המדיניות של Google בנושא נתוני משתמשים בשירותי API.
- לוחצים על סיום.
-
יוצרים את פרטי הכניסה של לקוח OAuth:
- במסוף Google Cloud , נכנסים לדף APIs & Services > OAuth consent screen > Clients.
- לוחצים על Create credentials > OAuth client ID (יצירת פרטי כניסה > מזהה לקוח OAuth).
- בוחרים באפשרות Web application (אפליקציית אינטרנט) מהרשימה.
- מזינים שם שקל לזהות את לקוח ה-OAuth.
- בקטע Authorized redirect URIs (כתובות URI מורשות להפניה אוטומטית), לוחצים על Add URI (הוספת URI) ומזינים את כתובת ה-URI להפניה אוטומטית שיצרתם.
- לוחצים על יצירה. בתיבת הדו-שיח OAuth client created, מעתיקים את הערכים של Client ID ושל Client Secret שנוצרו.
-
אימות בקוד הנציג
כדי לאמת את הסוכן, אפשר להשתמש ב-ADK או לקרוא ישירות ל-Agent Identity API.
כשמבקשים פרטי כניסה, האפליקציה מציינת continue_uri שאליו המשתמשים מופנים אחרי שהם נותנים הסכמה.
אם הגדרתם default_continue_uri כשיצרתם את ספק האימות, ציון continue_uri בקוד של הסוכן הוא אופציונלי.
ADK
אפשר להפנות לספק האימות בקוד של הסוכן באמצעות ערכת הכלים של MCP ב-ADK.
from google.adk.agents import Agent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from google.adk.auth.auth_tool import AuthConfig # Register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # The URI to redirect the user to after consent is granted. # Optional if default_continue_uri is configured on the auth provider. CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId" # Create auth provider scheme # Note: If using the legacy V1 API, the resource name uses 'connectors' # instead of 'authProviders': projects/.../connectors/... auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", continue_uri=CONTINUE_URI ) # Configure an MCP tool with the authentication scheme. toolset = McpToolset( connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"), auth_scheme=auth_scheme, ) # Initialize the agent with the authenticated tools. agent = Agent( name="AGENT_NAME", model="MODEL_NAME (ex. gemini-2.5-flash)", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
דוגמה: התחברות ל-BigQuery MCP
בדוגמה הבאה מוצגת הגדרה של agent.py שמתחברת לסוכן לשרת MCP של BigQuery:
import os from google.adk.agents import Agent from google.adk.apps import App from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.models import Gemini from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset import google.auth from google.genai import types _, project_id = google.auth.default() os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID" os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True" bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME" bigquery_mcp_endpoint = os.environ.get( "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp" ) # Register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # URI to redirect user to after consent is granted. CONTINUE_URI = "http://127.0.0.1:8501/validateUserId" bigquery_mcp_auth_scheme = GcpAuthProviderScheme( name=f"projects/{project_id}/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["https://www.googleapis.com/auth/bigquery"], continue_uri=CONTINUE_URI, ) bigquery_mcp_tools = McpToolset( connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint), auth_scheme=bigquery_mcp_auth_scheme, errlog=None, ) root_agent = Agent( name="root_agent", model=Gemini( model="gemini-2.5-flash", retry_options=types.HttpRetryOptions(attempts=3), ), instruction=( "You are a helpful AI assistant designed to provide accurate and useful" " information. You can also use your BigQuery MCP tools to look up" " BigQuery data." ), tools=[bigquery_mcp_tools], ) app = App( root_agent=root_agent, name="AGENT_NAME", )
ADK
אפשר להפנות לספק האימות בקוד של הסוכן באמצעות כלי פונקציה מאומת ב-ADK.
import httpx from google.adk.agents import Agent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider from google.adk.integrations.agent_identity import GcpAuthProviderScheme from google.adk.apps import App from google.adk.auth.auth_credential import AuthCredential from google.adk.auth.auth_tool import AuthConfig from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool from vertexai import agent_engines # First, register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # The URI to redirect the user to after consent is completed. CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI" # Create Auth Config spotify_auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", continue_uri=CONTINUE_URI ) ) # Use the Auth Config in Authenticated Function Tool spotify_search_track_tool = AuthenticatedFunctionTool( func=spotify_search_track, auth_config=spotify_auth_config ) # Sample function tool async def spotify_search_track(credential: AuthCredential, query: str) -> str | list: token = None if credential.http and credential.http.credentials: token = credential.http.credentials.token if not token: return "Error: No authentication token available." async with httpx.AsyncClient() as client: response = await client.get( "https://api.spotify.com/v1/search", headers={"Authorization": f"Bearer {token}"}, params={"q": query, "type": "track", "limit": 1}, ) # Add your own logic here agent = Agent( name="AGENT_NAME", model="gemini-2.5-flash", instruction="AGENT_INSTRUCTIONS", tools=[spotify_search_track_tool], ) app = App( name="APP_NAME", root_agent=agent, ) vertex_app = agent_engines.AdkApp(app_name=app)
ADK
מפנים לספק האימות בקוד של הסוכן באמצעות ערכת הכלים Agent Registry MCP ב-ADK.
לא צריך ליצור תוכנית אימות לרצף הפעולות הזה. הקישור היוצא של שרת ה-MCP כבר מתעד את ספק האימות שבו צריך להשתמש. מעבירים את הערך
continue_uri כדי לציין לאן להפנות את המשתמש אחרי שהוא מביע הסכמה.
from google.adk.agents import Agent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider from google.adk.integrations.agent_registry import AgentRegistry # First, register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # The URI to redirect the user to after consent is completed. CONTINUE_URI="WEB_APP_VALIDATE_USER_URI" # Set Agent Registry. LOCATION must be the same region as the auth provider. registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION") # The auth provider is resolved from the MCP server's outbound binding. toolset = registry.get_mcp_toolset( mcp_server_name=( "projects/PROJECT_ID/locations/" "LOCATION/mcpServers/" "agentregistry-00000000-0000-0000-0000-000000000000" ), continue_uri=CONTINUE_URI, ) agent = Agent( name="AGENT_NAME", model="MODEL_NAME", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
שליחת קריאה ישירה ל-API
אם אתם לא משתמשים ב-ADK, הנציג שלכם צריך לשלוח קריאה ל-agentidentitycredentials.retrieveCredentials API כדי לקבל את הטוקן.
מכיוון שמדובר בתהליך OAuth רב-שלבי, הסוכן צריך לטפל במחזור החיים של הפעולה:
- הבקשה הראשונית: הסוכן מתקשר אל
retrieveCredentials. - נדרשת הסכמה: אם המשתמש לא העניק הסכמה, ה-API מחזיר תגובה שמכילה את התוצאה
uri_consent_required. הוא יכלולauthorization_uriוconsent_nonce. - הפניה אוטומטית בחזית האתר: האפליקציה צריכה להפנות את המשתמש אל
authorization_uri. - השלמה: אחרי שהמשתמש מביע הסכמה, צריך להפעיל את
FinalizeCredentialsבאמצעותconsent_nonceכדי להשלים את התהליך ולקבל את האסימון.
עדכון האפליקציה בצד הלקוח
כדי לטפל בכניסה של משתמשים ובהפניה אוטומטית ב-OAuth 3.0, האפליקציה בצד הלקוח צריכה לבצע את השלבים הבאים כדי לנהל את הסכמת המשתמש ולחדש את השיחה:
שרת לדוגמה של ממשק משתמש
אפשר להוריד ולהריץ שרת ממשק משתמש לדוגמה שמשתמש ב-uvicorn. לפני שמתחילים, מוודאים שיש לכם חשבון ב-GitHub ושהתקנתם את pip.
כדי להגדיר ולהפעיל את שרת ממשק המשתמש לדוגמה:
-
משכפלים את
adk-pythonהמאגר ב-GitHub:git clone https://github.com/google/adk-python.git
-
מנווטים למאגר ומפעילים סביבה וירטואלית של Python:
cd adk-python python3 -m venv .venv source .venv/bin/activate
-
עוברים לספריית הלקוח של ממשק המשתמש לדוגמה:
cd contributing/samples/integrations/gcp_auth/client
-
מתקינים את יחסי התלות של הלקוח:
pip install -r requirements.txt
-
לפני שמפעילים את השרת, מגדירים את משתנה הסביבה
AGENT_PROJECT_DIRכדי לציין את הספרייה שבה נמצא קוד הסוכן. אחרת, האפליקציה תחפש סוכנים כברירת מחדל בתיקיית האב של תיקיית הלקוח.מפעילים את שרת ממשק המשתמש לדוגמה באמצעות
uvicorn. מוודאים שהיציאה תואמת לכתובת ה-URI להפניה אוטומטית שהוגדרה בלקוח OAuth:export AGENT_PROJECT_DIR="/path/to/your/agent_project" uvicorn main:app --port 8501 --reload
-
פותחים את
http://localhost:8501בדפדפן. (הערה: צריך להשתמש ב-localhostולא ב-127.0.0.1, כי כתובת ה-URL להפניה אוטומטית של OAuth מחייבת שימוש בשם המארחlocalhost). מציינים את ההגדרות, לוחצים על שמירת ההגדרות והחלתן, ואז מתקשרים עם הנציג.
אפליקציה עם ממשק משתמש בהתאמה אישית
כדי להטמיע את היכולות האלה ישירות באפליקציית ממשק משתמש בהתאמה אישית, פועלים לפי השלבים הבאים:
טיפול בהפעלת ההרשאה
כשסוכן צריך הסכמה מהמשתמש, הוא מחזיר קריאה לפונקציה adk_request_credential. האפליקציה שלכם צריכה ליירט את השיחה הזו כדי ליזום תיבת דו-שיח של הרשאת משתמש או הפניה אוטומטית.
ניהול הקשר של הסשן על ידי תיעוד של consent_nonce שסופק על ידי ספק האימות. הצופן החד-פעמי הזה נדרש כדי לאמת את המשתמש במהלך שלב האימות. שומרים את הערכים auth_config ו-auth_request_function_call_id בסשן כדי לאפשר המשך של התהליך אחרי שהמשתמש מביע הסכמה.
if (fc := get_auth_request_function_call(event_data)): print("--> Authentication required by agent.") try: auth_config = get_auth_config(fc) auth_uri, consent_nonce = handle_adk_request_credential( auth_config, AUTH_PROVIDER_NAME, request.user_id ) if auth_uri: event_data['popup_auth_uri'] = auth_uri fc_id = ( fc.get('id') if isinstance(fc, dict) else getattr(fc, 'id', None) ) event_data['auth_request_function_call_id'] = fc_id event_data['auth_config'] = auth_config.model_dump() # Store session state if session_id: consent_sessions[session_id] = { "user_id": request.user_id, "consent_nonce": consent_nonce } except Exception as e: print(f"Error handling adk_request_credential: {e}") # Optionally, add logic to inform the user about the error. def handle_adk_request_credential(auth_config, auth_provider_name, user_id): ec = auth_config.exchanged_auth_credential if ec and ec.oauth2: oauth2 = ec.oauth2 return oauth2.auth_uri, oauth2.nonce return None, None
הטמעה של נקודת קצה לאימות משתמשים
מטמיעים נקודת קצה לאימות בשרת האינטרנט (אותו URI שסופק בתור
continue_uri במהלך ההגדרה). נקודת הקצה הזו צריכה:
- מקבלים את
user_id_validation_state,auth_provider_nameו-uuidכפרמטרים של שאילתה. - מאחזרים את הערכים של
user_idושלconsent_nonceמאחסון הסשן. אם כמה תהליכי הרשאה פועלים בו-זמנית, צריך להשתמש ב-uuidכדי להתאים את הסשן הנכון. - שולחים קריאה ל-
FinalizeCredentialsAPI של ספק האימות עם הפרמטרים האלה. - סגירה של חלון ההרשאה אחרי קבלת תשובה על הצלחה.
דוגמה: נקודת קצה (endpoint) לאימות FastAPI (main.py)
בדוגמה הבאה מוצגת נקודת קצה מלאה של אימות FastAPI שמטפלת בקריאה חוזרת של OAuth ומסיימת את פרטי הכניסה של המשתמש:
@app.api_route("/validateUserId", methods=["GET"]) async def validate_user(request: Request): auth_provider_name = request.query_params.get("auth_provider_name") session_id = request.cookies.get("session_id") session = consent_sessions.get(session_id, {}) payload = { "userId": session.get("user_id"), "userIdValidationState": request.query_params.get( "user_id_validation_state" ), "consentNonce": session.get("consent_nonce"), } base_url = "https://agentidentitycredentials.googleapis.com/v1" finalize_url = f"{base_url}/{auth_provider_name}/credentials:finalize" try: async with httpx.AsyncClient(timeout=30.0) as client: resp = await client.post(finalize_url, json=payload) resp.raise_for_status() except httpx.HTTPError as e: err_text = e.response.text if hasattr(e, "response") else str(e) status = e.response.status_code if hasattr(e, "response") else 500 return HTMLResponse(err_text, status_code=status) return HTMLResponse(""" <script> window.close(); </script> <p>Success. You can close this window.</p> """)
המשך השיחה עם נציג התמיכה
אחרי שהמשתמש מביע הסכמה וחלון ההרשאה נסגר, מאחזרים את הערכים auth_config ו-auth_request_function_call_id מנתוני הסשן. כדי להמשיך בשיחה, צריך לכלול את הפרטים האלה בבקשה חדשה לנציג התמיכה בתור function_response.
if (request.is_auth_resume and session.auth_request_function_call_id and session.auth_config): auth_content = types.Content( role='user', parts=[ types.Part( function_response=types.FunctionResponse( id=session.auth_request_function_call_id, name='adk_request_credential', response=session.auth_config ) ) ], ) # Send message to agent async for event in agent.async_stream_query( user_id=request.user_id, message=auth_content, session_id=session_id, ): # ...
פריסת הסוכן
כשפורסים את הסוכן ב- Google Cloud, מוודאים ש-Agent Identity מופעל.
Agent CLI
אם אתם משתמשים בערכה לפיתוח סוכנים (ADK) וב-Agent CLI, אתם צריכים לבצע את הפעולות הבאות כדי לפרוס את הסוכן עם Agent Identity מופעלת:
-
בתיקיית האפליקציה של הסוכן, יוצרים קובץ תצורה בשם
.agent_engine_config.jsonכדי להפעיל את Agent Identity:echo '{ "identity_type": "AGENT_IDENTITY" }' >
AGENT_NAME/.agent_engine_config.json -
פריסת הסוכן ב-Agent Runtime ב-Gemini Enterprise Agent Platform:
uv run adk deploy agent_engine
AGENT_NAME\ --project="PROJECT_ID" \ --region="LOCATION"מחליפים את מה שכתוב בשדות הבאים:
-
AGENT_NAME: השם של תיקיית אפליקציית הסוכן (לדוגמה,maps_agent). -
PROJECT_ID: מזהה הפרויקט ב- Google Cloud. -
LOCATION: האזור הנתמך שבו רוצים לפרוס את הסוכן (לדוגמה,us-west1).
-
Python SDK
אם אתם מבצעים פריסה באופן פרוגרמטי באמצעות Vertex AI
Python SDK, משתמשים בדגל identity_type=AGENT_IDENTITY:
import vertexai from vertexai import types from vertexai.agent_engines import AdkApp from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider # Initialize the Vertex AI client with v1beta1 API for Agent Identity support client = vertexai.Client( project="PROJECT_ID", location="LOCATION", http_options=dict(api_version="v1beta1") ) # Register the auth provider in set_up() so that it runs in the deployed # container. Use the proper wrapper class for your Agent Framework (for example, AdkApp). class AuthenticatedAdkApp(AdkApp): def set_up(self): CredentialManager.register_auth_provider(GcpAuthProvider()) super().set_up() app = AuthenticatedAdkApp(agent=agent) # Deploy the agent with Agent Identity enabled remote_app = client.agent_engines.create( agent=app, config={ "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": [ "google-cloud-aiplatform[agent_engines,adk]", "google-adk[agent-identity,mcp]>=2.7.1", ], }, )
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
LOCATION: האזור הנתמך שבו רוצים לפרוס את הסוכן (לדוגמה,us-west1).
המאמרים הבאים
- פתרון בעיות באימות של זהות הנציג
- סקירה כללית בנושא זהות הסוכן
- אימות באמצעות OAuth דו-רגלי עם מנהל ההרשאות
- אימות באמצעות מפתח API עם כלי ניהול ההרשאות
- ניהול ספקי אימות של זהויות סוכנים