Utiliser la CLI OpenCode

Utiliser la CLI OpenCode

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette page explique comment utiliser l'interface de ligne de commande (CLI) OpenCode avec une instance Gemini Enterprise Agent Platform Workbench.

Ce document est destiné aux analystes de données, aux data scientists et aux développeurs de données qui travaillent avec Agent Platform Workbench. Ce document suppose que vous savez écrire du code dans un environnement de notebook.

Présentation

OpenCode est un agent de codage d'IA Open Source qui s'exécute dans un terminal. Pour en savoir plus, consultez opencode.ai.

Lorsqu'un administrateur l'active, la CLI OpenCode est disponible dans un terminal de l'interface JupyterLab de votre instance Agent Platform Workbench. Vous pouvez l'utiliser pour travailler avec les notebooks et les fichiers de votre instance, et pour exécuter des commandes shell et Google Cloud en donnant des instructions en langage naturel.

Limites

Tenez compte des limites suivantes lorsque vous utilisez l'interface de ligne de commande OpenCode avec Agent Platform Workbench :

• OpenCode est une CLI uniquement. Une interface de chat graphique et des outils avancés dans l'éditeur ne sont pas inclus.

• Lorsque vous demandez à OpenCode de modifier un notebook, OpenCode modifie le fichier du notebook directement sur le disque de l'instance. Par conséquent, vous ne pouvez pas annuler les modifications apportées par OpenCode à l'aide du bouton Annuler de l'éditeur de notebooks ni du raccourci clavier Ctrl+Z (Cmd+Z sur macOS). Toutefois, vous pouvez demander à OpenCode d'annuler une modification à l'aide d'une commande en langage naturel, telle que Undo your last change.

• Étant donné qu'OpenCode écrit directement sur le disque, il peut modifier un fichier que vous avez également ouvert dans JupyterLab. Si vous avez apporté des modifications à un notebook sans les enregistrer, enregistrez-les avant de demander à OpenCode de modifier ce même notebook.

• OpenCode s'exécute avec les identifiants actifs sur votre instance. Par défaut, il s'agit des identifiants du compte de service de votre instance Agent Platform Workbench. OpenCode peut ainsi accéder aux mêmes ressources que l'instance. Si vous authentifiez une autre identité sur l'instance (par exemple, en exécutant gcloud auth login ou gcloud auth application-default login), OpenCode utilise les autorisations de cette identité à la place.

Avant de commencer

Cette technologie étant à un stade précoce, il se peut que les produits Gemini pour Google Cloudgénèrent des résultats qui semblent plausibles, mais qui sont en fait incorrects. Nous vous recommandons de vérifier tous les résultats des produits Gemini pour Google Cloud avant de les utiliser. Pour en savoir plus, consultez la page Gemini pour Google Cloud et l'IA responsable.

Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

Rôles requis

Pour utiliser la CLI OpenCode dans Agent Platform Workbench, vous devez accorder des autorisations à l'utilisateur de l'instance Agent Platform Workbench et au compte de service de l'instance.

Remarque : OpenCode fonctionne strictement dans les limites des autorisations de l'environnement de votre instance Agent Platform Workbench. Si vous (ou le compte de service utilisé par votre instance) n'êtes pas autorisé à accéder à une ressource spécifique, OpenCode ne pourra pas non plus y accéder. Si une commande échoue en raison d'autorisations, demandez à votre administrateur de vous accorder les autorisations nécessaires.

Accorder des autorisations à l'utilisateur de l'instance

Pour obtenir les autorisations nécessaires pour utiliser l'interface de ligne de commande OpenCode dans une instance Agent Platform Workbench, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur Agent Platform (roles/aiplatform.user) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Accorder une autorisation au compte de service de votre instance

