איך יוצרים שילוב עם סוכן AI

בדף הזה מוסבר איך ליצור שילוב באמצעות הנחיה לסוכן AI לכתיבת קוד. אתם מתארים מה השילוב אמור לעשות, והסוכן כותב את השילוב, מעלה ומפרסם אותו באמצעות Application Integration API בארכיטקטורת REST, מריץ אותו ועוזר לכם לפתור בעיות. לדוגמה, אתם יוצרים שילוב פשוט של פסיקה בתביעות ביטוח.

הנציג מקבל את הידע שלו על Application Integration משלוש מיומנויות שזמינות לכולם במאגר google/skills:

כדי לראות את קובצי הרפרנס של כל מיומנות, עיינו במאמר מיומנויות של סוכני Application Integration.

לפני שמתחילים

  1. השתמשו בפרויקט ב- Google Cloud שבו תוכלו להתנסות בבטחה, ולא בפרויקט בסביבת ייצור. החיוב צריך להיות מופעל בפרויקט.
  2. להגדיר את Application Integration בפרויקט, באזור נתמך. כדי להגדיר את Application Integration צריך תפקידים משלו, שמפורטים בדף הזה.
  3. מתקינים את ה-CLI של gcloud ונכנסים באמצעות gcloud auth login. הסוכן קורא ל-API בארכיטקטורת REST בשמכם, באמצעות פרטי הכניסה שלכם ל-gcloud או באמצעות Application Default Credentials (אם הוא משתמש בספריית לקוח). אם הסוכן משתמש בספריית לקוח, יכול להיות שתתבקשו להריץ את gcloud auth application-default login.
  4. משתמשים בסוכן AI לתכנות שתומך במיומנויות של סוכנים.

התפקידים הנדרשים

אחרי שמגדירים את Application Integration, צריך את התפקידים הבאים כדי ליצור ולהריץ שילובים.

כדי לקבל את ההרשאות שדרושות להעלאה, לפרסום ולהפעלה של אינטגרציות ולצפייה בהפעלות שלהן, אתם צריכים לבקש מהאדמין לתת לכם את התפקידים הבאים ב-IAM:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

במאמר הקצאת התפקיד "משתמש בחשבון שירות" לחשבונות שירות להרצה מוסבר מי צריך את התפקיד ואיך מקצים אותו.

התקנת המיומנויות של הסוכן

בטרמינל, מריצים את הפקודות הבאות כדי להתקין את שלוש המיומנויות:

npx skills add google/skills --skill application-integration-basics
npx skills add google/skills --skill application-integration-authoring
npx skills add google/skills --skill application-integration-troubleshooting

כשמוצגת בקשה, בוחרים את הסוכנים שרוצים להגדיר ואת היקף ההתקנה. אם הסוכן שלכם לא מופיע ברשימה, האפשרות האוניברסלית שמוגדרת כברירת מחדל מתקינה את .agents/skills. יכול להיות שתוכנת ההתקנה תציע גם מיומנויות אחרות, כמו find-skills; אתם לא צריכים אותן בשביל הדף הזה. חלק מהסוכנים טוענים מיומנויות מתיקיית פרויקט רק אחרי שאתם מגדירים את התיקייה כמהימנה. אם npx לא זמין, מתקינים את Node.js שכולל אותו. כדי לעדכן את המיומנויות מאוחר יותר, מריצים את הפקודה npx skills update.

תיאור השילוב

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

Using the Application Integration skills, build an integration named
claims-adjudication in project PROJECT_ID, region LOCATION.

- Start it with an API trigger named adjudicate_claim.
- Inputs: claimId (string), claimAmount (double), policyActive (boolean).
- Outputs: decision (string) and reason (string).
- Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less,
  return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation.
- Save the integration version JSON in this directory so I can review it.
- Show me every command before you run it, then upload, publish, and run it
  once with a sample claim.

מחליפים את PROJECT_ID במזהה הפרויקט ואת LOCATION באזור שבו הגדרתם את Application Integration.

בודקים את התוכנית ומאשרים את הפקודות

