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. הגדרת הפרויקט
- אם אין לכם עדיין חשבון Google, אתם צריכים ליצור חשבון Google.
- להשתמש בחשבון לשימוש אישי במקום בחשבון של מקום עבודה או מוסד לימודים. בחשבונות של מקומות עבודה ומוסדות לימודים יכולות להיות הגבלות שמונעות הפעלה של ממשקי ה-API שנדרשים ל-Lab הזה.
- נכנסים למסוף Google Cloud.
- מפעילים את החיוב במסוף Cloud.
- השלמת ה-Lab הזה אמורה לעלות פחות מ-1 דולר ארה"ב במשאבי Cloud.
- כדי למנוע חיובים נוספים, אתם יכולים לפעול לפי השלבים שבסוף ה-Lab הזה כדי למחוק משאבים.
- משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$.
- יוצרים פרויקט חדש או בוחרים להשתמש בפרויקט קיים.
- אם מופיעה שגיאה לגבי מכסת הפרויקטים, צריך להשתמש מחדש בפרויקט קיים או למחוק פרויקט קיים כדי ליצור פרויקט חדש.
השתמשו בפרויקט חדש או בפרויקט קיים שבו אתם יכולים להתנסות בבטחה, ולא בפרויקט בסביבת ייצור. הסוכן מעלה, מפרסם ומפעיל שילובים בתיקייה הזו באמצעות פרטי הכניסה שלכם.
3. פתיחת Cloud Shell Editor
- לוחצים על הקישור הזה כדי לעבור ישירות אל Cloud Shell Editor.
- אם תתבקשו לאשר בשלב כלשהו היום, לחצו על Authorize כדי להמשיך.

- אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
- לוחצים על הצגה.
- לוחצים על Terminal (מסוף).

- בטרמינל, מגדירים את הפרויקט באמצעות הפקודה הבאה:
- פורמט:
gcloud config set project [PROJECT_ID] - דוגמה:
gcloud config set project lab-project-id-example - אם אתם לא זוכרים את מזהה הפרויקט:
- כדי להציג את כל מזהי הפרויקטים, אפשר להשתמש בפקודה:
gcloud projects list | awk '/PROJECT_ID/{print $2}'

- כדי להציג את כל מזהי הפרויקטים, אפשר להשתמש בפקודה:
- פורמט:
- ההודעה הבאה אמורה להופיע:
אם מופיע הסימן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.
- שימו לב למזהה הפרויקט, כי תצטרכו להדביק אותו בהנחיה בהמשך:
gcloud config get-value project - מפעילים את Application Integration API:
gcloud services enable integrations.googleapis.com - נכנסים לדף Application Integration במסוף Google Cloud ובוחרים את הפרויקט.
- בדף 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: אבחון של הפעלות שנכשלו, נתקעו או לא הפיקו פלט.
- יוצרים ספרייה ל-Lab הזה ועוברים אליה:
mkdir ~/appint-agent-lab && cd ~/appint-agent-lab - מתקינים את שלושת הסקילים:
לכל מיומנות, תוכנת ההתקנה שואלת כמה שאלות. Gemini CLI כלול באפשרות ברירת המחדל Universal (.agents/skills), אז מקישים על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-troubleshootingEnterכדי להשאיר אותה, בוחרים באפשרות Project בתור היקף ההתקנה ומאשרים את ההתקנה.
הסקילים עכשיו ב~/appint-agent-lab/.agents/skills.
6. הפעלת Gemini CLI
- מפעילים את Gemini CLI מספריית ה-Lab:
כש-Gemini CLI שואל אם אתם סומכים על התיקייה הזו, בוחרים באפשרות Trust folder. Gemini CLI טוען מיומנויות מתיקיית פרויקט רק אחרי שמאשרים שהתיקייה מהימנה, ואז מפעיל מחדש. אם הוא לא מופעל מחדש, פותחים טרמינל חדש, עוברים אלgemini~/appint-agent-labומריצים שוב אתgemini. יכול להיות שתצטרכו ללחוץ עלEnterכדי לאשר הגדרות ברירת מחדל מסוימות. - כדי להציג את רשימת המיומנויות ש-Gemini CLI יכול להשתמש בהן:
שלוש המיומנויות של/skillsapplication-integration-*אמורות להופיע ברשימה.
7. בנייה, פרסום והרצה של השילוב
- מדביקים את ההנחיה הזו ב-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. - בפעם הראשונה שהסוכן משתמש במיומנות, Gemini CLI מבקש מכם להפעיל אותה. מאשרים אותה.
- הסוכן כותב קובץ גרסת שילוב, כמו
sample-claims-adjudication.json. הוא מכיל את הטריגר (triggerConfigs), המשימות (taskConfigs) והמשתנים (integrationParameters). כדאי לקרוא אותו ולבקש מהסוכן להסביר דברים לא צפויים. לדוגמה, כדאי לבדוק אם הסוכן הפעיל את Cloud Logging (cloudLoggingDetails.enableCloudLogging), כי זה יכול להוסיף עלויות. כדי להשבית אותה, מגדירים אתenableCloudLoggingלערךfalseומסירים אתcloudLoggingSeverity. - מאשרים את הפקודות. Gemini CLI מבקש אישור לפני שהוא מריץ כל פקודה, כולל פקודות לקריאה בלבד. הכישורים גם מורים לסוכן להראות לכם את הפקודה או הבקשה המדויקת לפני שהוא משנה משהו, כמו העלאה, פרסום או הפעלה של השילוב. אם הנציג מבקש אישור בלי להציג את הפקודה, בקשו ממנו להציג אותה. לפני שמאשרים, בודקים את הפרויקט, האזור ושם האינטגרציה, ודוחים פקודות שקוראות או משנות אינטגרציות שלא שייכות לכם.
אחרי שאתם מאשרים, הנציג מעלה את קובץ ה-JSON כגרסה חדשה (versions.upload), מפרסם אותו (versions.publish) ומריץ אותו דרך הטריגר של ה-API (integrations.execute). לאחר מכן הוא מציג לכם את ההחלטה, הסיבה ומזהה ההרצה.
8. אימות הביצוע
מריצים את השילוב שפורסם וקוראים את רשומת ההפעלה שלו.
- פותחים כרטיסייה חדשה של מסוף Cloud Shell, עוברים לספריית ה-Lab ושומרים את מזהה הפרויקט והאזור במשתנים:
cd ~/appint-agent-lab export PROJECT_ID=$(gcloud config get-value project) export LOCATION=us-central1 - מריצים את השילוב עם תביעה מעל 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. - קוראים את רשומת הביצוע. מחליפים את
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. הסרת המשאבים
- ב-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) - מקלידים
/quitולוחצים עלEnterכדי לצאת מ-Gemini CLI. - מוחקים את ספריית ה-Lab:
cd ~ && rm -rf ~/appint-agent-lab
11. מזל טוב
יצרתם, פרסמתם, הפעלתם ובדקתם שילוב באמצעות הנחיה לסוכן AI עם מיומנויות של סוכן Application Integration.
המאמרים הבאים
- איך יוצרים שילוב עם סוכן AI
- מיומנויות של סוכני Application Integration
- קראו את המיומנויות ב-GitHub: יסודות, יצירה ופתרון בעיות.