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

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

סקירה כללית

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

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

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

מגבלות

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

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

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

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

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

    import agentplatform
from agentplatform import types

client = agentplatform.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.runtimes.create(
  config={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)

    אחרי שיוצרים את מופע Agent Runtime עם זהות הסוכן, אפשר להוסיף קוד לסוכן באמצעות client.runtimes.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 agentplatform
from agentplatform import types
from agentplatform.frameworks import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = agentplatform.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.runtimes.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-agentplatform[adk,runtimes]"],
    "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

  • פריסת סוכנים עם 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: מתחם אמון (trust domain) מוקצה לכם כשמפעילים את Agent Platform API:

    • אם יש לכם ארגון, דומיין מהימן נוצר ברמת הארגון בפורמט agents.global.org-ORGANIZATION_ID.system.id.goog.

    • אם לפרויקט אין ארגון, נוצר מתחם אמון (trust domain) ברמת הפרויקט בפורמט agents.global.proj-PROJECT_NUMBER.system.id.goog.

  • ‫NAMESPACE: נתיב המשאב הקבוע של הסוכן.

  • ‫AGENT_NAME: agent-reasoning-engine-id שלא ניתן לשינוי.

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

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

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

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

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

  • מדיניות הרשאות: מעניקה לסוכן גישה למשאב 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" \

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

  • ‫RESOURCE_TYPE: סוג המשאב (לדוגמה, projects או organizations).

  • ‫RESOURCE_ID: המזהה של המשאב שרוצים להעניק לו גישה.

  • ‫ORGANIZATION_ID: המזהה של הארגון.

  • ‫PROJECT_NUMBER: מספר הפרויקט.

  • ‫LOCATION: האזור שלכם. אזורים נתמכים לזמן ריצה

  • ‫AGENT_ENGINE_ID: מזהה המשאב של מופע Agent Runtime.

  • ‫ROLE_NAME: שם התפקיד שרוצים להעניק. לדוגמה, roles/vision.user. רשימה של תפקידים מוגדרים מראש מופיעה במאמר הסבר על תפקידים.

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

הענקת גישה להרשאת גישה מסוכן לסוכן (A2A)

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

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

  • הסוכן הראשי יכול לחפש את נקודת הקצה של הסוכן המשני בזמן ריצה: Agent Registry API Viewer (roles/agentregistry.viewer) בפרויקט הראשי או במשאב של המרשם
  • מאפשרים לסוכן הראשי לשלוח הודעות לנציג המשנה: Agent Platform User (roles/aiplatform.user) on the target subagent's reasoning engine resource

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

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

לדוגמה, כדי להעניק את התפקיד roles/agentregistry.viewer בפרויקט, אפשר להשתמש בפקודה הבאה של Google Cloud CLI:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
    --role="roles/agentregistry.viewer"

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

  • ‫ORGANIZATION_ID: המזהה של הארגון.
  • ‫PROJECT_NUMBER: מספר הפרויקט.
  • ‫LOCATION: האזור שבו סוכן ראשי שלכם נפרס.
  • ‫PARENT_AGENT_ENGINE_ID: מזהה המשאב של מופע Agent Runtime של סוכן האב.

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

אתם יכולים להקצות תפקיד 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.proj-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

הנחיות לגבי CI/CD ואוטומציה

בצינורות עיבוד נתונים לפריסה אוטומטית שמוחקים ויוצרים מחדש סוכנים (כמו פריסות blue-green, סביבות בדיקה זמניות או תהליכי עבודה של Terraform), יכולה להיות אובדן גישה שקט בזמן הריצה. מכיוון שכל פריסה מחדש יוצרת משאב reasoningEngines חדש עם מזהה ייחודי, הסוכן מקבל מזהה ראשי חדש. ההרשאות הקודמות ב-IAM שניתנו לגורם הקודם לא עוברות בירושה לגורם החדש.

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

  • אחזור דינמי של מזהה הישות המורשית החדשה: צריך לתעד את הערך spec.effectiveIdentity מתגובת הפריסה, או לשלוח שאילתה ל-API בארכיטקטורת REST אחרי הפריסה כדי לקבל את הזהות הפעילה של הסוכן. מחילים את הקישורים הנדרשים של IAM על הגורם החדש הזה כשלב אחרי הפריסה.

    לדוגמה, כדי לשלוח שאילתה לגבי הזהות הפעילה עם gcloud, משתמשים בפקודה הבאה:

    gcloud ai reasoning-engines describe RESOURCE_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --format="value(spec.effectiveIdentity)"

    ב-Terraform, אפשר ליצור באופן דינמי את זהות הסוכן מתוך מזהה המשאב google_vertex_ai_reasoning_engine שנפרס, ולהפנות אליה בקישורי IAM:

    resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
  provider = google-beta

  project      = var.project_id
  region       = var.region
  display_name = var.display_name
  description  = var.agent_description

  spec {
    agent_framework = "google-adk"
    identity_type   = "AGENT_IDENTITY"

    source_code_spec {
      inline_source {
        source_archive = filebase64(data.archive_file.agent_tarball.output_path)
      }

      python_spec {
        entrypoint_module = var.agent_python_spec.entrypoint_module
        entrypoint_object = var.agent_python_spec.entrypoint_object
        requirements_file = var.agent_python_spec.requirements_path
        version           = var.agent_python_spec.version
      }
    }

    deployment_spec {
      env {
        name  = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"
        value = "true"
      }

      env {
        name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
        value = "true"
      }
    }
  }
}

locals {
  agent_resource_id        = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1)
  agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}"
}

  • שימוש ב-principalSets בהיקף הפרויקט להרשאות בסיסיות: מכיוון שקישורי principalSet מכוונים לכל הסוכנים בפרויקט, הם נשמרים גם אם הסוכן נמחק ונוצר מחדש. מקצים תפקידים נפוצים ולא רגישים (כמו שימוש בשירות, רישום ביומן והסקת מסקנות כללית של מודל) ל-principalSet ברמת הפרויקט במקום לסוכנים ספציפיים. הגבלת קשירת principal://משתמשים בודדים למקורות נתונים רגישים מאוד.

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

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

  • כשהנציג פועל בשם המשתמש, ביומנים מוצגים גם זהות הנציג וגם זהות המשתמש.

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

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

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

המסוף

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

    מעבר לדף Deployments

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

  2. זהות הסוכן מופיעה בעמודה זהות של כל סוכן.

‫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

מדריך

שימוש בסוכן עם Agent Platform Runtime.