שימוש ב-OpenCode CLI

בדף הזה מוסבר איך להשתמש בממשק שורת הפקודה (CLI) של OpenCode עם מופע של Gemini Enterprise Agent Platform Workbench.

המסמך הזה מיועד למנתחי נתונים, למדעני נתונים ולמפתחי נתונים שעובדים עם Agent Platform Workbench. במסמך הזה אנחנו מניחים שיש לכם ידע בכתיבת קוד בסביבת מחברת.

סקירה כללית

‫OpenCode הוא סוכן AI בקוד פתוח לתכנות שפועל בטרמינל. מידע נוסף זמין באתר opencode.ai.

כשהאדמין מפעיל את OpenCode CLI, הוא זמין בטרמינל בממשק JupyterLab של מכונת Agent Platform Workbench. אתם יכולים להשתמש בו כדי לעבוד עם קובצי ה-notebook והקבצים במופע, וכדי להריץ פקודות shell ופקודות Google Cloud , על ידי מתן הוראות בשפה טבעית.

מגבלות

כשמשתמשים ב-OpenCode CLI עם Agent Platform Workbench, חשוב להביא בחשבון את המגבלות הבאות:

  • ‫OpenCode הוא CLI בלבד. לא כלולים ממשק גרפי לצ'אט וכלים מתקדמים בעורך.

  • כשמבקשים מ-OpenCode לשנות מחברת, OpenCode משנה את קובץ המחברת ישירות בדיסק של המופע. לכן, אי אפשר לבטל עריכות שבוצעו על ידי OpenCode באמצעות הלחצן ביטול בעורך ה-notebook או באמצעות Control+Z (Command+Z ב-macOS). עם זאת, אתם יכולים לבקש מ-OpenCode לבטל שינוי באמצעות פקודה בשפה טבעית, כמו Undo your last change.

  • מכיוון ש-OpenCode כותב ישירות לדיסק, הוא יכול לשנות קובץ שפתוח גם ב-JupyterLab. אם יש לכם שינויים שלא נשמרו ב-notebook, כדאי לשמור אותם לפני שמבקשים מ-OpenCode לשנות את אותו notebook.

  • ההרצה של OpenCode מתבצעת באמצעות פרטי הכניסה שפעילים במופע שלכם. כברירת מחדל, אלה פרטי הכניסה של חשבון השירות של מופע Agent Platform Workbench, כך ש-OpenCode יכול לגשת לאותם משאבים שהמופע יכול לגשת אליהם. אם מאמתים זהות אחרת במופע (לדוגמה, על ידי הפעלת gcloud auth login או gcloud auth application-default login), OpenCode משתמש בהרשאות של הזהות הזו במקום זאת.

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

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

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

כדי להשתמש ב-CLI של OpenCode ב-Agent Platform Workbench, צריך להעניק הרשאות למשתמש של מופע Agent Platform Workbench ולחשבון השירות של המופע.

הענקת הרשאות למשתמש של המופע

כדי לקבל את ההרשאות שנדרשות לשימוש בממשק OpenCode CLI במופע של Agent Platform Workbench, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Agent Platform User (roles/aiplatform.user) בפרויקט. להסבר על מתן תפקידים, קראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

מתן הרשאה לחשבון השירות של המופע

כדי לוודא שלחשבון השירות של מופע Agent Platform Workbench יש את ההרשאה הנדרשת להפעלת OpenCode CLI במופע Agent Platform Workbench, צריך לבקש מהאדמין להקצות לחשבון השירות של מופע Agent Platform Workbench את תפקיד ה-IAM משתמש ב-Agent Platform (roles/aiplatform.user) בפרויקט.

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

התפקיד המוגדר מראש הזה כולל את ההרשאה aiplatform.endpoints.predict, שנדרשת כדי להפעיל את OpenCode CLI במכונת Agent Platform Workbench.

יכול להיות שהאדמין יוכל גם להעניק לחשבון השירות של מופע Agent Platform Workbench את ההרשאה הזו באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

הפעלת OpenCode CLI

‫OpenCode CLI זמין רק במכונות של Agent Platform Workbench שמשתמשות בתמונת Debian 12 ‏ (workbench-instances-2603). היא לא מותקנת במופעים שמשתמשים בתמונה של Debian 11 ‏ (workbench-instances).

כברירת מחדל, כלי OpenCode CLI מופעל במופעים נתמכים. כדי להשבית את התכונה, מגדירים את מפתח המטא-נתונים של המכונה enable-opencode לערך false. מידע נוסף זמין במאמר בנושא ניהול תכונות באמצעות מטא-נתונים.

