Utilizza la CLI OpenCode

Utilizza la CLI OpenCode

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questa pagina descrive come utilizzare l'interfaccia a riga di comando (CLI) OpenCode con un'istanza di Gemini Enterprise Agent Platform Workbench.

Questo documento è destinato ad analisti di dati, data scientist e sviluppatori di dati che lavorano con Agent Platform Workbench. Questo documento presuppone che tu sappia scrivere codice in un ambiente notebook.

Panoramica

OpenCode è un agente di codifica AI open source che viene eseguito in un terminale. Per saperne di più, visita opencode.ai.

Quando un amministratore lo attiva, la CLI OpenCode è disponibile in un terminale nell'interfaccia JupyterLab dell'istanza Agent Platform Workbench. Puoi utilizzarlo per lavorare con i notebook e i file sull'istanza ed eseguire comandi shell e Google Cloud comandi, fornendo istruzioni in linguaggio naturale.

Limitazioni

Tieni presente le seguenti limitazioni quando utilizzi la CLI OpenCode con Agent Platform Workbench:

• OpenCode è solo una CLI. Non sono inclusi un'interfaccia grafica di chat e strumenti avanzati nell'editor.

• Quando chiedi a OpenCode di modificare un blocco note, OpenCode modifica il file del blocco note direttamente sul disco dell'istanza. Per questo motivo, non puoi annullare le modifiche apportate da OpenCode utilizzando il pulsante Annulla dell'editor di blocchi note o Ctrl+Z (Cmd+Z su macOS). Tuttavia, puoi chiedere a OpenCode di annullare una modifica utilizzando un comando in linguaggio naturale, ad esempio Undo your last change.

• Poiché OpenCode scrive direttamente su disco, può modificare un file che hai aperto anche in JupyterLab. Se hai modifiche non salvate in un notebook, salvale prima di chiedere a OpenCode di modificare lo stesso notebook.

• OpenCode viene eseguito con le credenziali attive nella tua istanza. Per impostazione predefinita, queste sono le credenziali delaccount di serviziot dell'istanza di Agent Platform Workbench, quindi OpenCode può accedere alle stesse risorse a cui può accedere l'istanza. Se autentichi un'identità diversa sull'istanza (ad esempio eseguendo gcloud auth login o gcloud auth application-default login), OpenCode utilizza le autorizzazioni di questa identità.

Prima di iniziare

Poiché si tratta di una tecnologia in fase iniziale, Gemini per i prodotti Google Cloud può generare output apparentemente plausibili, ma di fatto errati. Ti consigliamo di verificare tutti gli output di Gemini per i prodotti Google Cloud prima di utilizzarli. Per saperne di più, consulta Gemini for Google Cloud e l'AI responsabile.

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

2. Verify that billing is enabled for your Google Cloud 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

Ruoli obbligatori

Per utilizzare la CLI OpenCode in Agent Platform Workbench, devi concedere le autorizzazioni all'utente dell'istanza di Agent Platform Workbench e alaccount di serviziont dell'istanza.

Nota :OpenCode opera rigorosamente all'interno delle autorizzazioni dell'ambiente dell'istanza di Agent Platform Workbench. Se tu (o il account di servizio utilizzato dalla tua istanza) non hai l'autorizzazione ad accedere a una risorsa specifica, OpenCode non potrà accedervi. Se un comando non riesce a causa delle autorizzazioni, chiedi all'amministratore di concedere le autorizzazioni necessarie.

Concedi le autorizzazioni all'utente dell'istanza

Per ottenere le autorizzazioni necessarie per utilizzare la CLI OpenCode in un'istanza di Agent Platform Workbench, chiedi all'amministratore di concederti il ruolo IAM Agent Platform User (roles/aiplatform.user) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi un'autorizzazione al account di servizio della tua istanza

Per assicurarti che il service account dell'istanza di Agent Platform Workbench disponga delle autorizzazioni necessarie per consentire l'esecuzione della CLI OpenCode in un'istanza di Agent Platform Workbench, chiedi all'amministratore di concedere al account di servizio account dell'istanza di Agent Platform Workbench il ruolo IAM Agent Platform User (roles/aiplatform.user) sul progetto.

Importante: devi concedere questo ruolo al service account dell'istanza di Agent Platform Workbench, non al tuo account utente. La mancata concessione del ruolo all'entità corretta potrebbe comportare errori di autorizzazione.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione aiplatform.endpoints.predict necessaria per abilitare l'esecuzione della CLI OpenCode in un'istanza di Agent Platform Workbench.

L'amministratore potrebbe anche essere in grado di concedere al service account dell'istanza di Agent Platform Workbench questa autorizzazione tramite ruoli personalizzati o altri ruoli predefiniti.

Abilita la CLI OpenCode

La CLI OpenCode è disponibile solo sulle istanze Agent Platform Workbench che utilizzano l'immagine Debian 12 (workbench-instances-2603). Non è installato su istanze che utilizzano l'immagine Debian 11 (workbench-instances).

L'interfaccia a riga di comando OpenCode è attiva per impostazione predefinita sulle istanze supportate. Per disattivarlo, imposta la chiave dei metadati dell'istanza enable-opencode su false. Per saperne di più, consulta Gestire le funzionalità tramite i metadati.

Utilizza la CLI OpenCode

1. Nella console Google Cloud , vai alla pagina Istanze.

   Vai a Istanze

2. Accanto al nome di un'istanza di Agent Platform Workbench, fai clic su Apri JupyterLab.

3. In JupyterLab, fai clic su File > Nuovo launcher.

4. Nella scheda Avvio app, nella sezione Altro, fai clic sul riquadro OpenCode.

   Si apre un terminale e viene avviata la CLI OpenCode.

