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

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

סקירה כללית

זהות הסוכן מספקת זהות לכל סוכן, שמאפשרת גישה של הרשאה מינימלית וקשורה למחזור החיים של הסוכן. לכן, זהות הסוכן היא חשבון משתמש מאובטח יותר מחשבונות שירות. אמצעי הבקרה הקיימים לניהול גישה באמצעות 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 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.proj-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 ולשירותים באמצעות זהות הסוכן

אחרי שיוצרים סוכן עם זהות סוכן, אפשר להעניק או לדחות את הגישה של הסוכן ל- 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: האזור שלכם. אזורים נתמכים ב-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.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 ואוטומציה

בצינורות עיבוד נתונים לפריסה אוטומטית שמוחקים ויוצרים מחדש סוכנים (כמו פריסות כחולות-ירוקות, סביבות בדיקה זמניות או תהליכי עבודה של 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.