Usar a CLI OpenCode

Usar a CLI OpenCode

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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 do Agent Platform. Este documento pressupõe que você sabe 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 OpenCode fica disponível em um terminal na interface do JupyterLab da instância do Workbench do Agent Platform. Você pode usá-lo para trabalhar com os notebooks e arquivos em sua instância e para executar comandos de shell, fornecendo instruções em linguagem natural.

Limitações

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

• O OpenCode é 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 edições feitas pelo OpenCode usando o botão Desfazer do editor de notebook 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 mudar um arquivo que você também abriu no JupyterLab. Se você tiver mudanças não salvas em um notebook, salve-as antes de pedir ao OpenCode para modificar o 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, para que o OpenCode possa 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 usará as permissões dessa identidade.

Antes de começar

Como uma tecnologia em estágio inicial, os produtos do Gemini para Google Cloudpodem gerar uma saída plausível, mas que é factualmente incorreta. Recomendamos que você valide todas as saídas dos produtos do Gemini para Google Cloud antes de usá-las. Para mais informações, consulte Gemini para Google Cloud e IA responsável.

1. 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

2. Verify that billing is enabled for your Google Cloud 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 OpenCode no Agent Platform Workbench, conceda permissões ao usuário da instância do Agent Platform Workbench e à conta de serviço da instância.

Observação: o OpenCode opera estritamente dentro das permissões do ambiente da sua instância do Agent Platform Workbench. Se você (ou a conta de serviço usada pela sua instância) não tiver permissão para acessar um recurso específico, o OpenCode também não terá. Se um comando falhar devido a permissões, peça ao administrador para conceder as permissões necessárias.

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

Para receber as permissões necessárias para usar a CLI OpenCode em uma instância do Agent Platform Workbench, peça ao administrador para conceder a você o papel do IAM de Usuário da Agent Platform (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 sua 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 OpenCode seja executada em uma instância do Agent Platform Workbench, peça ao administrador para conceder o papel do IAM de usuário da plataforma de agentes (roles/aiplatform.user) à conta de serviço da instância do Agent Platform Workbench no projeto.

Importante:conceda esse papel à conta de serviço da sua instância do Agent Platform Workbench, não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.

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 OpenCode seja executada em uma instância do Agent Platform Workbench.

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 OpenCode

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

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

Usar a CLI OpenCode

1. No console do Google Cloud , 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 OpenCode.

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

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

Aprovar ações da ferramenta

Por padrão, o OpenCode no Workbench da Agent Platform 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 aprovar.

Esse padrão protege contra injeção de comando. Um notebook, script ou página da Web que o OpenCode lê 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 dá a você a oportunidade de ver e interromper essa ação antes da execução.

Atenção: é possível mudar esse comportamento na sua própria configuração do OpenCode, incluindo a desativação completa dos avisos de aprovação. Se você fizer isso, o OpenCode vai executar ações sem perguntar primeiro, e você aceita o risco resultante de injeção de comandos e exfiltração de dados para suas cargas de trabalho.

Usar modelos de terceiros

Por padrão, o OpenCode no Agent Platform Workbench é configurado para usar apenas os modelos do Gemini e do Claude veiculados pela Gemini Enterprise Agent Platform no seu projeto. Essas solicitações são autenticadas com as credenciais da sua instância na própria Gemini Enterprise Agent Platform do projeto. Assim, elas permanecem noGoogle Cloud projeto e estão sujeitas aos controles de segurança aplicáveis.

O OpenCode também oferece suporte a provedores de modelos cujas solicitações são enviadas fora do seu projeto. Isso inclui o Google AI Studio (a API Gemini para desenvolvedores), que, apesar de oferecer modelos do Gemini, é um serviço separado que autentica com uma chave de API pessoal em vez das credenciais do seu 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.

Atenção: se você ativar um desses provedores, seus comandos e todos os dados contidos neles, incluindo dados lidos dos seus notebooks e arquivos, serão enviados para a API externa desse provedor. Esses dados saem dos limites do seu projeto Google Cloud . Ele não será mais protegido pelos controles de segurança aplicados no seu projeto, incluindo a proteção do Model Armor contra injeção de comando, se você tiver configurado esse recurso. Ativar um provedor é sua decisão e responsabilidade, incluindo a conformidade com qualquer contrato de tratamento de dados que você tenha com esse provedor.

Controlar o acesso à CLI OpenCode

O acesso ao OpenCode é regido por dois controles independentes: se o iniciador do OpenCode é mostrado e se os modelos subjacentes podem ser chamados. Elas são separadas: ocultar o iniciador não bloqueia os modelos, e restringir os modelos não remove o iniciador. Portanto, configure os dois para corresponder à política da sua organização.

Controlar se o iniciador do OpenCode aparece

Para controlar se o OpenCode é oferecido em uma instância, use a chave de metadados da 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 iniciador é apresentado. Por si só, 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 possam 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, a mesma autenticação da Gemini Enterprise Agent Platform usada pela CLI do Gemini. Os usuários não precisam inserir uma chave de API para usar os modelos padrão do Gemini e do Claude. Uma solicitação só será 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 independente de como o OpenCode é iniciado.

Para gerenciar o acesso ao modelo, use os mesmos controles aplicados 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 são desativados por padrão. Para mais informações, consulte Usar modelos de terceiros.

A seguir

• Saiba mais sobre a Gemini Enterprise Agent Platform.

• Para saber como definir metadados da instância, consulte Gerenciar recursos usando metadados.