Usar a CLI do OpenCode

Nesta página, descrevemos como usar a interface de linha de comando (CLI) do OpenCode com uma instância do Gemini Enterprise Agent Platform Workbench.

Este documento é destinado a analistas de dados, cientistas de dados e desenvolvedores de dados que trabalham com o Workbench da plataforma do agente. Este documento pressupõe que você saiba como escrever código em um ambiente de notebook.

Visão geral

O OpenCode é um agente de programação de IA de código aberto que é executado em um terminal. Para mais informações, consulte opencode.ai.

Quando um administrador ativa a CLI do OpenCode, ela fica disponível em um terminal na interface do JupyterLab da instância do Workbench da Plataforma de Agentes. É possível usá-lo para trabalhar com os notebooks e arquivos na instância e executar comandos do shell e do Cloud de Confiance by S3NS , fornecendo instruções em linguagem natural.

Limitações

Considere as seguintes limitações ao usar a CLI do OpenCode com o Agent Platform Workbench:

  • O OpenCode é apenas uma CLI. Uma interface gráfica de chat e ferramentas avançadas no editor não estão incluídas.

  • Quando você pede para o OpenCode modificar um notebook, ele muda o arquivo diretamente no disco da instância. Por isso, não é possível desfazer as edições feitas pelo OpenCode usando o botão Desfazer do editor de notebooks ou Control+Z (Command+Z no macOS). No entanto, é possível pedir ao OpenCode para desfazer uma mudança usando um comando de linguagem natural, como Undo your last change.

  • Como o OpenCode grava diretamente no disco, ele pode alterar um arquivo que você também tem aberto no JupyterLab. Se você tiver alterações não salvas em um notebook, salve-as antes de pedir ao OpenCode para modificar esse mesmo notebook.

  • O OpenCode é executado com as credenciais ativas na sua instância. Por padrão, essas são as credenciais da conta de serviço da instância do Agent Platform Workbench. Assim, o OpenCode pode acessar os mesmos recursos que a instância. Se você autenticar uma identidade diferente na instância (por exemplo, executando gcloud auth login ou gcloud auth application-default login), o OpenCode vai usar as permissões dessa identidade.

Antes de começar

  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

Funções exigidas

Para usar a CLI do OpenCode no Agent Platform Workbench, é necessário conceder permissões ao usuário da instância do Agent Platform Workbench e à conta de serviço da instância.

Conceder permissões ao usuário da instância

