איך יוצרים שילוב עם סוכן AI ומיומנויות של סוכני Application Integration

1. מבוא

בשיעור ה-Lab הזה תבנו שילוב של Application Integration באמצעות תיאור שלו לסוכן AI. אתם מתקינים את שלושת הסקילים הציבוריים של סוכן Application Integration מהמאגר google/skills, ואז נותנים הנחיה ל-Gemini CLI לכתוב, להעלות, לפרסם ולהריץ אינטגרציה קטנה לדוגמה.

הדוגמה sample-claims-adjudication מקבלת תביעת ביטוח ומחזירה את הערכים APPROVE,‏ REVIEW או DENY.

הפעולות שתבצעו:

  • להגדיר את Application Integration בפרויקט ב-Google Cloud.
  • מתקינים את המיומנויות של סוכן Application Integration.
  • מנחים את Gemini CLI ליצור, להעלות, לפרסם ולהריץ אינטגרציה.
  • בודקים את ההרצה בעצמכם ומבקשים מהסוכן לפתור בעיות.
  • מנקים את השילוב לדוגמה.

מה תלמדו

  • מה הסקילים application-integration-basics, -authoring ו--troubleshooting נותנים לסוכן.
  • איך בודקים את גרסת השילוב ב-JSON ואת הפקודות שהנציג מריץ לפני שמאשרים אותן.
  • איך קוראים רשומת ביצוע.

2. הגדרת הפרויקט

  1. אם אין לכם עדיין חשבון Google, אתם צריכים ליצור חשבון Google.
    • להשתמש בחשבון לשימוש אישי במקום בחשבון של מקום עבודה או מוסד לימודים. בחשבונות של מקומות עבודה ומוסדות לימודים יכולות להיות הגבלות שמונעות הפעלה של ממשקי ה-API שנדרשים ל-Lab הזה.
  2. נכנסים למסוף Google Cloud.
  3. מפעילים את החיוב במסוף Cloud.
    • השלמת ה-Lab הזה אמורה לעלות פחות מ-1 דולר ארה"ב במשאבי Cloud.
    • כדי למנוע חיובים נוספים, אתם יכולים לפעול לפי השלבים שבסוף ה-Lab הזה כדי למחוק משאבים.
    • משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$‎.
  4. יוצרים פרויקט חדש או בוחרים להשתמש בפרויקט קיים.
    • אם מופיעה שגיאה לגבי מכסת הפרויקטים, צריך להשתמש מחדש בפרויקט קיים או למחוק פרויקט קיים כדי ליצור פרויקט חדש.

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

3. פתיחת Cloud Shell Editor

  1. לוחצים על הקישור הזה כדי לעבור ישירות אל Cloud Shell Editor.
  2. אם תתבקשו לאשר בשלב כלשהו היום, לחצו על Authorize כדי להמשיך. לוחצים כדי לאשר את Cloud Shell.
  3. אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
    • לוחצים על הצגה.
    • לוחצים על Terminal (מסוף).פתיחת טרמינל חדש ב-Cloud Shell Editor
  4. בטרמינל, מגדירים את הפרויקט באמצעות הפקודה הבאה:
    • פורמט:
      gcloud config set project [PROJECT_ID]
      
    • דוגמה:
      gcloud config set project lab-project-id-example
      
    • אם אתם לא זוכרים את מזהה הפרויקט:
      • כדי להציג את כל מזהי הפרויקטים, אפשר להשתמש בפקודה:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      הגדרת מזהה הפרויקט בטרמינל של Cloud Shell Editor
  5. ההודעה הבאה אמורה להופיע:
    Updated property [core/project].
    
    אם מופיע הסימן WARNING ומוצגת השאלה Do you want to continue (Y/n)?, כנראה שהזנתם מזהה פרויקט שגוי. מקישים על n, מקישים על Enter ומנסים להריץ שוב את הפקודה gcloud config set project.

4. הגדרת Application Integration

השירות Application Integration הוא אזורי, ולכן מגדירים אותו באזור אחד. ב-Lab הזה משתמשים ב-us-central1.

  1. שימו לב למזהה הפרויקט, כי תצטרכו להדביק אותו בהנחיה בהמשך:
    gcloud config get-value project
    
  2. מפעילים את Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. נכנסים לדף Application Integration במסוף Google Cloud ובוחרים את הפרויקט.
  4. בדף Overview, בוחרים את האזור us-central1 ולוחצים על Quick setup. בסיום ההגדרה, במסוף תוצג הרשימה Integrations. אם אתם משתמשים בפרויקט קיים, ודאו שיש לכם את התפקידים שמפורטים בקטע הגדרת Application Integration לפני שתלחצו על Quick setup.

מידע נוסף זמין במאמר הגדרת Application Integration.

5. התקנת הסקילים של הסוכן

הסקילים נותנים לסוכן את הידע שלו ב-Application Integration:

  • ‫application-integration-basics: מושגים, הפעלת ממשקי API, הקצאת אזור, תפקידי IAM ומגבלות.
  • ‫application-integration-authoring: כתיבת גרסאות של אינטגרציות כ-JSON, והעלאה, פרסום והרצה שלהן.
  • ‫application-integration-troubleshooting: אבחון של הפעלות שנכשלו, נתקעו או לא הפיקו פלט.
  1. יוצרים ספרייה ל-Lab הזה ועוברים אליה:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. מתקינים את שלושת הסקילים:
    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
    
    לכל מיומנות, תוכנת ההתקנה שואלת כמה שאלות. ‫Gemini CLI כלול באפשרות ברירת המחדל Universal (.agents/skills), אז מקישים על Enter כדי להשאיר אותה, בוחרים באפשרות Project בתור היקף ההתקנה ומאשרים את ההתקנה.

