Menggunakan OpenCode CLI

Menggunakan OpenCode CLI

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Halaman ini menjelaskan cara menggunakan antarmuka command line (CLI) OpenCode dengan instance Gemini Enterprise Agent Platform Workbench.

Dokumen ini ditujukan untuk analis data, data scientist, dan developer data yang menggunakan Agent Platform Workbench. Dokumen ini mengasumsikan Anda memiliki pengetahuan tentang cara menulis kode di lingkungan notebook.

Ringkasan

OpenCode adalah agen coding AI open source yang berjalan di terminal. Untuk mengetahui informasi selengkapnya, lihat opencode.ai.

Jika diaktifkan oleh administrator, OpenCode CLI akan tersedia di terminal di antarmuka JupyterLab instance Agent Platform Workbench Anda. Anda dapat menggunakannya untuk menangani notebook dan file di instance Anda, serta menjalankan perintah shell dan perintah Google Cloud , dengan memberikan petunjuk dalam bahasa alami.

Batasan

Pertimbangkan batasan berikut saat Anda menggunakan OpenCode CLI dengan Agent Platform Workbench:

• OpenCode hanya berupa CLI. Antarmuka chat grafis dan alat dalam editor tingkat lanjut tidak disertakan.

• Saat Anda meminta OpenCode untuk mengubah notebook, OpenCode akan mengubah file notebook secara langsung di disk instance. Oleh karena itu, Anda tidak dapat mengurungkan pengeditan yang dilakukan oleh OpenCode menggunakan tombol Urungkan editor notebook atau Control+Z (Command+Z di macOS). Namun, Anda dapat meminta OpenCode untuk mengurungkan perubahan menggunakan perintah bahasa alami, seperti Undo your last change.

• Karena OpenCode menulis langsung ke disk, OpenCode dapat mengubah file yang juga Anda buka di JupyterLab. Jika Anda memiliki perubahan yang belum disimpan di notebook, simpan perubahan tersebut sebelum meminta OpenCode untuk mengubah notebook yang sama.

• OpenCode berjalan dengan kredensial yang aktif di instance Anda. Secara default, kredensial ini adalah kredensial akun layanan instance Agent Platform Workbench Anda, sehingga OpenCode dapat mengakses resource yang sama dengan yang dapat diakses instance. Jika Anda mengautentikasi identitas yang berbeda pada instance (misalnya, dengan menjalankan gcloud auth login atau gcloud auth application-default login), OpenCode akan menggunakan izin identitas tersebut.

Sebelum memulai

Sebagai teknologi tahap awal, Gemini untuk produk Google Cloud dapat menghasilkan output yang seolah masuk akal, tetapi mengandung fakta yang salah. Sebaiknya Anda memvalidasi semua output dari Gemini untuk Google Cloud produk sebelum Anda menggunakannya. Untuk mengetahui informasi selengkapnya, lihat Gemini untuk Google Cloud dan AI yang bertanggung jawab.

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Peran yang diperlukan

Untuk menggunakan OpenCode CLI di Agent Platform Workbench, Anda harus memberikan izin kepada pengguna instance Agent Platform Workbench dan akun layanan instance.

Catatan: OpenCode beroperasi secara ketat dalam izin lingkungan instance Agent Platform Workbench Anda. Jika Anda (atau akun layanan yang digunakan instance Anda) tidak memiliki izin untuk mengakses resource tertentu, OpenCode juga tidak akan dapat mengaksesnya. Jika perintah gagal karena izin, minta administrator Anda untuk memberikan izin yang diperlukan.

Memberikan izin kepada pengguna instance

Untuk mendapatkan izin yang diperlukan untuk menggunakan OpenCode CLI di instance Agent Platform Workbench, minta administrator Anda untuk memberi Anda peran IAM Agent Platform User (roles/aiplatform.user) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Memberikan izin ke akun layanan instance Anda