Pour vous assurer que le compte de service de votre instance Agent Platform Workbench dispose des autorisations nécessaires pour permettre à l'interface de ligne de commande OpenCode de s'exécuter dans une instance Agent Platform Workbench, demandez à votre administrateur d'attribuer le rôle IAM Utilisateur Agent Platform (roles/aiplatform.user) au compte de service de votre instance Agent Platform Workbench sur le projet.

Important : Vous devez accorder ce rôle au compte de service de votre instance Agent Platform Workbench, et non à votre compte utilisateur. Si vous ne l'accordez pas au bon compte principal, vous risquez de rencontrer des erreurs d'autorisation.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation aiplatform.endpoints.predict, qui est nécessaire pour permettre à l'interface de ligne de commande OpenCode de s'exécuter dans une instance Agent Platform Workbench.

Il est possible que votre administrateur puisse également attribuer cette autorisation au compte de service de votre instance Agent Platform Workbench avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer la CLI OpenCode

La CLI OpenCode n'est disponible que sur les instances Agent Platform Workbench qui utilisent l'image Debian 12 (workbench-instances-2603). Il n'est pas installé sur les instances qui utilisent l'image Debian 11 (workbench-instances).

L'interface de ligne de commande OpenCode est activée par défaut sur les instances compatibles. Pour le désactiver, définissez la clé de métadonnées d'instance enable-opencode sur false. Pour en savoir plus, consultez Gérer les fonctionnalités à l'aide des métadonnées.

Utiliser la CLI OpenCode

1. Dans la console Google Cloud , accédez à la page Instances.

   Accéder à la page "Instances"

2. À côté du nom d'une instance Agent Platform Workbench, cliquez sur Ouvrir JupyterLab.

3. Dans JupyterLab, cliquez sur Fichier > Nouveau lanceur d'applications.

4. Dans l'onglet Lanceur d'applications, dans la section Autre, cliquez sur la tuile OpenCode.

   Un terminal s'ouvre et démarre l'interface de ligne de commande OpenCode.

5. Saisissez une requête, par exemple "Crée un notebook nommé 'test-notebook'".

6. Lorsque OpenCode propose une action, comme modifier un fichier ou exécuter une commande shell, examinez-la, puis approuvez-la ou refusez-la. Pour en savoir plus, consultez Approuver les actions de l'outil.

Approuver les actions d'outils

Par défaut, OpenCode dans Agent Platform Workbench vous demande votre approbation avant d'effectuer une action, comme modifier un fichier, exécuter une commande shell ou récupérer une URL. Examinez chaque action proposée avant de l'approuver.

Cette valeur par défaut protège contre l'injection de prompt. Un notebook, un script ou une page Web lus par OpenCode peuvent contenir des instructions cachées qui tentent de faire exécuter à l'agent des commandes que vous n'aviez pas prévues, comme l'envoi de vos données à une adresse externe. Étant donné qu'OpenCode s'exécute avec les identifiants de votre instance, l'approbation requise vous permet de voir et d'arrêter une telle action avant son exécution.

Attention : Vous pouvez modifier ce comportement dans votre propre configuration OpenCode, y compris en désactivant complètement les invites d'approbation. Si vous le faites, OpenCode exécute les actions sans vous demander votre avis au préalable, et vous acceptez le risque d'injection de prompt et d'exfiltration de données pour vos charges de travail.

Utiliser des modèles tiers

Par défaut, OpenCode dans Agent Platform Workbench est configuré pour n'utiliser que les modèles Gemini et Claude fournis par Gemini Enterprise Agent Platform dans votre projet. Ces requêtes sont authentifiées avec les identifiants de votre instance par rapport à la plate-forme Gemini Enterprise Agent de votre projet. Elles restent donc dans votre projetGoogle Cloud et sont soumises aux contrôles de sécurité qui s'y appliquent.

