שימוש ב-OpenCode CLI

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

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

סקירה כללית

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

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

מגבלות

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

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

  • כשמבקשים מ-OpenCode לשנות קובץ notebook, הוא משנה את הקובץ ישירות בדיסק של המכונה. לכן, אי אפשר לבטל שינויים שבוצעו על ידי 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. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. 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

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

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

מתן הרשאות למשתמש של המכונה

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

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

מתן הרשאה לחשבון השירות של המכונה

כדי לוודא שלחשבון השירות של מכונת 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 במסוף Cloud de Confiance .

    כניסה לדף Instances

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

  3. ב-JupyterLab, לוחצים על File > New launcher.

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

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

  5. מזינים הנחיה, למשל "Create a new notebook named 'test-notebook'".

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

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

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

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

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

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

ב-OpenCode יש גם תמיכה בספקי מודלים שהבקשות שלהם נשלחות מחוץ לפרויקט. הם כוללים את Google AI Studio (‏Gemini Developer API), שלמרות שהוא מציע מודלים של Gemini, הוא שירות נפרד שמאמת באמצעות מפתח API אישי ולא באמצעות פרטי הכניסה של הפרויקט, וגם ספקים שאינם של Google, כמו OpenAI וממשקי API ישירים של 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 שלו. המודלים האלה מושבתים כברירת מחדל. מידע נוסף זמין במאמר שימוש במודלים של צד שלישי.

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