הנציג כותב קובץ גרסת שילוב, לדוגמה claims-adjudication.json. הוא מכיל את הטריגר (triggerConfigs), המשימות (taskConfigs) והמשתנים (integrationParameters). כדאי לקרוא אותו לפני שממשיכים, ולבקש מהנציג להסביר כל דבר שלא ציפית לו. לדוגמה, בודקים אם הסוכן הפעיל את Cloud Logging (cloudLoggingDetails.enableCloudLogging), מה שיכול להוסיף עלויות. כדי להשבית אותה, מגדירים את enableCloudLogging לערך false ומסירים את cloudLoggingSeverity.

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

העלאה, פרסום והפעלה של האינטגרציה

אחרי שתאשרו, הנציג יבצע את הקריאות הבאות ל-Application Integration API:

  1. versions.upload מעלה את קובץ ה-JSON כגרסה חדשה של השילוב.
  2. versions.publish מפרסם את הגרסה הזו. גרסה שפורסמה היא ACTIVE, וכל גרסה שפורסמה בעבר לא מפורסמת.
  3. integrations.execute מפעיל את השילוב שפורסם באופן סינכרוני דרך הטריגר של ה-API.

אתם יכולים גם להריץ בעצמכם את האינטגרציה שפורסמה:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "triggerId": "api_trigger/adjudicate_claim",
      "inputParameters": {
        "claimId": {"stringValue": "CLM-1001"},
        "claimAmount": {"doubleValue": 2500},
        "policyActive": {"booleanValue": true}
      }
    }' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/claims-adjudication:execute"

התשובה מכילה executionId ואת משתני הפלט של האינטגרציה ב-outputParameters.

בדיקת הביצוע ופתרון בעיות

תגובה מוצלחת מ-integrations.execute לא תמיד אומרת שכל משימה פעלה כמו שציפיתם. אסטרטגיית הניסיון החוזר של המשימה יכולה לאפשר להרצה להמשיך אחרי שהמשימה נכשלת: עם Ignore, האינטגרציה מתייחסת למשימה שנכשלה כאילו היא הצליחה, ועם None, האינטגרציה עדיין יכולה להסתיים בהצלחה דרך נתיב חלופי. בנוסף, אם בבקשה מוגדר doNotPropagateError ל-true, השגיאות מוחזרות בתגובה במקום כסטטוס שגיאה. מבקשים מהסוכן לבדוק את הביצוע, לדוגמה:

Check execution EXECUTION_ID of claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.

הסוכן קורא את רשומת ההרצה באמצעות השיטה executions.list, ומסנן לפי מזהה ההרצה:

curl -G \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode 'filter=execution_id="EXECUTION_ID"' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/claims-adjudication/executions"

ברשומה מוצג מצב ההפעלה, למשל SUCCEEDED,‏ FAILED או SUSPENDED, והמצב של כל משימה. אפשר גם לפתוח את יומני ההפעלה במסוף Google Cloud . כברירת מחדל, Cloud Logging מושבת לאינטגרציות. כדי להשתמש בו, קראו את המאמר הצגת יומני אינטגרציות ב-Cloud Logging.

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

שיטות מומלצות

  • מתחילים מחוץ לסביבת הייצור. בונים ובודקים בפרויקט שלא מיועד לסביבת הייצור, ואז מקדמים את קובץ ה-JSON שנבדק. העלאה והורדה של שילובים
  • שימוש בחשבון שירות ייעודי להרצה בתור. השתמשו בחשבון שירות ייעודי עם היקף מינימלי לכל שילוב. הגדרת חשבון שירות להרצה
  • אל תאחסנו סודות במשתני הגדרות אישיות. משתני ההגדרות נשמרים ומיוצאים כטקסט פשוט. במקום זאת, צריך להשתמש בפרופיל אימות או במשימת הגישה של Secret Manager.
  • בודקים את קובץ ה-JSON שנוצר. שמרו אותו בבקרת המקור ובדקו את השינויים לפני שאתם מעלים אותם. פרופילי האימות לא נכללים בקובץ, לכן צריך להגדיר אותם בכל פרויקט.

הסרת המשאבים

כדי להסיר את השילוב לדוגמה, מבקשים מהנציג:

Unpublish claims-adjudication, then delete every version of it.

אחרי האישור, הנציג קורא ל-versions.unpublish בגרסה שפורסמה ול-versions.delete בכל גרסה. כשלא נשארות גרסאות, האינטגרציה לא מופיעה יותר ברשימת האינטגרציות. כדי למחוק את השילוב עצמו, צריך תפקיד כמו אדמין של Application Integration. אי אפשר למחוק את השילוב עם תפקיד עריכה.

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