Utilizza l'interfaccia a riga di comando OpenCode

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

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

Panoramica

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

Quando un amministratore la abilita, l'interfaccia a riga di comando OpenCode è disponibile in un terminale nell'interfaccia JupyterLab dell'istanza Agent Platform Workbench. Puoi utilizzarlo per lavorare con i notebook e i file della tua istanza e per eseguire comandi della shell e comandi Cloud de Confiance by S3NS fornendo istruzioni in linguaggio naturale.

Limitazioni

Tieni presente le seguenti limitazioni quando utilizzi l'interfaccia a riga di comando OpenCode con Agent Platform Workbench:

  • OpenCode è solo un'interfaccia a riga di comando. Non sono incluse un'interfaccia di chat grafica e strumenti avanzati nell'editor.

  • Quando chiedi a OpenCode di modificare un notebook, OpenCode modifica il file del notebook direttamente sul disco dell'istanza. Per questo motivo, non puoi annullare le modifiche apportate da OpenCode utilizzando il pulsante Annulla dell'editor del notebook o Ctrl+Z (Comando+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 sul 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 sulla tua istanza. Per impostazione predefinita, si tratta delle credenziali del account di servizio dell'istanza di Agent Platform Workbench, in modo che OpenCode possa accedere alle stesse risorse dell'istanza. Se autentichi un'identità diversa nell'istanza (ad esempio, eseguendo gcloud auth login o gcloud auth application-default login), OpenCode utilizza le autorizzazioni di quell'identità.

Prima di iniziare

  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

Ruoli obbligatori

Per utilizzare l'interfaccia a riga di comando OpenCode in Agent Platform Workbench, devi concedere le autorizzazioni all'utente dell'istanza di Agent Platform Workbench e al account di servizio dell'istanza.

Concedi le autorizzazioni all'utente dell'istanza

Per ottenere le autorizzazioni necessarie per utilizzare l'interfaccia a riga di comando 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 dell'istanza

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

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 consentire l'esecuzione dell'interfaccia a riga di comando 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 l'interfaccia a riga di comando OpenCode

L'interfaccia a riga di comando OpenCode è disponibile solo nelle 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 disattivarla, imposta la chiave dei metadati dell'istanza enable-opencode su false. Per saperne di più, consulta Gestisci le funzionalità tramite i metadati.

Utilizza l'interfaccia a riga di comando OpenCode

  1. Nella console Cloud de Confiance , 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 avviatore.

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

    Si apre un terminale e viene avviata l'interfaccia a riga di comando OpenCode.

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

  6. Quando OpenCode propone un'azione, ad esempio la modifica di un file o l'esecuzione di un comando shell, esaminala e approvala o rifiutala. Per saperne di più, consulta Approva le azioni dello strumento.

Approva le azioni dello strumento

Per impostazione predefinita, OpenCode in Agent Platform Workbench chiede la tua approvazione prima di eseguire 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 letti da OpenCode potrebbero contenere istruzioni nascoste che tentano di far eseguire all'agente comandi non previsti, 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 di questo tipo prima che venga eseguita.

Utilizza 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 Gemini Enterprise Agent Platform del tuo progetto, in modo che rimangano all'interno del tuo progettoCloud de Confiance by S3NS e rimangano soggette ai controlli di sicurezza applicabili.

OpenCode supporta anche i provider di modelli le cui richieste vengono inviate all'esterno 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é provider 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 di OpenCode e fornendo la chiave API del provider.

Controlla l'accesso all'interfaccia a riga di comando OpenCode

L'accesso a OpenCode è regolato da due controlli indipendenti: se il launcher di OpenCode viene mostrato e se i modelli sottostanti possono essere chiamati. Queste impostazioni sono separate: nascondere l'Avvio app non blocca i modelli e limitare i modelli non rimuove l'Avvio app. Configura entrambe le impostazioni in base alle policy della tua organizzazione.

Controllare se viene visualizzato il programma di avvio OpenCode

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

Questa impostazione controlla solo se il programma di avvio viene visualizzato. Di per sé, non blocca 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.

Controlla l'accesso ai modelli

OpenCode chiama i modelli tramite Gemini Enterprise Agent Platform utilizzando le credenziali della tua istanza, la stessa autenticazione di Gemini Enterprise Agent Platform utilizzata dall'interfaccia a riga di comando di Gemini. Gli utenti non inseriscono una chiave API per utilizzare i modelli Gemini e Claude predefiniti; una richiesta va a buon fine solo se l'identità dell'istanza è autorizzata a chiamare il modello e il progetto ha accesso al modello. 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 che si applicano a qualsiasi client di Gemini Enterprise Agent Platform:

  • Per consentire o limitare modelli specifici a livello di organizzazione, cartella o progetto, configura una policy dell'organizzazione. Consulta Controlla 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 Utilizza modelli di terze parti.

Passaggi successivi