שיתוף סוכן

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

כדי לשתף נציג, צריך לתת את ההרשאה aiplatform.reasoningEngines.query למשאב הספציפי של הנציג.

מתי כדאי לשתף סוכן

שיתוף של סוכן מאפשר ריבוי משתמשים או מערכות אוטומטיות לשלוח שאילתות לסוכן. תרחישים נפוצים לשיתוף נציג כוללים:

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

לפני שמתחילים

  1. מזהים את הסוכן שרוצים לשתף. אתם צריכים את מזהה הפרויקט ואת מזהה מנוע החשיבה הרציונלית של הנציג.
  2. מזהים את המשתמשים או את חשבונות השירות שרוצים לתת להם גישה.

שלב 1: יוצרים תפקיד בהתאמה אישית

כדי לשמור על העיקרון של הרשאות מינימליות, צריך ליצור תפקיד בהתאמה אישית שמכיל רק את ההרשאה aiplatform.reasoningEngines.query.

gcloud

כדי ליצור תפקיד בהתאמה אישית בפרויקט, מריצים את הפקודה הבאה:

gcloud iam roles create ROLE_ID  --project=PROJECT_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

לחלופין, כדי ליצור את התפקיד לכל הארגון:

gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

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

  • ‫ROLE_ID: מזהה התפקיד, למשל agentUser.
  • ‫ROLE_TITLE: שם לתפקיד, למשל Agent Runtime user.
  • ‫ROLE_DESCRIPTION: תיאור קצר של התפקיד, למשל Allows querying agents.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫ORGANIZATION_ID: מזהה הארגון.

Terraform

כדי ליצור את התפקיד בהתאמה אישית באמצעות Terraform, משתמשים במשאב google_project_iam_custom_role:

resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id     = "ROLE_ID"
title       = "ROLE_TITLE"
project     = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}

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

  • ‫ROLE_ID: מזהה התפקיד, למשל agentUser.
  • ‫ROLE_TITLE: שם לתפקיד, למשל Agent Runtime user.
  • ‫PROJECT_ID: מזהה הפרויקט.

שם התפקיד בהתאמה אישית יהיה projects/PROJECT_ID/roles/ROLE_ID או organizations/ORGANIZATION_ID/roles/ROLE_ID.

שלב 2: הקצאת התפקיד לנציג

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

Python

כדי להקצות את התפקיד באמצעות Python, משתמשים בספרייה google-cloud-aiplatform:

from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient
from google.api_core.client_options import ClientOptions

# Initialize the client
client = ReasoningEngineServiceClient(
  client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com")
)

# Define the resource path
resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

# Get the current IAM policy and add the new binding
policy = client.get_iam_policy(request={"resource": resource})
binding = policy.bindings.add()
binding.role = "projects/PROJECT_ID/roles/ROLE_ID"
binding.members.append("USER_OR_SA")

# Update the IAM policy on the resource
client.set_iam_policy(request={"resource": resource, "policy": policy})

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

  • ‫LOCATION: האזור שבו הנציג פרוס, למשל us-central1.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REASONING_ENGINE_ID: מזהה מנוע החשיבה הרציונלית של הסוכן.
  • ‫ROLE_ID: מזהה התפקיד, למשל agentUser.
  • ‫USER_OR_SA: כתובת האימייל של המשתמש או חשבון השירות, למשל user:someone@example.com או serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

כדי להקצות את התפקיד באמצעות Terraform, משתמשים במשאב google_vertex_ai_reasoning_engine_iam_member:

resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project          = "PROJECT_ID"
region           = "REGION"
reasoning_engine = "REASONING_ENGINE_ID"
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

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

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור.
  • ‫REASONING_ENGINE_ID: מזהה מנוע החשיבה הרציונלית של הסוכן.
  • ‫USER_OR_SA: המשתמש או חשבון השירות.

שיקולי אבטחה

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

  • ממשק קצה אמין: רוב הסוכנים שמוגדרים כברירת מחדל בערכה לפיתוח סוכנים (ADK) פועלים מממשק קצה אמין. הנציג סומך על הפקודות של ממשק המשתמש, מה שנותן לממשק המשתמש שליטה מלאה בסשנים ובמשתמשים. במקרים כאלה, אל תתנו לישויות לא מהימנות גישה ישירה לנציג.
  • סוכני A2A: סוכנים אחרים, כמו סוכני Agent2Agent ‏ (A2A), יכולים להיחשף לישויות לא מהימנות אם הם מטמיעים אימות והרשאה משלהם. ‫Agent Runtime ב-Gemini Enterprise Agent Platform מספק רק בקרת גישה גסה לממשק של הסוכן.

המאמרים הבאים