מעבר ל-Agent Identity API

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

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

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

  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 במסוףGoogle Cloud עובר ל-API החדש כדי לקרוא ולכתוב משאבים:

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

  • ספק אימות חדש שנוצר באמצעות Google Cloud המסוף או ה-CLI של gcloud מופיע כמשאב 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 alpha agent-identity authProviders 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 3.0: בשרת האימות של חזית האתר (לדוגמה, main.py), מעדכנים את כתובת ה-URL של נקודת הקצה FinalizeCredentials ל-https://agentidentitycredentials.googleapis.com/v1alpha. בנוסף, קוראים את הערך של auth_provider_name מהבקשה הנכנסת ומגדירים אותו כשדה auth_provider בגוף הבקשה FinalizeCredentials.

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

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

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

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

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