Utiliser la CLI OpenCode

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 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 des commandes Cloud de Confiance by S3NS , en donnant des instructions en langage naturel.

Limites

Tenez compte des limites suivantes lorsque vous utilisez la CLI 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 notebook ou de 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.

  • Comme OpenCode écrit directement sur le disque, il peut modifier un fichier que vous avez également ouvert dans JupyterLab. Si vous avez des modifications non enregistrées dans un notebook, 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é.

Avant de commencer

  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

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.

Accorder des autorisations à l'utilisateur de l'instance

Pour obtenir les autorisations nécessaires pour utiliser la CLI 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 à la CLI OpenCode de s'exécuter dans une instance Agent Platform Workbench, demandez à votre administrateur d'accorder le rôle IAM Utilisateur Agent Platform (roles/aiplatform.user) au compte de service de votre instance Agent Platform Workbench 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.

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

Votre administrateur peut é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).

La CLI OpenCode est activée par défaut sur les instances compatibles. Pour la désactiver, définissez la clé de métadonnées d'instance enable-opencode sur false. Pour en savoir plus, consultez Gérer les caractéristiques via les métadonnées.

Utiliser la CLI OpenCode

  1. Dans la console Cloud de Confiance , 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 File > New launcher (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 la CLI OpenCode.

  5. Saisissez une requête, par exemple "Créer 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 des outils.

Approuver les actions associées à l'outil

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'exigence d'approbation vous permet de voir et d'arrêter une telle action avant qu'elle ne s'exécute.

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 diffusés via Gemini Enterprise Agent Platform dans votre projet. Ces requêtes sont authentifiées avec les identifiants de votre instance auprès de la plate-forme Gemini Enterprise Agent Platform de votre projet. Elles restent donc dans votre projetCloud de Confiance by S3NS 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 de fournisseurs non Google tels que les API directes d'OpenAI et d'Anthropic. Toutes ces options sont désactivées par défaut. Vous pouvez en activer un en modifiant votre propre configuration OpenCode et en fournissant la clé API du fournisseur.

Contrôler l'accès à la CLI OpenCode

L'accès à OpenCode est régi par deux commandes indépendantes : l'affichage du lanceur OpenCode et la possibilité d'appeler les modèles sous-jacents. Ces deux actions sont distinctes : masquer le lanceur d'applications ne bloque pas les modèles, et limiter les modèles ne supprime pas le lanceur d'applications. Configurez donc les deux en fonction des règles de votre organisation.

Déterminer si le lanceur OpenCode s'affiche

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 apparaît dans le lanceur JupyterLab, sauf si un administrateur définit la clé sur false, ce qui la masque.

Ce paramètre détermine uniquement si le lanceur d'applications est présenté. Il ne bloque pas l'accès aux modèles par lui-même : 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 lui permettent d'utiliser. Pour limiter les actions d'OpenCode, 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 des modèles via Gemini Enterprise Agent Platform à l'aide des identifiants de votre instance, c'est-à-dire la même authentification Gemini Enterprise Agent Platform que celle utilisée par la 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 ne réussit que si l'identité de l'instance est autorisée à appeler le modèle et que le projet y a accès. Cette commande détermine si OpenCode peut générer des réponses et s'applique quelle que soit la manière dont OpenCode est démarré.

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

  • Pour autoriser ou restreindre 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 extérieurs à votre projet (par exemple, l'API directe d'Anthropic) nécessitent que l'utilisateur fournisse la clé API de ce fournisseur dans sa propre configuration OpenCode. Ils sont désactivés par défaut. Pour en savoir plus, consultez Utiliser des modèles tiers.

Étapes suivantes