שיתוף סוכן

בדף הזה מוסבר איך לשתף סוכן יחיד בפרויקט שלכם על ידי הענקת הרשאות ניהול זהויות והרשאות גישה (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:[e-mail] או serviceAccount:[e-mail].

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 = google_vertex_ai_reasoning_engine.my_engine.name
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור.
• ‫USER_OR_SA: המשתמש או חשבון השירות.

שיקולי אבטחה

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

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