Untuk memastikan bahwa akun layanan instance Agent Platform Workbench Anda memiliki izin yang diperlukan untuk mengaktifkan OpenCode CLI agar dapat berjalan di instance Agent Platform Workbench, minta administrator Anda untuk memberikan peran IAM Pengguna Agent Platform (roles/aiplatform.user) kepada akun layanan instance Agent Platform Workbench Anda di project.

Penting: Anda harus memberikan peran ini ke akun layanan instance Agent Platform Workbench Anda, bukan ke akun pengguna Anda. Jika peran tidak diberikan kepada akun utama yang tepat, error izin mungkin terjadi.

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin aiplatform.endpoints.predict yang diperlukan untuk mengaktifkan OpenCode CLI agar dapat berjalan di instance Agent Platform Workbench.

Administrator Anda mungkin juga dapat memberi akun layanan instance Agent Platform Workbench Anda izin ini dengan peran khusus atau peran bawaan lainnya.

Mengaktifkan OpenCode CLI

CLI OpenCode hanya tersedia di instance Agent Platform Workbench yang menggunakan image Debian 12 (workbench-instances-2603). Tidak diinstal pada instance yang menggunakan image Debian 11 (workbench-instances).

CLI OpenCode diaktifkan secara default pada instance yang didukung. Untuk menonaktifkannya, tetapkan kunci metadata instance enable-opencode ke false. Untuk mengetahui informasi selengkapnya, lihat Mengelola fitur melalui metadata.

Menggunakan OpenCode CLI

1. Di konsol Google Cloud , buka halaman Instances.

   Buka Instances

2. Di samping nama instance Agent Platform Workbench, klik Open JupyterLab.

3. Di JupyterLab, klik File > New launcher.

4. Di tab Launcher, di bagian Other, klik kartu OpenCode.

   Terminal akan terbuka dan memulai OpenCode CLI.

5. Masukkan perintah, seperti "Buat notebook baru bernama 'test-notebook'".

6. Saat OpenCode menyarankan tindakan, seperti mengedit file atau menjalankan perintah shell, tinjau dan setujui atau tolak tindakan tersebut. Untuk mengetahui informasi selengkapnya, lihat Menyetujui tindakan alat.

Menyetujui tindakan alat

Secara default, OpenCode di Agent Platform Workbench akan meminta persetujuan Anda sebelum melakukan tindakan apa pun, seperti mengedit file, menjalankan perintah shell, atau mengambil URL. Tinjau setiap tindakan yang diusulkan sebelum Anda menyetujuinya.

Setelan default ini melindungi dari injeksi perintah. Notebook, skrip, atau halaman web yang dibaca OpenCode dapat berisi instruksi tersembunyi yang mencoba membuat agen menjalankan perintah yang tidak Anda inginkan, seperti mengirim data Anda ke alamat eksternal. Karena OpenCode berjalan dengan kredensial instance Anda, persetujuan diperlukan agar Anda dapat melihat dan menghentikan tindakan tersebut sebelum dijalankan.

Perhatian: Anda dapat mengubah perilaku ini dalam konfigurasi OpenCode Anda sendiri, termasuk menonaktifkan perintah persetujuan sepenuhnya. Jika Anda melakukannya, OpenCode akan menjalankan tindakan tanpa meminta izin Anda terlebih dahulu, dan Anda menerima risiko injeksi perintah dan pemindahan data yang tidak sah untuk beban kerja Anda.

Menggunakan model pihak ketiga

Secara default, OpenCode di Agent Platform Workbench dikonfigurasi untuk menggunakan hanya model Gemini dan Claude yang ditayangkan melalui Gemini Enterprise Agent Platform di project Anda. Permintaan ini diautentikasi dengan kredensial instance Anda terhadap Gemini Enterprise Agent Platform project Anda sendiri, sehingga permintaan tersebut tetap berada dalam Google Cloud project Anda dan tetap tunduk pada kontrol keamanan yang berlaku untuk project tersebut.