5. Inserisci un prompt, ad esempio "Crea un nuovo notebook chiamato "test-notebook"".

6. Quando OpenCode propone un'azione, ad esempio la modifica di un file o l'esecuzione di un comando shell, rivedila e approvala o rifiutala. Per saperne di più, vedi Approvare le azioni degli strumenti.

Approvare le azioni dello strumento

Per impostazione predefinita, OpenCode in Agent Platform Workbench chiede la tua approvazione prima di intraprendere qualsiasi azione, ad esempio modificare un file, eseguire un comando shell o recuperare un URL. Esamina ogni azione proposta prima di approvarla.

Questa impostazione predefinita protegge dal prompt injection. Un notebook, uno script o una pagina web che OpenCode legge potrebbe contenere istruzioni nascoste che tentano di far eseguire all'agente comandi che non avevi intenzione di eseguire, ad esempio l'invio dei tuoi dati a un indirizzo esterno. Poiché OpenCode viene eseguito con le credenziali della tua istanza, la richiesta di approvazione ti offre l'opportunità di visualizzare e interrompere un'azione prima che venga eseguita.

Attenzione: puoi modificare questo comportamento nella tua configurazione OpenCode, incluso disattivare completamente le richieste di approvazione. In questo caso, OpenCode esegue le azioni senza chiederti prima e accetti il rischio conseguente di prompt injection ed esfiltrazione di dati per i tuoi workload.

Utilizzare modelli di terze parti

Per impostazione predefinita, OpenCode in Agent Platform Workbench è configurato per utilizzare solo i modelli Gemini e Claude forniti tramite Gemini Enterprise Agent Platform nel tuo progetto. Queste richieste vengono autenticate con le credenziali della tua istanza rispetto alla tua istanza di Gemini Enterprise Agent Platform, quindi rimangono all'interno del tuo progettoGoogle Cloud e rimangono soggette ai controlli di sicurezza applicabili.

OpenCode supporta anche i fornitori di modelli le cui richieste vengono inviate al di fuori del tuo progetto. Questi includono Google AI Studio (l'API Gemini Developer), che, nonostante offra modelli Gemini, è un servizio separato che esegue l'autenticazione con una chiave API personale anziché con le credenziali del progetto, nonché fornitori non Google come le API dirette di OpenAI e Anthropic. Tutte queste opzioni sono disattivate per impostazione predefinita. Puoi attivarne uno modificando la tua configurazione OpenCode e fornendo la chiave API del provider.

Avviso: se abiliti uno di questi provider, i tuoi prompt e tutti i dati contenuti, inclusi i dati letti dai tuoi blocchi note e file, vengono inviati all'API esterna del provider. Questi dati escono dai confini del tuo progetto Google Cloud . Non è più protetto dai controlli di sicurezza applicati al tuo progetto, inclusa la protezione Model Armor contro il prompt injection, se l'hai configurata. L'attivazione di un fornitore è una tua decisione e responsabilità, incluso il rispetto di qualsiasi contratto di gestione dei dati stipulato con questo fornitore.

Controllare l'accesso alla CLI OpenCode

L'accesso a OpenCode è regolato da due controlli indipendenti: se il launcher OpenCode viene mostrato e se è possibile chiamare i modelli sottostanti. Queste impostazioni sono separate: nascondere il launcher non blocca i modelli e limitare i modelli non rimuove il launcher, quindi configura entrambi in modo che corrispondano alla policy della tua organizzazione.

Controllare se viene visualizzato l'Avvio app OpenCode

Per controllare se OpenCode viene offerto su un'istanza, utilizza la chiave dei metadati dell'istanza enable-opencode. OpenCode è attivo per impostazione predefinita: il riquadro OpenCode viene visualizzato nel launcher JupyterLab, a meno che un amministratore non imposti la chiave su false, che lo nasconde.

Questa impostazione controlla solo se viene visualizzato l'avvio app. Non blocca di per sé l'accesso ai modelli: un utente che può raggiungere l'ambiente dell'istanza (ad esempio tramite un terminale) può comunque avviare OpenCode e chiamare qualsiasi modello che le sue credenziali sono autorizzate a utilizzare. Per limitare le azioni che OpenCode può eseguire, controlla l'accesso ai modelli come descritto nella sezione successiva.

Controllare l'accesso ai modelli

OpenCode chiama i modelli tramite Gemini Enterprise Agent Platform utilizzando le credenziali della tua istanza, ovvero la stessa autenticazione di Gemini Enterprise Agent Platform utilizzata dalla CLI Gemini. Gli utenti non inseriscono una chiave API per utilizzare i modelli Gemini e Claude predefiniti; una richiesta ha esito positivo solo se l'identità dell'istanza è autorizzata a chiamare il modello e il progetto ha accesso. Questo controllo determina se OpenCode può generare risposte e si applica indipendentemente da come viene avviato OpenCode.

Per gestire l'accesso ai modelli, utilizza gli stessi controlli applicati a qualsiasi client Gemini Enterprise Agent Platform:

• Per consentire o limitare modelli specifici a livello di organizzazione, cartella o progetto, configura un criterio dell'organizzazione. Consulta Controllare l'accesso ai modelli di Model Garden.

• Per impedire a un'identità di utilizzare gli endpoint del modello per l'inferenza, non concederle l'autorizzazione aiplatform.endpoints.predict.

• I modelli di provider esterni al tuo progetto (ad esempio l'API diretta di Anthropic) richiedono all'utente di fornire la chiave API del provider nella propria configurazione OpenCode e sono disattivati per impostazione predefinita. Per saperne di più, consulta Utilizzare modelli di terze parti.

Passaggi successivi

• Scopri di più su Gemini Enterprise Agent Platform.

• Per scoprire come impostare i metadati dell'istanza, consulta Gestire le funzionalità tramite i metadati.