Usa la CLI de OpenCode

Usa la CLI de OpenCode

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta página, se describe cómo usar la interfaz de línea de comandos (CLI) de OpenCode con una instancia de Gemini Enterprise Agent Platform Workbench.

Este documento está dirigido a analistas de datos, científicos de datos y desarrolladores de datos que trabajan con Agent Platform Workbench. En este documento, se supone que sabes escribir código en un entorno de notebook.

Descripción general

OpenCode es un agente de programación de IA de código abierto que se ejecuta en una terminal. Para obtener más información, consulta opencode.ai.

Cuando un administrador la habilita, la CLI de OpenCode está disponible en una terminal en la interfaz de JupyterLab de tu instancia de Agent Platform Workbench. Puedes usarlo para trabajar con los notebooks y los archivos de tu instancia, y para ejecutar comandos de shell y comandos de Google Cloud dando instrucciones en lenguaje natural.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando uses la CLI de OpenCode con Agent Platform Workbench:

• OpenCode solo está disponible en la CLI. No se incluyen una interfaz de chat gráfica ni herramientas avanzadas en el editor.

• Cuando le pides a OpenCode que modifique un notebook, OpenCode cambia el archivo del notebook directamente en el disco de la instancia. Por este motivo, no puedes deshacer las ediciones realizadas por OpenCode con el botón Deshacer del editor de notebooks ni con Ctrl+Z (Cmd+Z en macOS). Sin embargo, puedes pedirle a OpenCode que deshaga un cambio con un comando en lenguaje natural, como Undo your last change.

• Como OpenCode escribe directamente en el disco, puede cambiar un archivo que también tengas abierto en JupyterLab. Si tienes cambios sin guardar en un cuaderno, guárdalos antes de pedirle a OpenCode que modifique ese mismo cuaderno.

• OpenCode se ejecuta con las credenciales que están activas en tu instancia. De forma predeterminada, estas son las credenciales de la cuenta de servicio de tu instancia de Agent Platform Workbench, por lo que OpenCode puede acceder a los mismos recursos a los que puede acceder la instancia. Si autenticas una identidad diferente en la instancia (por ejemplo, ejecutando gcloud auth login o gcloud auth application-default login), OpenCode usará los permisos de esa identidad.

Antes de comenzar

Como tecnología en etapa inicial, los productos de Gemini para Google Cloud pueden generar resultados que parecen posibles, pero que no son correctos. Te recomendamos que valides todos los resultados de Gemini para los productos de Google Cloud antes de usarlos. Para obtener más información, consulta Gemini para Google Cloud y la IA responsable.

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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

Roles obligatorios

Para usar la CLI de OpenCode en Agent Platform Workbench, debes otorgar permisos al usuario de la instancia de Agent Platform Workbench y a la cuenta de servicio de la instancia.

Nota: OpenCode opera estrictamente dentro de los permisos del entorno de tu instancia de Agent Platform Workbench. Si tú (o la cuenta de servicio que usa tu instancia) no tienen permiso para acceder a un recurso específico, OpenCode tampoco podrá acceder a él. Si un comando falla debido a los permisos, pídele a tu administrador que te otorgue los permisos necesarios.

Otorga permisos al usuario de la instancia

Para obtener los permisos que necesitas para usar la CLI de OpenCode en una instancia de Agent Platform Workbench, pídele a tu administrador que te otorgue el rol de IAM de Usuario de Agent Platform (roles/aiplatform.user) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga un permiso a la cuenta de servicio de tu instancia

Para garantizar que la cuenta de servicio de tu instancia de Agent Platform Workbench tenga el permiso necesario para habilitar la CLI de OpenCode para que se ejecute en una instancia de Agent Platform Workbench, pídele a tu administrador que le otorgue el rol de IAM de Usuario de Agent Platform (roles/aiplatform.user) a la cuenta de servicio de tu instancia de Agent Platform Workbench en el proyecto.

Importante: Debes otorgar este rol a la cuenta de servicio de tu instancia de Agent Platform Workbench, no a tu cuenta de usuario. Si no se otorga el rol a la entidad principal correcta, es posible que se produzcan errores de permisos.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso aiplatform.endpoints.predict, que se requiere para habilitar la CLI de OpenCode para que se ejecute en una instancia de Agent Platform Workbench.

Es posible que tu administrador también pueda otorgar este permiso a la cuenta de servicio de tu instancia de Agent Platform Workbench con roles personalizados o con otros roles predefinidos.

Habilita la CLI de OpenCode

La CLI de OpenCode solo está disponible en las instancias de Agent Platform Workbench que usan la imagen de Debian 12 (workbench-instances-2603). No está instalado en instancias que usan la imagen de Debian 11 (workbench-instances).

La CLI de OpenCode está activada de forma predeterminada en las instancias compatibles. Para desactivarlo, establece la clave de metadatos de la instancia enable-opencode en false. Para obtener más información, consulta Administra funciones a través de metadatos.

Usa la CLI de OpenCode

1. En la consola de Google Cloud , ve a la página Instancias.

   Ir a Instancias

2. Junto al nombre de una instancia de Agent Platform Workbench, haz clic en Abrir JupyterLab.

3. En JupyterLab, haz clic en Archivo > Nuevo selector.

4. En la pestaña Selector, en la sección Otros, haz clic en la tarjeta OpenCode.

   Se abrirá una terminal y se iniciará la CLI de OpenCode.

5. Ingresa una instrucción, como "Crea un cuaderno nuevo llamado "test-notebook"".