OpenCode juga mendukung penyedia model yang permintaannya dikirim di luar project Anda. Hal ini mencakup Google AI Studio (Gemini Developer API), yang meskipun menawarkan model Gemini, merupakan layanan terpisah yang mengautentikasi dengan kunci API pribadi, bukan kredensial project Anda, serta penyedia non-Google seperti OpenAI dan API langsung Anthropic. Semua opsi ini dinonaktifkan secara default. Anda dapat mengaktifkannya dengan mengedit konfigurasi OpenCode Anda sendiri dan memberikan kunci API penyedia.

Peringatan: Jika Anda mengaktifkan salah satu penyedia ini, perintah Anda—dan data apa pun yang terkandung di dalamnya, termasuk data yang dibaca dari notebook dan file Anda—akan dikirim ke API eksternal penyedia tersebut. Data ini keluar dari batas project Google Cloud Anda. Model tidak lagi dilindungi oleh kontrol keamanan yang berlaku dalam project Anda, termasuk perlindungan Model Armor terhadap injeksi perintah, jika Anda telah mengonfigurasinya. Mengaktifkan penyedia tersebut adalah keputusan dan tanggung jawab Anda, termasuk kepatuhan terhadap perjanjian penanganan data yang Anda miliki dengan penyedia tersebut.

Mengontrol akses ke OpenCode CLI

Akses ke OpenCode diatur oleh dua kontrol independen: apakah peluncur OpenCode ditampilkan, dan apakah model yang mendasarinya dapat dipanggil. Keduanya terpisah—menyembunyikan peluncur tidak memblokir model, dan membatasi model tidak menghapus peluncur—jadi, konfigurasikan keduanya agar sesuai dengan kebijakan organisasi Anda.

Mengontrol apakah peluncur OpenCode muncul

Untuk mengontrol apakah OpenCode ditawarkan di instance, gunakan kunci metadata instance enable-opencode. OpenCode aktif secara default: kartu OpenCode muncul di peluncur JupyterLab kecuali jika administrator menyetel kunci ke false, yang menyembunyikannya.

Setelan ini hanya mengontrol apakah peluncur ditampilkan. Dengan sendirinya, hal ini tidak memblokir akses ke model: pengguna yang dapat mengakses lingkungan instance (misalnya, melalui terminal) tetap dapat memulai OpenCode dan memanggil model apa pun yang kredensialnya diizinkan untuk digunakan. Untuk membatasi kemampuan OpenCode, kontrol akses ke model seperti yang dijelaskan di bagian berikutnya.

Mengontrol akses ke model

OpenCode memanggil model melalui Gemini Enterprise Agent Platform menggunakan kredensial instance Anda—autentikasi Gemini Enterprise Agent Platform yang sama dengan yang digunakan Gemini CLI. Pengguna tidak memasukkan kunci API untuk menggunakan model Gemini dan Claude default; permintaan hanya berhasil jika identitas instance diizinkan untuk memanggil model dan project memiliki akses ke model tersebut. Kontrol ini menentukan apakah OpenCode dapat membuat respons, dan berlaku terlepas dari cara OpenCode dimulai.

Untuk mengelola akses model, gunakan kontrol yang sama yang berlaku untuk klien Gemini Enterprise Agent Platform:

• Untuk mengizinkan atau membatasi model tertentu di tingkat organisasi, folder, atau project, siapkan kebijakan organisasi. Lihat Mengontrol akses ke model Model Garden.

• Untuk memblokir identitas agar tidak menggunakan endpoint model untuk inferensi, jangan berikan izin aiplatform.endpoints.predict kepadanya.

• Model dari penyedia di luar project Anda (misalnya, Anthropic Direct API) mengharuskan pengguna memberikan kunci API penyedia tersebut dalam konfigurasi OpenCode mereka sendiri, dan dinonaktifkan secara default. Untuk mengetahui informasi selengkapnya, lihat Menggunakan model pihak ketiga.

Langkah berikutnya

• Pelajari lebih lanjut Gemini Enterprise Agent Platform.

• Untuk mempelajari cara menyetel metadata instance, lihat Mengelola fitur melalui metadata.