OpenCode est également compatible avec les fournisseurs de modèles dont les requêtes sont envoyées en dehors de votre projet. Il s'agit notamment de Google AI Studio (l'API Gemini Developer), qui, bien qu'il propose des modèles Gemini, est un service distinct qui s'authentifie avec une clé API personnelle plutôt qu'avec les identifiants de votre projet, ainsi que des fournisseurs non Google tels que les API directes d'OpenAI et d'Anthropic. Toutes ces options sont désactivées par défaut. Pour en activer un, modifiez votre propre configuration OpenCode et fournissez la clé API du fournisseur.

Avertissement : Si vous activez l'un de ces fournisseurs, vos requêtes (et toutes les données qu'elles contiennent, y compris les données lues à partir de vos notebooks et fichiers) sont envoyées à l'API externe de ce fournisseur. Ces données quittent les limites de votre projet Google Cloud . Il n'est plus protégé par les contrôles de sécurité qui s'appliquent à votre projet, y compris la protection Model Armor contre l'injection de prompt, si vous l'avez configurée. L'activation d'un tel fournisseur relève de votre décision et de votre responsabilité, y compris en ce qui concerne le respect de tout accord de traitement des données que vous avez conclu avec ce fournisseur.

Contrôler l'accès à l'interface de ligne de commande OpenCode

L'accès à OpenCode est régi par deux contrôles indépendants : l'affichage du lanceur OpenCode et la possibilité d'appeler les modèles sous-jacents. Ces deux éléments sont distincts : masquer le lanceur d'applications ne bloque pas les modèles, et restreindre les modèles ne supprime pas le lanceur d'applications. Configurez donc les deux pour qu'ils correspondent aux règles de votre organisation.

Contrôler l'affichage du lanceur OpenCode

Pour contrôler si OpenCode est proposé sur une instance, utilisez la clé de métadonnées d'instance enable-opencode. OpenCode est activé par défaut : la tuile OpenCode s'affiche dans le lanceur JupyterLab, sauf si un administrateur définit la clé sur false, ce qui la masque.

Ce paramètre ne contrôle que l'affichage ou non du lanceur. En soi, il ne bloque pas l'accès aux modèles : un utilisateur qui peut accéder à l'environnement de l'instance (par exemple, via un terminal) peut toujours démarrer OpenCode et appeler tous les modèles que ses identifiants sont autorisés à utiliser. Pour limiter les actions qu'OpenCode peut effectuer, contrôlez l'accès aux modèles comme décrit dans la section suivante.

Contrôler l'accès aux modèles

OpenCode appelle les modèles via Gemini Enterprise Agent Platform à l'aide des identifiants de votre instance, soit la même authentification Gemini Enterprise Agent Platform que celle utilisée par l'CLI Gemini. Les utilisateurs n'ont pas besoin de saisir de clé API pour utiliser les modèles Gemini et Claude par défaut. Une requête n'aboutit que si l'identité de l'instance est autorisée à appeler le modèle et si le projet y a accès. Cette option détermine si OpenCode peut générer des réponses, et elle s'applique quelle que soit la façon dont OpenCode est démarré.

Pour gérer l'accès aux modèles, utilisez les mêmes contrôles que ceux qui s'appliquent à n'importe quel client Gemini Enterprise Agent Platform :

• Pour autoriser ou limiter l'accès à des modèles spécifiques au niveau d'une organisation, d'un dossier ou d'un projet, configurez une règle d'administration. Consultez Contrôler l'accès aux modèles Model Garden.

• Pour empêcher une identité d'utiliser des points de terminaison de modèle pour l'inférence, ne lui accordez pas l'autorisation aiplatform.endpoints.predict.

• Les modèles de fournisseurs externes à votre projet (par exemple, l'API directe d'Anthropic) exigent que l'utilisateur fournisse la clé API de ce fournisseur dans sa propre configuration OpenCode et sont désactivés par défaut. Pour en savoir plus, consultez Utiliser des modèles tiers.

Étapes suivantes

• En savoir plus sur Gemini Enterprise Agent Platform

• Pour savoir comment définir des métadonnées d'instance, consultez Gérer les fonctionnalités à l'aide des métadonnées.