‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שימוש בזהות הסוכן עם Agent Runtime

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

סקירה כללית

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

פרטי הכניסה של סוכן מוגנים כברירת מחדל באמצעות מדיניות של בקרת גישה מבוססת-הקשר (CAA) שמנוהלת על ידי Google. המדיניות הזו אוכפת קישור mTLS כדי להבטיח שאפשר להשתמש באישורים של הסוכן בצורה של אסימונים שקשורים לאישור רק בסביבת זמן הריצה המיועדת והמהימנה (לדוגמה, קונטיינר של Cloud Run). הגדרת בסיס האבטחה הזו מונעת שימוש חוזר בפרטי כניסה גנובים, ומספקת הגנה מפני גניבת פרטי כניסה והשתלטות על חשבונות (ATO).

בדף הזה מפורטים הנושאים הבאים:

יצירת סוכן עם זהות סוכן: יצירת סוכן כך שהסוכן יקבל באופן אוטומטי זהות ייחודית כשפורסים אותו ב-Agent Runtime.
אישור גישה ל-API באמצעות זהות הסוכן: שימוש בזהות הסוכן שהוקצתה כדי לאשר או לדחות את הגישה של הסוכן לכלים, לממשקי API ולמשאבים של צד ראשון של Google Cloud. Google Cloud הגישה כוללת גם סוכנים אחרים שמארחים ב-Agent Runtime באמצעות פרוטוקול Agent2Agent‏ (A2A).
רישום פעילות הסוכן: הצגת זהות הסוכן ביומנים בשירותי Google Cloud . בתהליכי עבודה שבהם המשתמש מעניק הרשאה, ביומנים מוצגים גם זהות המשתמש וגם זהות הסוכן.
רשימת הסוכנים וזהות הסוכן: הצגת רשימת הסוכנים והזהויות שלהם ב-Agent Runtime.
ביטול ההסכמה לבקרת גישה מבוססת-הקשר (לא מומלץ): ביטול ההסכמה למדיניות ברירת המחדל של בקרת הגישה מבוססת-הקשר (CAA).

מגבלות

אי אפשר להעניק זהויות של סוכנים תפקידים של קטגוריות מדור קודם (storage.legacyBucketReader,‏ storage.legacyBucketWriter או storage.legacyBucketOwner) בקטגוריות של Cloud Storage.

יצירת סוכן עם זהות סוכן

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

כשיוצרים זהות של סוכן, יש לכם את האפשרויות הבאות:

יצירת מופע של Agent Runtime בלי לפרוס קוד של סוכן: אם רוצים להגדיר מדיניות IAM לפני פריסת הסוכן, אפשר ליצור זהות של סוכן בלי לפרוס את קוד הסוכן. כדי לעשות זאת, יוצרים מופע של Agent Runtime עם השדה identity_type בלבד:
```
import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
  config={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)
```
אחרי שיוצרים את מופע Agent Runtime עם זהות הסוכן, אפשר להוסיף קוד לסוכן באמצעות agent_engine.update(...).

יצירת מופע של Agent Runtime במהלך פריסת קוד הסוכן: אם רוצים להקצות את זהות הסוכן במהלך פריסת קוד הסוכן, צריך להשתמש ב-Agent Platform SDK for Python ובדגל identity_type=AGENT_IDENTITY.

מגדירים את הסוכן במסגרת המועדפת:

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

לאחר מכן, פורסים אותו:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

כאשר BUCKET_NAME הוא השם של הקטגוריה ב-Cloud Storage.

פריסת סוכנים באמצעות Agents CLI: ‏Agents CLI הוא כלי אידיאלי ללומדים, ליצירת אב טיפוס ולבדיקות מהירות, כי הוא מציע פתרון פריסה מהיר עם משאבים בסיסיים למעקב. הפקודה הבאה פורסת את הסוכן:
```
agents-cli deploy --agent-identity
```
פריסת סוכנים עם זהות סוכן באמצעות ADK deploy: הגדרת הסוכן באמצעות ADK. לפני שמריצים את הפקודה adk deploy, מריצים את הפקודות הבאות בתיקייה של הסוכן כדי להוסיף קובץ הגדרות עם זהות הסוכן.
```
# Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json
```

מופע Agent Runtime נוצר עם זהות סוכן לקריאה בלבד שאומתה על ידי המערכת (מזהה חשבון ראשי):

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

החלקים הבאים מוקצים לכם אוטומטית כחלק מזהות הסוכן:

‫TRUST_DOMAIN: דומיין מהימן מוקצה לכם כשאתם מפעילים את Agent Platform API:
- אם יש לכם ארגון, דומיין מהימן נוצר ברמת הארגון בפורמט agents.global.org-ORGANIZATION_ID.system.id.goog.
- אם לפרויקט אין ארגון, נוצר דומיין מהימן ברמת הפרויקט בפורמט agents.global.project-PROJECT_NUMBER.system.id.goog.
‫NAMESPACE: נתיב המשאב הקבוע של הסוכן.
‫AGENT_NAME: agent-reasoning-engine-id שלא ניתן לשינוי.

זהות הסוכן מבוססת על SPIFFE. אנחנו גם מקצים ומנהלים אוטומטית אישור x509 בסוכן עם אותה זהות לאימות מאובטח. כברירת מחדל, לסוכן יש גישה לרישום ביומן, למדדים, לגישה למודל, לסשנים, לזיכרונות ולסביבות ארגז חול (גרסת טרום-השקה) משלו.

