בעזרת Agent Registry, סוכני הניהול יכולים לאמת בצורה מאובטחת את הזהות של סוכנים מרוחקים, ערכות כלים של Model Context Protocol (MCP) ושירותיGoogle Cloud שזוהו. באמצעות Agent Identity ומנהל האימות של Agent Identity, אתם יכולים להגדיר פרטי כניסה, קישורים וכותרות HTTP בהתאמה אישית כשאתם קוראים ליכולות שזוהו דרך Agent Registry.
לפני שמתחילים
לפני שמאמתים את הכלים והמשאבים, צריך לבצע את הפעולות הבאות:
- הגדרת Agent Registry.
אם אתם משתמשים בפרויקט אחד, אתרו את מזהה הפרויקט של פרויקט הפיקוח שבו מופעל Agent Registry. אם הגדרתם גבול ניהול לכמה פרויקטים, השתמשו במזהה של פרויקט הניהול כדי לגלות ולרשום את כל הפרויקטים בגבול, או ציינו מזהה של פרויקט חבר כדי לבצע פעולות בפרויקט יחיד.
מתקינים את הגרסה העדכנית של ערכת הפיתוח לסוכנים (ADK) או משדרגים אליה, עם יחסי התלות של A2A, Agent Identity ו-MCP:
תמונה בתוך תמונה (PIP)
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"uv
uv add "google-adk[a2a,agent-identity,mcp]"צריך לשדרג לגרסה
google-adk>=1.29.0לפחות.כדי להשתמש ב-Application Default Credentials (ADC) לאימות, צריך להגדיר אותם:
gcloud auth application-default loginלפרטי הכניסה של ADC צריכות להיות ההרשאות הנדרשות לניהול זהויות והרשאות גישה (IAM) בשביל שירותי Google Cloud הבסיסיים שהסוכנים או הכלים יוצרים איתם אינטראקציה.
מגדירים את משתני הסביבה הבאים:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=LOCATION export API_KEY=EXTERNAL_API_KEYמחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט של פרויקט הפיקוח. -
LOCATION: המיקום ב-Agent Registry שבו הסוכנים ושרתי ה-MCP רשומים, למשלus-central1אוglobal. -
EXTERNAL_API_KEY: אם משתמשים בכותרות בהתאמה אישית, מפתח ה-API החיצוני.
-
מידע ולמידה על מודלים של אימות
כדי לנהל את פרטי הכניסה, Agent Registry מסתמך על Agent Identity לאימות Google Cloud מובנה, ועל מנהל האימות לספקי אימות וקישורים.
הנציגים יכולים להשתמש בזהות שלהם או במנהל האימות כדי לגשת לכלים באמצעות מפתחות API או OAuth 2.0. הזהות של הנציג עצמו מסופקת באמצעות Application Default Credentials (ADC), גם אם אתם משתמשים ב-Agent Identity וגם אם אתם משתמשים בחשבונות שירות.
אם אתם צריכים לבצע אימות בלי להשתמש במנהל האימות, אתם יכולים לספק כותרות HTTP בהתאמה אישית ישירות בבקשות של ה-ADK.
כדי להעביר פרטי כניסה של משתמשים או להגביל את ההרשאות של אסימונים שנשלחים לסוכני Agent2Agent (A2A) מרוחקים, קראו את המאמר הגבלת הרשאות של סוכנים באמצעות פרטי כניסה מוגדרים.
כדי לקבוע מהי הגישה הכי טובה לתרחיש לדוגמה שלכם, קראו את המאמר מודלים של אימות.
שימוש ב-Agent Identity בכלים של Google Cloud
בשירותים של Google Cloud , כמו Agent Runtime ב-Gemini Enterprise Agent Platform או Cloud Storage, הנציג משתמש בזהות שלו כדי לגשת לכלים. הגישה הזו מנוהלת באמצעות Application Default Credentials (ADC), גם אם אתם משתמשים בזהות של הנציג וגם אם אתם משתמשים בחשבונות שירות.
לזהות שמשויכת לסוכן צריכות להיות הרשאות IAM הנדרשות לשירותי Google Cloud הבסיסיים. לדוגמה, אם כלי MCP מנהל מכונות וירטואליות של Compute Engine, לזהות הסוכן צריך להיות תפקיד כמו אדמין מכונות של Compute (v1) או תפקיד ברמה גבוהה יותר, בנוסף לתפקיד צפייה ב-API של Agent Registry.
אימות סוכני A2A מרוחקים
אם סוכן הניהול מתחבר לסוכן Google Agent2Agent (A2A) מרוחק באמצעות הזהות שלו, צריך לכלול באופן מפורש את httpx.AsyncClient שמוגדר עם כותרות האימות של Google ב-method get_remote_a2a_agent().
כדי לא לחרוג ממגבלות הזמן הקצוב לתפוגה שמוגדרות כברירת מחדל בצד הלקוח ב-HTTP, צריך להגדיר זמן קצוב לתפוגה בהתאמה אישית.
בדוגמה הבאה מוסבר איך להגדיר את httpx.AsyncClient באמצעות ADC וזמן קצוב לתפוגה בהתאמה אישית:
import os
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry
class GoogleAuth(httpx.Auth):
def __init__(self):
self.creds, _ = google.auth.default()
def auth_flow(self, request):
if not self.creds.valid:
self.creds.refresh(Request())
request.headers["Authorization"] = f"Bearer {self.creds.token}"
yield request
# Initialize the registry client
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
if not project_id:
raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")
registry = AgentRegistry(
project_id=project_id,
location=location,
)
# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))
# Connect to a remote A2A agent using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "agents/AGENT_ID"
# Full format: f"projects/{project_id}/locations/{location}/agents/AGENT_ID"
agent_name = "agents/AGENT_ID"
my_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_name,
httpx_client=httpx_client,
)
מחליפים את AGENT_ID במזהה של הנציג המשני הרשום מסוג A2A שרוצים שנציג ה-orchestrator יתקשר אליו.
אימות כלי MCP
אם סוכן הניהול משתמש בזהות משלו כדי לגשת לערכת הכלים של MCP, אתם יכולים להפעיל את לקוח המרשם באמצעות ADC והשיטה get_mcp_toolset():
import os
from google.adk.integrations.agent_registry import AgentRegistry
# Initialize the registry client
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
if not project_id:
raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")
registry = AgentRegistry(
project_id=project_id,
location=location,
)
# Retrieve an MCP toolset using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "mcpServers/SERVER_ID"
# Full format: f"projects/{project_id}/locations/{location}/mcpServers/SERVER_ID"
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)
מחליפים את SERVER_ID במזהה של שרת ה-MCP הרשום.
שימוש במנהל האימות לכלים בהתאמה אישית ולגישה שהוענקה
כשהנציג צריך להתחבר לממשקי API חיצוניים, לכלים בהתאמה אישית או לשרתי MCP חיצוניים, אתם יכולים להשתמש במנהל האימות כדי לנהל את פרטי הכניסה בלי להטמיע אותם בקוד של האפליקציה.
בהתאם לתרחיש לדוגמה, אתם יכולים להגדיר את מנהל האימות לתרחישים הבאים:
- גישה לכלים בהתאמה אישית: מאמתים את הנציג באמצעות מפתחות API או OAuth עם 2 רגליים (2LO) כשהנציג צריך לגשת לכלי באמצעות הזהות וההרשאות שלו.
- גישה לכלים בשם משתמש: אימות הנציג שפועל כמשתמש ספציפי באמצעות OAuth תלת-רגלי (3LO). המודל הזה מומלץ כשהנציג צריך לגשת לכלים בשם האדם שיוצר איתו אינטראקציה, ונדרשת הסכמה מהמשתמש והרשאה שהוקצתה.
במודלים האלה צריך ליצור ספק אימות. לאחר מכן, יוצרים קישור ב-Agent Registry כדי לקשר את ספק האימות למשאבי המרשם.
אחרי שמגדירים את ספק האימות, ה-ADK מנהל את תהליך האימות של סוכן ה-orchestrator. לדוגמה, ראו פתרון קישורים בקוד ADK.
גישה לכלים בהתאמה אישית
אם אתם רוצים שהנציג יתחבר לכלים חיצוניים או מותאמים אישית באמצעות פרטי הכניסה שלו, אתם יכולים להגדיר את מנהל האימות כך שיטפל במפתחות API או ב-OAuth עם 2 רגליים (2LO):
- יצירת ספק האימות: יוצרים ספק אימות במנהל האימות כדי לאחסן את מפתח ה-API או את פרטי הכניסה ל-OAuth. מידע נוסף זמין במאמרים אימות באמצעות OAuth דו-רגלי עם מנהל האימות או אימות באמצעות מפתח API עם מנהל האימות.
קישור ספק האימות: כדי לאפשר לסוכן התזמור לזהות את ספק האימות הנכון של יעד, צריך ליצור קישור ב-Agent Registry בין הסוכן, משאב המטרה וספק האימות. כשמשתמשים בקישורים, לא צריך להגדיר באופן ידני ספקי אימות בקוד:
gcloud
כדי ליצור קישור מפורש בין הסוכן לבין משאב המטרה וספק האימות, מריצים את הפקודה
gcloud agent-registry bindings create. כשמציינים את שם המשאב--auth-provider-binding, צריך להשתמש במזהה הפרויקט של פרויקט הפיקוח:gcloud agent-registry bindings create BINDING_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --source-identifier="SOURCE_ID" \ --target-identifier="TARGET_ID" \ --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"Terraform
מגדירים את המשאב
google_agent_registry_bindingכדי לקשר את הסוכן ומשאב המטרה לספק האימות:resource "google_agent_registry_binding" "custom_tool_binding" { project = "PROJECT_ID" location = "LOCATION" binding_id = "BINDING_NAME" display_name = "DISPLAY_NAME" source { identifier = "SOURCE_ID" } target { identifier = "TARGET_ID" } auth_provider_binding { auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" } }מחליפים את מה שכתוב בשדות הבאים:
-
BINDING_NAME: המזהה הייחודי של הקישור. -
PROJECT_ID: מזהה הפרויקט של פרויקט הפיקוח. -
LOCATION: האזור או המיקום של המאגר, למשלus-central1אוglobal. -
DISPLAY_NAME: שם קריא לאנשים שמוצג לקישור. -
SOURCE_ID: מזהה הסוכן של סוכן המקור בפורמט URN. TARGET_ID: מזהה המאגר של שרת ה-MCP או נקודת הקצה של היעד בפורמט URN.-
AUTH_PROVIDER_ID: המזהה של ספק האימות.
-
גישה לכלים בשם משתמש
אם אתם רוצים שהנציג יאמת את הזהות שלו מול שרתי MCP או כלים מרוחקים בשם משתמש ספציפי, השתמשו ב-OAuth תלת-רגלי (3LO) דרך מנהל האימות.
מנהל האימות הוא שירות שמנוהל באופן מלא על ידי Google, ומטפל באסימוני OAuth, בהסכמת המשתמשים ובהפניות אוטומטיות. כשמשתמש קצה יוצר אינטראקציה עם הנציג ומפעיל כלי שדורש הרשאות גישה, הפלטפורמה מבקשת מהמשתמש באופן אוטומטי לתת הסכמה, מאחסנת את פרטי הכניסה וממשיכה בתהליך העבודה:
- יצירת ספק האימות: יוצרים ספק אימות במנהל האימות ומגדירים את כתובות ה-URI להפניה אוטומטית ב-OAuth. מידע נוסף זמין במאמר אימות באמצעות OAuth תלת-רגלי עם מנהל אימות.
- עדכון אפליקציית הלקוח: מעדכנים את אפליקציית הלקוח כדי לטפל בקריאה לפונקציה
adk_request_credentialולנהל את הסכמת המשתמש. הוראות מפורטות זמינות במאמר עדכון האפליקציה בצד הלקוח. קישור ספק האימות: כדי לאפשר לסוכן הניהול לזהות את ספק האימות הנכון למשאב המטרה, צריך ליצור קישור ב-Agent Registry בין הסוכן, משאב המטרה וספק האימות. כשמשתמשים בקישורים, לא צריך להגדיר באופן ידני ספקי אימות בקוד:
gcloud
כדי ליצור קישור מפורש בין הסוכן לבין משאב המטרה וספק האימות, מריצים את הפקודה
gcloud agent-registry bindings create. כשמציינים את שם המשאב--auth-provider-binding, צריך להשתמש במזהה הפרויקט של פרויקט הפיקוח:gcloud agent-registry bindings create BINDING_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --source-identifier="SOURCE_ID" \ --target-identifier="TARGET_ID" \ --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" \ --auth-provider-binding-scopes=SCOPES \ --auth-provider-binding-continue-uri="https://REDIRECT_URI"Terraform
מגדירים את המשאב
google_agent_registry_bindingעם היקפי ההרשאות של OAuth 2.0 וכתובת ה-URI להמשך:resource "google_agent_registry_binding" "user_delegated_binding" { project = "PROJECT_ID" location = "LOCATION" binding_id = "BINDING_NAME" display_name = "DISPLAY_NAME" source { identifier = "SOURCE_ID" } target { identifier = "TARGET_ID" } auth_provider_binding { auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" scopes = [SCOPES] continue_uri = "https://REDIRECT_URI" } }מחליפים את מה שכתוב בשדות הבאים:
-
BINDING_NAME: המזהה הייחודי של הקישור. -
PROJECT_ID: מזהה הפרויקט של פרויקט הפיקוח. -
LOCATION: האזור או המיקום של המאגר, למשלus-central1אוglobal. -
DISPLAY_NAME: שם קריא לאנשים שמוצג לקישור. -
SOURCE_ID: מזהה הסוכן של סוכן המקור בפורמט URN. -
TARGET_ID: מזהה המאגר של שרת ה-MCP או משאב הכלי, בפורמט URN. -
AUTH_PROVIDER_ID: המזהה של ספק האימות. -
SCOPES: רשימה מופרדת בפסיקים של היקפי הרשאות OAuth 2.0, למשלhttps://www.googleapis.com/auth/cloud-platform. ב-Terraform, צריך להקיף כל היקף הרשאות במירכאות כפולות. -
REDIRECT_URI: ה-URI להפניה אוטומטית שהוגדר לספק האימות אחרי הסכמה מהמשתמש.
-
פתרון בעיות בקישורים בקוד של ה-ADK
אחרי שיוצרים את הקישור לספק האימות ב-Agent Registry, ה-ADK מטפל בתהליך האימות.
כשמשתמשים בלקוח AgentRegistry כדי לאחזר ערכת כלים של MCP, ה-ADK פותר באופן אוטומטי את כל הקישורים שמשויכים לשרת הזה ומחיל את הסכימה הנכונה. אתם לא צריכים להגדיר פרטי כניסה בקוד באופן ידני.
בדוגמה הבאה אפשר לראות איך מאחזרים ערכת כלים מאומתת של MCP ומצרפים אותה לנציג:
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
if not project_id:
raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")
# Register the auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())
# Initialize the registry client
registry = AgentRegistry(
project_id=project_id,
location=location,
)
# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)
# Compose the agent
maps_agent = LlmAgent(
name="maps_agent",
model="gemini-1.5-flash",
instruction=(
"You are a local guide and navigation expert. Your goal is to provide "
"accurate location information and directions.\n\n"
"Rules:\n"
"1. **Planning**: Before answering, plan how to use the tools to get "
"the best information (e.g., search for a place first, then get details "
"or directions).\n"
"2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses, "
"and navigation details. Do not guess locations or distances.\n"
"3. **Output Format**: Provide clear summaries of locations, including "
"full addresses and key details. Use formatting to make recommendations "
"easy to read.\n"
"4. **Tone**: Be helpful, enthusiastic, and descriptive, with "
"appropriate emojis to enhance the experience."
),
tools=[my_mcp_toolset],
)
מחליפים את SERVER_ID במזהה של שרת ה-MCP הרשום.
אם הגדרתם 3LO כדי לגשת לכלים בשם המשתמש, אתם צריכים גם לספק את continue_uri ל-method get_mcp_toolset. ה-URI הזה מציין לאן משתמש הקצה מופנה אחרי שהוא נותן את ההסכמה שלו:
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
if not project_id:
raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")
# Register the auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())
# Initialize the registry client
registry = AgentRegistry(
project_id=project_id,
location=location,
)
# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
# For 3-legged OAuth (3LO), provide continue_uri.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(
mcp_server_name=mcp_server_name,
# Replace with your app's redirect URI:
continue_uri="https://REDIRECT_URI"
)
# Compose the agent
maps_agent = LlmAgent(
name="maps_agent",
model="gemini-1.5-flash",
instruction=(
"You are a local guide and navigation expert. Your goal is to provide "
"accurate location information and directions.\n\n"
"Rules:\n"
"1. **Planning**: Before answering, plan how to use the tools to get "
"the best information (e.g., search for a place first, then get details "
"or directions).\n"
"2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses, "
"and navigation details. Do not guess locations or distances.\n"
"3. **Output Format**: Provide clear summaries of locations, including "
"full addresses and key details. Use formatting to make recommendations "
"easy to read.\n"
"4. **Tone**: Be helpful, enthusiastic, and descriptive, with "
"appropriate emojis to enhance the experience."
),
tools=[my_mcp_toolset],
)
מחליפים את מה שכתוב בשדות הבאים:
-
SERVER_ID: המזהה של שרת ה-MCP הרשום. -
REDIRECT_URI: ה-URI להפניה אוטומטית של האפליקציה, שאליו המשתמש מועבר אחרי שהוא נותן הסכמה.
שימוש בכותרות מותאמות אישית לכלים חיצוניים
אם אתם צריכים לאמת או להעביר כותרות של בקשות בלי להשתמש במנהל האימות, אתם יכולים לספק כותרות HTTP בהתאמה אישית ישירות בבקשות של ה-ADK.
כדי להגדיר כותרות בהתאמה אישית, צריך לספק קריאה חוזרת (callback) של header_provider כשמפעילים את הלקוח AgentRegistry.
הקריאה החוזרת (callback) של header_provider מקבלת את הקשר ההפעלה הנוכחי ומחזירה מילון של כותרות HTTP. הרכיב McpToolset מצרף באופן אוטומטי את הכותרות האלה לבקשות במורד הזרם שנשלחות לשרת ה-MCP.
כותרות בהתאמה אישית שסופקו על ידי הקריאה החוזרת (callback) של header_provider נשלחות רק לשרתי ה-MCP של היעד. כותרות בהתאמה אישית לא משמשות לאימות מול Agent Registry API עצמו. ה-API תמיד מסתמך על ADC.
בדוגמה הזו מוסבר איך לספק מפתח API או טוקן למוכ"ז בהתאמה אישית לערכת כלים חיצונית:
import os
from typing import Any
from google.adk.integrations.agent_registry import AgentRegistry
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
external_api_key = os.environ.get("API_KEY")
# Define the custom header provider.
def my_auth_headers(context: Any) -> dict[str, str]:
"""Returns custom headers injected into MCP toolset requests."""
return {
"Authorization": f"Bearer {external_api_key}",
"X-Custom-Context": "orchestrator-request"
}
# Initialize the registry client.
# The header_provider is sent to the target MCP server when calling tools.
# The header_provider is not used to authenticate against the Agent Registry API.
# The Agent Registry API always uses your Google ADC.
registry = AgentRegistry(
project_id=project_id,
location=location,
header_provider=my_auth_headers
)
# Fetching the toolset automatically attaches the header_provider to the MCP server.
# Replace with the full resource name of your registered MCP server.
mcp_server_name = f"projects/PROJECT_ID/locations/LOCATION/mcpServers/EXTERNAL_SERVER_ID"
external_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט של פרויקט הפיקוח. -
LOCATION: האזור או המיקום של המרשם, למשלus-central1. -
EXTERNAL_SERVER_ID: המזהה של שרת ה-MCP החיצוני שרשום.
המאמרים הבאים
- איך מגבילים את ההרשאות של הסוכן באמצעות פרטי כניסה מוגדרים
- איך משתמשים ב-Agent Gateway כדי לאכוף אמצעי בקרת גישה וגבולות רשת על בקשות מאומתות של כלים