מעבר ל-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). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (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 (roles/iamconnectors.user) למזהה SPIFFE של הסוכן במשאב connectors/AUTH_PROVIDER_NAME מדור קודם, צריך להקצות את התפקיד משתמש בזהות הסוכן (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"

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