לזהויות של סוכנים מוקצים תפקידי ברירת מחדל roles/aiplatform.agentContextEditor ו-roles/aiplatform.agentDefaultAccess, כדי שלסוכנים יהיו הרשאות בסיסיות לפעולה.

אפשר לראות את הזהות דרך מסוף Agent Runtime Google Cloud וה-API.

גישה Google Cloud לממשקי API ולשירותים באמצעות זהות הסוכן

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

מדיניות הרשאות: מעניקה לסוכן גישה למשאב Google Cloud .
כללי מדיניות דחייה: דחיית הגישה של סוכן ל Google Cloud משאב.

הענקת גישה לסוכן

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

‫roles/aiplatform.expressUser: הענקת גישה להסקת מסקנות, להפעלת סשנים ולזיכרון.
‫roles/serviceusage.serviceUsageConsumer: נותנים לסוכן הרשאה להשתמש במכסה של הפרויקט וב-Agent Platform SDK.
‫roles/browser: הענקת גישה לפונקציות בסיסיות. Google Cloud

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

יוצרים מדיניות הרשאה ב-IAM כדי להעניק לסוכן תפקיד ב-IAM:

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

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

‫ORGANIZATION_ID: המזהה של הארגון.
‫PROJECT_NUMBER: מספר הפרויקט.
‫LOCATION: האזור שלכם. אזורים נתמכים ב-Runtime
‫AGENT_ENGINE_ID: מזהה המשאב של מופע Agent Runtime.
‫ROLE_NAME: שם התפקיד שרוצים להעניק. לדוגמה, roles/vision.user. רשימה של תפקידים מוגדרים מראש מופיעה במאמר הסבר על תפקידים.

אחרי שמגדירים את IAM, ‏ Application Default Credentials ב-Agent Platform SDK משתמשים אוטומטית בזהות של הסוכן כדי לבצע אימות למשאבים ב-Google Cloud .

הענקת גישה לכמה סוכנים

אתם יכולים להקצות תפקיד IAM לכל הסוכנים של Agent Runtime בפרויקט מסוים או בארגון שלם.

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

אם הפרויקט שייך לארגון:

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

אם הפרויקט לא שייך לארגון:

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.project-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

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

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

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/aiplatform.expressUser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

כדי להעניק תפקיד לכל הסוכנים של Agent Runtime בארגון:

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

דחיית הגישה של סוכן

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

דחיית הגישה של הסוכן למשאבים מסוימים באמצעות כללי מדיניות הדחייה ב-IAM.

// Deny policy (deny all agents across the org from ability to create or delete buckets)

{
"displayName": "Deny access to bucket for all agent identities in the org",
"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "principalSet://<org.id>.global.agent.id.goog/*"
      ],
      "deniedPermissions": [
        "iam.googleapis.com/roles.create",
        "storage.googleapis.com/buckets.delete"
      ]
    }
  }
]
}

מגדירים את תחום הגישה של החשבון הראשי כדי להגביל את המשאבים שהסוכן יכול לגשת אליהם, למרות הרשאות אחרות שיש לסוכן:

// PAB Policy (Only allow agents to operate within resource boundary)

{
    "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
    "details": {
    "rules": [
      {
        "description": "Restrict agent identity inside a folder",
        "resources": [
          "//cloudresourcemanager.googleapis.com/folder/0123456789012"
        ],
        "effect": "ALLOW"
      }
    ],
  }
}

// Bind PAB policy to all identities in the organization (incl agent id)

gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
      --organization=organizations/ORGANIZATION_ID \
      --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

תיעוד הפעילות של הסוכן

אם מפעילים את Cloud Logging, אפשר לראות את היומנים של הסוכן והמשתמשים שניגשו למשאב Google Cloud .

כשהנציג פועל בשם המשתמש, ביומני הרישום מוצגים גם זהות הנציג וגם זהות המשתמש.
כשהסוכן פועל על סמך הסמכות שלו, ביומנים מוצג רק הזיהוי של הסוכן.

רשימת הסוכנים והזהויות שלהם

אפשר לראות את רשימת הזהויות של הסוכנים ב-Agent Runtime באמצעות Google Cloud מסוף ושורת פקודה.

המסוף

נכנסים לדף Deployments של Agent Platform במסוף Google Cloud .

מעבר לדף Deployments

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

‫API בארכיטקטורת REST

אפשר לאחזר את זהות הסוכן כשמקבלים מופע של Agent Runtime באמצעות ה-API בארכיטקטורת REST.

התשובה כוללת את זהות הסוכן בפורמט הבא:

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

במקרים של מופעי Agent Runtime שלא משתמשים בזהות סוכן, השדה effectiveIdentity מכיל את שם חשבון השירות או סוכן השירות שמשויך למופע Agent Runtime.

ביטול ההסכמה לשימוש בבקרת גישה מבוססת-הקשר (CAA)

כברירת מחדל, ניסיון להשתמש באסימון גישה מחוץ לסביבת זמן הריצה המיועדת של Agent Runtime מוביל לשגיאה הבאה:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

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

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

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

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

מדריך

ניהול הסוכנים שנפרסו

איך מנהלים סוכנים שנפרסו בסביבת זמן ריצה מנוהלת של Agent Platform