Para receber as permissões necessárias para usar a CLI do OpenCode em uma instância do Workbench da plataforma de agentes, peça ao administrador para conceder a você o papel do IAM de usuário da plataforma de agentes (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder uma permissão à conta de serviço da instância

Para garantir que a conta de serviço da instância do Agent Platform Workbench tenha a permissão necessária para permitir que a CLI do OpenCode seja executada em uma instância do Agent Platform Workbench, peça ao administrador para conceder o papel do IAM de usuário do Agent Platform (roles/aiplatform.user) à conta de serviço da instância do Agent Platform Workbench no projeto.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão aiplatform.endpoints.predict, que é necessária para permitir que a CLI do OpenCode seja executada em uma instância do Workbench da plataforma de agentes.

O administrador também pode conceder essa permissão à conta de serviço da instância do Agent Platform Workbench com papéis personalizados ou outros papéis predefinidos.

Ativar a CLI do OpenCode

A CLI do OpenCode está disponível apenas em instâncias do Agent Platform Workbench que usam a imagem do Debian 12 (workbench-instances-2603). Ele não é instalado em instâncias que usam a imagem do Debian 11 (workbench-instances).

A CLI do OpenCode é ativada por padrão em instâncias compatíveis. Para desativá-lo, defina a chave de metadados da instância enable-opencode como false. Para mais informações, consulte Gerenciar recursos usando metadados.

Usar a CLI do OpenCode

  1. No console do Cloud de Confiance , acesse a página Instâncias.

    Acesse "Instâncias"

  2. Ao lado do nome de uma instância do Agent Platform Workbench, clique em Abrir JupyterLab.

  3. No JupyterLab, clique em Arquivo > Nova tela de início.

  4. Na guia Acesso rápido, na seção Outros, clique no bloco OpenCode.

    Um terminal é aberto e inicia a CLI do OpenCode.

  5. Insira um comando, como "Criar um novo notebook chamado 'test-notebook'".

  6. Quando o OpenCode propõe uma ação, como editar um arquivo ou executar um comando do shell, revise e aprove ou rejeite. Para mais informações, consulte Aprovar ações de ferramentas.

Aprovar ações de ferramentas

Por padrão, o OpenCode no Workbench da plataforma de agentes pede sua aprovação antes de realizar qualquer ação, como editar um arquivo, executar um comando do shell ou buscar um URL. Analise cada ação proposta antes de aprová-la.

Esse padrão protege contra injeção de comando. Um notebook, script ou página da Web lido pelo OpenCode pode conter instruções ocultas que tentam fazer com que o agente execute comandos que você não pretendia, como enviar seus dados para um endereço externo. Como o OpenCode é executado com as credenciais da sua instância, exigir aprovação permite que você veja e interrompa essa ação antes que ela seja executada.

Usar modelos de terceiros

Por padrão, o OpenCode no Agent Platform Workbench está configurado para usar apenas os modelos do Gemini e do Claude disponibilizados pela Gemini Enterprise Agent Platform no seu projeto. Essas solicitações são autenticadas com as credenciais da sua instância na Gemini Enterprise Agent Platform do seu projeto. Assim, elas permanecem no seu projetoCloud de Confiance by S3NS e estão sujeitas aos controles de segurança que se aplicam a ele.

O OpenCode também é compatível com provedores de modelos que enviam solicitações para fora do seu projeto. Isso inclui o Google AI Studio (a API Gemini Developer), que, apesar de oferecer modelos do Gemini, é um serviço separado que faz a autenticação com uma chave de API pessoal em vez das credenciais do projeto, além de provedores que não são do Google, como as APIs diretas da OpenAI e da Anthropic. Todas essas opções ficam desativadas por padrão. Para ativar um, edite sua própria configuração do OpenCode e forneça a chave de API do provedor.

Controlar o acesso à CLI do OpenCode

O acesso ao OpenCode é regido por dois controles independentes: se o inicializador do OpenCode é mostrado e se os modelos subjacentes podem ser chamados. Essas ações são separadas: ocultar o acesso não bloqueia os modelos, e restringir os modelos não remove o acesso. Portanto, configure as duas opções de acordo com a política da sua organização.

Controlar se o inicializador do OpenCode aparece

Para controlar se o OpenCode é oferecido em uma instância, use a chave de metadados de instância enable-opencode. O OpenCode fica ativado por padrão: o bloco do OpenCode aparece no acesso rápido do JupyterLab, a menos que um administrador defina a chave como false, o que o oculta.

Essa configuração controla apenas se o inicializador é apresentado. Ele não bloqueia o acesso aos modelos: um usuário que pode acessar o ambiente da instância (por exemplo, por um terminal) ainda pode iniciar o OpenCode e chamar qualquer modelo que as credenciais dele permitam usar. Para restringir o que o OpenCode pode fazer, controle o acesso aos modelos conforme descrito na próxima seção.

Controlar o acesso aos modelos

O OpenCode chama modelos pela Gemini Enterprise Agent Platform usando as credenciais da sua instância, que é a mesma autenticação da Gemini Enterprise Agent Platform usada pela CLI do Gemini. Os usuários não inserem uma chave de API para usar os modelos padrão do Gemini e do Claude. Uma solicitação só é bem-sucedida se a identidade da instância tiver permissão para chamar o modelo e o projeto tiver acesso a ele. Esse controle determina se o OpenCode pode gerar respostas e se aplica independentemente de como o OpenCode é iniciado.

Para gerenciar o acesso ao modelo, use os mesmos controles que se aplicam a qualquer cliente da Gemini Enterprise Agent Platform:

  • Para permitir ou restringir modelos específicos no nível da organização, da pasta ou do projeto, configure uma política da organização. Consulte Controlar o acesso aos modelos do Model Garden.

  • Para impedir que uma identidade use endpoints de modelo para inferência, não conceda a ela a permissão aiplatform.endpoints.predict.

  • Os modelos de provedores fora do seu projeto (por exemplo, a API direta da Anthropic) exigem que o usuário forneça a chave de API desse provedor na própria configuração do OpenCode e estão desativados por padrão. Para mais informações, consulte Usar modelos de terceiros.

A seguir