הסקילים עכשיו ב~/appint-agent-lab/.agents/skills.

6. הפעלת Gemini CLI

  1. מפעילים את Gemini CLI מספריית ה-Lab:
    gemini
    
    כש-Gemini CLI שואל אם אתם סומכים על התיקייה הזו, בוחרים באפשרות Trust folder. ‫Gemini CLI טוען מיומנויות מתיקיית פרויקט רק אחרי שמאשרים שהתיקייה מהימנה, ואז מפעיל מחדש. אם הוא לא מופעל מחדש, פותחים טרמינל חדש, עוברים אל ~/appint-agent-lab ומריצים שוב את gemini. יכול להיות שתצטרכו ללחוץ על Enter כדי לאשר הגדרות ברירת מחדל מסוימות.
  2. כדי להציג את רשימת המיומנויות ש-Gemini CLI יכול להשתמש בהן:
    /skills
    
    שלוש המיומנויות של application-integration-* אמורות להופיע ברשימה.

7. בנייה, פרסום והרצה של השילוב

  1. מדביקים את ההנחיה הזו ב-Gemini CLI. מחליפים את PROJECT_ID במזהה הפרויקט שציינתם בהגדרת Application Integration.
    Using the Application Integration skills, build an integration named
    sample-claims-adjudication in project PROJECT_ID, region us-central1.
    
    - 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.
    
  2. בפעם הראשונה שהסוכן משתמש במיומנות, Gemini CLI מבקש מכם להפעיל אותה. מאשרים אותה.
  3. הסוכן כותב קובץ גרסת שילוב, כמו sample-claims-adjudication.json. הוא מכיל את הטריגר (triggerConfigs), המשימות (taskConfigs) והמשתנים (integrationParameters). כדאי לקרוא אותו ולבקש מהסוכן להסביר דברים לא צפויים. לדוגמה, כדאי לבדוק אם הסוכן הפעיל את Cloud Logging (cloudLoggingDetails.enableCloudLogging), כי זה יכול להוסיף עלויות. כדי להשבית אותה, מגדירים את enableCloudLogging לערך false ומסירים את cloudLoggingSeverity.
  4. מאשרים את הפקודות. ‫Gemini CLI מבקש אישור לפני שהוא מריץ כל פקודה, כולל פקודות לקריאה בלבד. הכישורים גם מורים לסוכן להראות לכם את הפקודה או הבקשה המדויקת לפני שהוא משנה משהו, כמו העלאה, פרסום או הפעלה של השילוב. אם הנציג מבקש אישור בלי להציג את הפקודה, בקשו ממנו להציג אותה. לפני שמאשרים, בודקים את הפרויקט, האזור ושם האינטגרציה, ודוחים פקודות שקוראות או משנות אינטגרציות שלא שייכות לכם.

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

8. אימות הביצוע

מריצים את השילוב שפורסם וקוראים את רשומת ההפעלה שלו.

  1. פותחים כרטיסייה חדשה של מסוף Cloud Shell, עוברים לספריית ה-Lab ושומרים את מזהה הפרויקט והאזור במשתנים:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. מריצים את השילוב עם תביעה מעל 1,000:
    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/sample-claims-adjudication:execute"
    
    התשובה מכילה executionId ו-outputParameters, כאשר decision מוגדר כ-REVIEW.
  3. קוראים את רשומת הביצוע. מחליפים את EXECUTION_ID ב-executionId מהתשובה:
    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/sample-claims-adjudication/executions"
    
    בתגובה, executionDetails.state הוא SUCCEEDED, ו-executionDetails.executionSnapshots מראה את המצב של כל משימה.

אפשר גם לראות את ההרצה ביומני ההרצה במסוף Google Cloud.

9. פתרון בעיות

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

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

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

אם משהו משתבש בשיעור ה-Lab הזה, כדאי לבדוק את הסיבות הנפוצות הבאות:

  • /skills לא מפרט את המיומנויות של Application Integration. מפעילים את Gemini CLI מ-~/appint-agent-lab ומגדירים את התיקייה כמהימנה.
  • קריאה נכשלת עם PERMISSION_DENIED. מוודאים שאתם משתמשים בפרויקט הנכון, ושיש לכם בו את התפקיד "עריכה של Application Integration" (roles/integrations.integrationEditor).
  • הפעלת השילוב נכשלת עם No integrations found for the requested trigger_id. צריך לוודא שהפרויקט והאזור בבקשה תואמים למקום שבו פורסם השילוב, ש-triggerId הוא api_trigger/adjudicate_claim ושגרסה של השילוב פורסמה. השגיאה הזו תופיע גם אם העליתם גרסה אבל לא פרסמתם אותה.

10. הסרת המשאבים

  1. ב-Gemini CLI, מבקשים מהסוכן להסיר את השילוב לדוגמה:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    אחרי האישור, הנציג מבטל את הפרסום של הגרסה שפורסמה (versions.unpublish) ומוחק כל גרסה (versions.delete). כשלא נשארות גרסאות, השילוב לא מופיע יותר ברשימת השילובים.אם יצרתם פרויקט רק בשביל שיעור ה-Lab הזה, אתם יכולים למחוק את הפרויקט במקום להסיר את השילוב. מריצים את הפקודה הבאה בכרטיסיית הטרמינל שפתחתם בקטע אימות ההרצה:
    gcloud projects delete $(gcloud config get-value project)
    
  2. מקלידים /quit ולוחצים על Enter כדי לצאת מ-Gemini CLI.
  3. מוחקים את ספריית ה-Lab:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. מזל טוב

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

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