מעבר ל-Agent Identity API

במאמר הזה מוסבר איך להעביר את הנציגים וספקי האימות שפרסתם מ-IAM Connectors API הקודם (iamconnectors.googleapis.com) ל-Agent Identity API החדש (agentidentity.googleapis.com).

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

תהליך ההעברה כולל את המשימות הבאות:

  1. הפעלת Agent Identity API
  2. עדכון מדיניות ההרשאות של IAM
  3. עדכון קוד הנציג וערכות ה-SDK
  4. השבתת ה-API הקודם

הפעלת Agent Identity API

כדי להתחיל את המיגרציה, צריך להפעיל את Agent Identity API החדש בפרויקט.

מפעילים את Agent Identity API, אם הוא עדיין לא מופעל.

התפקידים שנדרשים כדי להפעיל ממשקי API

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

להפעלת ה-API

כשמפעילים את Agent Identity API, הדף Agent Registry במסוףCloud de Confiance עובר ל-API החדש כדי לקרוא ולכתוב משאבים:

  • אין צורך ליצור מחדש את ספקי האימות. ה-API החדש משקף כל ספק אימות מדור קודם (לדוגמה, projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) כמשאב authProviders (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME).

  • ספק אימות שאתם יוצרים באמצעות מסוף Cloud de Confiance , ה-CLI של gcloud או ה-API בארכיטקטורת REST מופיע כמשאב authProviders/ ולא גלוי ב-API הקודם.

  • הסוכנים הפעילים שמשתמשים במחרוזות connectors/ מדור קודם ממשיכים לפעול במהלך חלון ההעברה.

עדכון מדיניות ההרשאות של IAM

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

לדוגמה, אם הקציתם את התפקיד Connector User (roles/iamconnectors.user) למזהה ה-SPIFFE של הנציג במשאב connectors/AUTH_PROVIDER_NAME הקודם, הקצו את התפקיד Agent Identity User (roles/agentidentity.user) במשאב authProviders/AUTH_PROVIDER_NAME החדש:

gcloud agent-identity auth-providers add-iam-policy-binding \
    AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

אם אתם בודקים את הנציג באופן מקומי באמצעות adk web, תנו את ההרשאה roles/agentidentity.user לחשבון המשתמש האישי שלכם (user:USER_EMAIL).

עדכון קוד הסוכן וערכות ה-SDK

מעדכנים את קוד הסוכן כך שיפנה להיררכיית המשאבים ולנקודות הקצה החדשות של authProviders/:

  1. מעדכנים את גרסת ה-ADK בקוד של הנציג לגרסה 2.3.0 ואילך.

  2. בקוד של הנציג (לדוגמה, agent.py), מחליפים את connectors/ ב-authProviders/ במחרוזת המשאב GcpAuthProviderScheme.

    הגדרה מדור קודם: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

    הגדרה חדשה: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

  3. ‫OAuth עם 3 רגליים בלבד: אם הסוכן קורא ישירות ל-API בארכיטקטורת REST, צריך לעדכן את שם המארח של נקודת הקצה מ-iamconnectorcredentials.googleapis.com ל-agentidentitycredentials.googleapis.com, ולהחליף את connectors/ ב-authProviders/ בנתיב הבקשה.

  4. רק ב-OAuth תלת-רגלי: בשרת האימות של ממשק המשתמש (לדוגמה, main.py), מעדכנים את כתובת ה-URL של נקודת הקצה (FinalizeCredentials) ל-https://agentidentitycredentials.googleapis.com/v1. בנוסף, קוראים את הערך של auth_provider_name מהבקשה הנכנסת ומגדירים אותו בתור השדה auth_provider בגוף הבקשה של FinalizeCredentials.

השבתת ה-API הקודם

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

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

gcloud services disable iamconnectors.googleapis.com \
    --project="PROJECT_ID"

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