שימוש ב-OpenCode CLI

  1. נכנסים לדף Instances במסוף Google Cloud .

    כניסה לדף Instances

  2. לצד השם של מופע Agent Platform Workbench, לוחצים על Open JupyterLab.

  3. ב-JupyterLab, לוחצים על File (קובץ) > New launcher (מרכז אפליקציות חדש).

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

    ייפתח טרמינל ויתחיל לפעול OpenCode CLI.

  5. מזינים הנחיה, כמו 'תיצור מחברת חדשה בשם test-notebook'.

  6. כש-OpenCode מציע פעולה, כמו עריכת קובץ או הפעלת פקודת shell, בודקים את הפעולה ומאשרים או דוחים אותה. מידע נוסף זמין במאמר בנושא אישור פעולות בכלי.

אישור פעולות שקשורות לכלים

כברירת מחדל, OpenCode ב-Agent Platform Workbench מבקש את האישור שלכם לפני שהוא מבצע פעולות, כמו עריכת קובץ, הרצת פקודת מעטפת או אחזור כתובת URL. חשוב לבדוק כל פעולה מוצעת לפני שמאשרים אותה.

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

שימוש במודלים של צד שלישי

כברירת מחדל, OpenCode ב-Agent Platform Workbench מוגדר לשימוש רק במודלים של Gemini ו-Claude שמופעלים דרך Gemini Enterprise Agent Platform בפרויקט שלכם. הבקשות האלה מאומתות באמצעות פרטי הכניסה של המופע שלכם מול Gemini Enterprise Agent Platform של הפרויקט, ולכן הן נשארות בתוךGoogle Cloud הפרויקט וכפופות לאמצעי הבקרה שחלים עליו.

בנוסף, OpenCode תומך בספקי מודלים שהבקשות שלהם נשלחות מחוץ לפרויקט. השירותים האלה כוללים את Google AI Studio (Gemini Developer API), שלמרות שהוא מציע מודלים של Gemini, הוא שירות נפרד שמאמת באמצעות מפתח API אישי ולא באמצעות פרטי הכניסה של הפרויקט, וגם ספקים שאינם של Google, כמו ממשקי ה-API הישירים של OpenAI ו-Anthropic. כל האפשרויות האלה מושבתות כברירת מחדל. כדי להפעיל אחת מהן, צריך לערוך את ההגדרה של OpenCode ולספק את מפתח ה-API של הספק.

שליטה בגישה ל-OpenCode CLI

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

קביעה אם מרכז האפליקציות של OpenCode יופיע

כדי לקבוע אם OpenCode מוצע במופע, משתמשים במפתח המטא-נתונים של המופע enable-opencode. האפשרות OpenCode מופעלת כברירת מחדל: הלחצן OpenCode מופיע במרכז האפליקציות של JupyterLab, אלא אם האדמין מגדיר את המפתח לערך false, שמסתיר אותו.

ההגדרה הזו קובעת רק אם מרכז האפליקציות יוצג. היא לא חוסמת את הגישה למודלים: משתמש שיכול להגיע לסביבה של המופע (לדוגמה, דרך מסוף) עדיין יכול להפעיל את OpenCode ולקרוא לכל המודלים שהאישורים שלו מאפשרים לו להשתמש בהם. כדי להגביל את הפעולות שאפשר לבצע ב-OpenCode, צריך לשלוט בגישה למודלים כמו שמתואר בקטע הבא.

שליטה בגישה למודלים

‫OpenCode קורא למודלים דרך Gemini Enterprise Agent Platform באמצעות פרטי הכניסה של המופע שלכם – אותה אימות של Gemini Enterprise Agent Platform שבה משתמש Gemini CLI. המשתמשים לא צריכים להזין מפתח API כדי להשתמש במודלים של Gemini ו-Claude שמוגדרים כברירת מחדל. בקשה תצליח רק אם הזהות של המופע מורשית להפעיל את המודל, ולפרויקט יש גישה אליו. ההגדרה הזו קובעת אם OpenCode יכול ליצור תשובות, והיא חלה על כל דרך שבה OpenCode מופעל.

כדי לנהל את הגישה למודלים, משתמשים באותם אמצעי בקרה שחלים על כל לקוח של Gemini Enterprise Agent Platform:

  • כדי לאפשר או להגביל שימוש במודלים ספציפיים ברמת הארגון, התיקייה או הפרויקט, צריך להגדיר מדיניות ארגונית. מידע נוסף מופיע במאמר שליטה בגישה למודלים ב-Model Garden.

  • כדי לחסום זהות מסוימת משימוש בנקודות קצה של מודלים להסקת מסקנות, אל תעניקו לה את ההרשאה aiplatform.endpoints.predict.

  • מודלים מספקים מחוץ לפרויקט (לדוגמה, ממשק ה-API הישיר של Anthropic) מחייבים את המשתמש לספק את מפתח ה-API של הספק בהגדרה שלו ב-OpenCode, והם מושבתים כברירת מחדל. מידע נוסף זמין במאמר בנושא שימוש במודלים של צד שלישי.

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