6. Cuando OpenCode proponga una acción, como editar un archivo o ejecutar un comando de shell, revísala y aprueba o rechaza. Para obtener más información, consulta Cómo aprobar acciones de herramientas.

Cómo aprobar acciones de herramientas

De forma predeterminada, OpenCode en Agent Platform Workbench te pide aprobación antes de realizar cualquier acción, como editar un archivo, ejecutar un comando de shell o recuperar una URL. Revisa cada acción propuesta antes de aprobarla.

Este valor predeterminado protege contra la inyección de instrucciones. Un notebook, una secuencia de comandos o una página web que lee OpenCode podría contener instrucciones ocultas que intenten hacer que el agente ejecute comandos que no querías, como enviar tus datos a una dirección externa. Como OpenCode se ejecuta con las credenciales de tu instancia, solicitar aprobación te brinda la oportunidad de ver y detener esa acción antes de que se ejecute.

Precaución: Puedes cambiar este comportamiento en tu propia configuración de OpenCode, incluso desactivar por completo las indicaciones de aprobación. Si lo haces, OpenCode ejecutará acciones sin preguntarte primero, y aceptarás el riesgo resultante de inyección de instrucciones y robo de datos para tus cargas de trabajo.

Usar modelos de terceros

De forma predeterminada, OpenCode en Agent Platform Workbench está configurado para usar solo los modelos de Gemini y Claude que se entregan a través de Gemini Enterprise Agent Platform en tu proyecto. Estas solicitudes se autentican con las credenciales de tu instancia en tu propia Gemini Enterprise Agent Platform, por lo que permanecen dentro de tu proyecto deGoogle Cloud y están sujetas a los controles de seguridad que se aplican a él.

OpenCode también admite proveedores de modelos cuyas solicitudes se envían fuera de tu proyecto. Estos incluyen Google AI Studio (la API de Gemini Developer), que, a pesar de ofrecer modelos de Gemini, es un servicio independiente que se autentica con una clave de API personal en lugar de las credenciales de tu proyecto, así como proveedores que no son de Google, como las APIs directas de OpenAI y Anthropic. Todas estas opciones están desactivadas de forma predeterminada. Para activar uno, edita tu propia configuración de OpenCode y proporciona la clave de API del proveedor.

Advertencia: Si habilitas uno de estos proveedores, tus instrucciones y todos los datos que contengan, incluidos los datos que se leen de tus notebooks y archivos, se envían a la API externa de ese proveedor. Estos datos salen de los límites de tu proyecto Google Cloud . Ya no está protegida por los controles de seguridad que se aplican en tu proyecto, incluida la protección de Model Armor contra la inyección de instrucciones, si la configuraste. Habilitar a un proveedor de este tipo es tu decisión y responsabilidad, incluido el cumplimiento de cualquier acuerdo de manejo de datos que tengas con ese proveedor.

Controla el acceso a la CLI de OpenCode

El acceso a OpenCode se rige por dos controles independientes: si se muestra el selector de OpenCode y si se pueden llamar a los modelos subyacentes. Estas opciones son independientes: ocultar el selector no bloquea los modelos, y restringir los modelos no quita el selector. Por lo tanto, configura ambas opciones para que coincidan con la política de tu organización.

Controla si aparece el selector de OpenCode

Para controlar si se ofrece OpenCode en una instancia, usa la clave de metadatos de instancia enable-opencode. OpenCode está activado de forma predeterminada: la tarjeta de OpenCode aparece en el Launcher de JupyterLab, a menos que un administrador establezca la clave en false, lo que la oculta.

Este parámetro de configuración solo controla si se presenta el selector. Por sí misma, no bloquea el acceso a los modelos: un usuario que puede acceder al entorno de la instancia (por ejemplo, a través de una terminal) puede iniciar OpenCode y llamar a cualquier modelo que sus credenciales le permitan usar. Para restringir lo que puede hacer OpenCode, controla el acceso a los modelos como se describe en la siguiente sección.

Controla el acceso a los modelos

OpenCode llama a los modelos a través de Gemini Enterprise Agent Platform con las credenciales de tu instancia, la misma autenticación de Gemini Enterprise Agent Platform que usa la CLI de Gemini. Los usuarios no ingresan una clave de API para usar los modelos predeterminados de Gemini y Claude. Una solicitud solo se realiza correctamente si la identidad de la instancia tiene permiso para llamar al modelo y el proyecto tiene acceso a él. Este control determina si OpenCode puede generar respuestas y se aplica independientemente de cómo se inicie OpenCode.

Para administrar el acceso al modelo, usa los mismos controles que se aplican a cualquier cliente de Gemini Enterprise Agent Platform:

• Para permitir o restringir modelos específicos a nivel de la organización, la carpeta o el proyecto, configura una política de la organización. Consulta Controla el acceso a los modelos de Model Garden.

• Para impedir que una identidad use extremos de modelos para la inferencia, no le otorgues el permiso aiplatform.endpoints.predict.

• Los modelos de proveedores externos a tu proyecto (por ejemplo, la API directa de Anthropic) requieren que el usuario proporcione la clave de API de ese proveedor en su propia configuración de OpenCode y están desactivados de forma predeterminada. Para obtener más información, consulta Usa modelos de terceros.

¿Qué sigue?

• Obtén más información sobre Gemini Enterprise Agent Platform.

• Para obtener información sobre cómo configurar los metadatos de la instancia, consulta Administra atributos a través de los metadatos.