מעבר ל-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 במסוף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 או ה-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"

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