Pular para o conteúdo principal

Genie Code CLI

A CLI do Genie Code é um agente de codificação executado localmente no seu terminal e otimizado para trabalho com dados e AI no Databricks. Ele funciona como outros agentes de codificação de terminal, mas vem pré-configurado para entender o Databricks e trabalhar naturalmente com seus dados, pipelines, modelos e aplicativos.

Como sua execução ocorre em sua máquina, a CLI do Genie Code pode ler e editar seus arquivos locais, realizar a execução de comandos e acessar o Databricks em seu nome. Ele usa a CLI do Databricks, incluindo os databricks genie comandos como databricks genie ask, para descobrir dados e responder a perguntas. A CLI do Genie Code usa modelos fornecidos pelo Databricks, para que você não precise trazer sua própria inscrição de modelo. Você gerencia o acesso e os orçamentos da mesma forma que o Genie Code. Consulte Faturamento e orçamentos.

Requisitos​

A execução do Genie Code CLI ocorre sob sua própria identidade, de modo que ele só pode acessar dados e realizar operações que suas permissões do Databricks permitam.

Instalar e configurar​

  1. Instale o Databricks CLI (versão 1.0.0 ou acima) separadamente, caso ainda não o tenha feito. Consulte Install or update the Databricks CLI.

  2. Instale a CLI do Genie Code com o comando para o seu sistema operacional.

Bash
curl -fsSL https://github.com/databricks/genie-code-cli/releases/latest/download/install.sh | bash
  1. Confirme a instalação:

    Bash
    genie --version
  2. Entre no diretório do seu projeto e comece a CLI do Genie Code:

    Bash
    cd my-project
    genie
  3. Quando solicitado, selecione um perfil da CLI do Databricks ou autentique-se caso ainda não tenha configurado um. Consulte Autenticação para a CLI do Databricks. A CLI do Genie Code usa este perfil para acesso ao modelo e faturamento. Ela ainda pode usar outros perfis da CLI do Databricks para trabalhar com outros Workspace ou trabalhar totalmente fora do Databricks.

  4. Confirme que você confia no conteúdo do diretório e, em seguida, comece a criar prompts.

O que você pode fazer com a CLI do Genie Code​

Genie Code CLI can work directly with local files, discover and query your Unity Catalog data through Genie, and build and implantado Databricks ativos from a single conversation in the terminal. Por exemplo:

  • Ingerir e governar : "Limpe estes CSVs de ventas mensais, carregue-os no Unity Catalog e mostre-me a receita por região ao longo do tempo."
  • Explore seus dados : "Qual dos meus catálogos tem dados de rotatividade de clientes e quais foram os principais drivers do último trimestre?"
  • Estender um pipeline : "Adicionar uma tabela silver refunds ao meu pipeline de pedidos e preencher os últimos 90 dias."
  • Ensinar e servir um modelo : "Faça a execução deste script de treinamento no Databricks e coloque o modelo atrás de um Endpoint de serviço."
  • Criar e entregar um aplicativo : "Criar um protótipo de aplicativo local para minha tabela customers e implantá-lo como um Databricks App."

Como a CLI do Genie Code difere do Genie Code no workspace​

Genie Code CLI é uma experiência separada criada para o trabalho local baseado em terminal. Ele tem suas próprias ferramentas, habilidades e instruções e, no momento, não as compartilha com o Genie Code no workspace do Databricks. Ele também ainda não inclui todos os recursos disponíveis na IU do workspace.

Use a CLI do Genie Code como um componente nativo de terminal ao trabalhar localmente com arquivos, scripts e protótipos. Continue a usar o Genie Code no workspace para obter uma experiência mais rica e completa.

Configurar habilidades e servidores MCP​

Você pode estender a CLI do Genie Code com habilidades, servidores MCP e instruções de projeto. Se você já usa o Claude Code ou o Cursor, faça a execução de /import na CLI do Genie Code para importar sua configuração deles.

Adicionar habilidades​

O Genie Code CLI já vem instalado com habilidades de agente do Databricks para que o agente funcione de forma mais eficaz com dados e recursos do Databricks, como jobs, pipelines, modelos e aplicativos. Essas habilidades estão em ~/.genie/skills/.system/.

Para adicionar sua própria habilidade, crie uma pasta que contenha um arquivo SKILL.md no formato de Habilidades do Agente padrão e salve-a em ~/.genie/skills/. Para compartilhar uma habilidade com sua equipe, salve-a em .agents/skills/ no seu repository. A CLI do Genie Code também carrega habilidades de outras pastas locais, como pastas pai do seu diretório de trabalho e a raiz do seu repository.

Você também pode pedir à CLI do Genie Code para criar uma habilidade ou converter uma habilidade existente de outro agente de codificação.

A CLI do Genie Code carrega habilidades apenas de pastas locais. Para usar uma habilidade do seu workspace do Databricks, como uma habilidade em .assistant/skills/, faça download dela para uma destas pastas.

Conectar servidores MCP​

Use genie mcp add para conectar a CLI do Genie Code a qualquer servidor MCP, incluindo servidores MCP que não estejam hospedados no Databricks.

Para se conectar a um servidor MCP remoto, passe o URL dele e o nome de uma variável de ambiente que contenha um access token para ele:

Bash
genie mcp add <server-name> --url <server-url> --bearer-token-env-var <env-var-name>

Para conectar um servidor MCP executado na sua máquina, passe o comando que o começa:

Bash
genie mcp add <server-name> -- <command> <args>

Para conectar um servidor MCP gerenciado no Databricks, como o servidor MCP Genie One:

  1. Armazene um access token do Databricks em uma variável de ambiente:

    Bash
    export DATABRICKS_MCP_TOKEN=$(databricks auth token --profile <profile-name> | jq -r .access_token)
  2. Adicione o servidor MCP e passe o nome da variável de ambiente. Se a URL do seu workspace incluir um ID de workspace, como ?o=<workspace-id>, adicione-o ao final da URL do servidor MCP.

    Bash
    genie mcp add genie_one \
    --url "https://<workspace-host>/ai-gateway/mcp-services/system.ai.genie_one_mcp" \
    --bearer-token-env-var DATABRICKS_MCP_TOKEN
  3. No mesmo terminal, comece a CLI do Genie Code:

    Bash
    genie
  4. Execução /mcp para confirmar que o servidor está conectado.

Adicionar instruções do projeto​

Para dar instruções à CLI do Genie Code que se aplicam a todas as conversas em um projeto, como convenções de codificação, nomes de catálogo e esquema ou como execução testes, adicione um arquivo AGENTS.md à raiz do diretório do projeto. A CLI do Genie Code lê esse arquivo quando você a começa nesse diretório.

Disponibilidade regional​

O Genie Code CLI é um Serviço Designado. Sua disponibilidade depende da região do seu workspace e da configuração Impor o processamento de dados na área geográfica do workspace para Serviços Designados . O processamento cross-Geo é habilitado por default para workspaces fora dos EUA e da UE que não estão com o perfil de segurança de compliance habilitado. Se o processamento cross-Geo estiver desabilitado, o Genie Code CLI poderá não estar disponível em seu workspace. Para disponibilidade em cada Geo, consulte Disponibilidade de Serviços Designados em cada Geo.

A CLI do Genie Code não está disponível em regiões onde o faturamento pay-as-you-go do Genie não está disponível: Azure West Central US e Qatar Central, AWS Asia Pacific (Jakarta) e regiões governamentais.

Pesquisa na Web​

A pesquisa na web tem requisitos adicionais:

  • A pesquisa na Web tem os mesmos requisitos que a pesquisa na Web no Genie Code, incluindo a prévia de Pesquisa na Web no Genie Code e Genie One .
  • Ao contrário da pesquisa na Web no Genie Code, a pesquisa na Web no Genie Code CLI não está disponível em Workspace com o perfil de segurança compliance.

Quando a pesquisa na web não estiver disponível, a CLI do Genie Code ainda pode acessar a internet executando comandos shell como curl.

Faturamento e orçamentos​

A CLI do Genie Code é faturada da mesma forma que o Genie Code, usando o preço pay-as-you-go do Genie. Ela compartilha o uso mensal gratuito que cada usuário recebe para produtos Genie. O uso da CLI do Genie Code é rastreado através do Unity Gateway.

Os orçamentos e controles de custos para o Genie Code CLI são gerenciados junto com outros produtos do Genie, e o uso do Genie Code CLI conta para o mesmo orçamento do Genie. Consulte Gerenciar orçamentos e controles de custos para o Genie.

O uso da CLI do Genie Code aparece na tabela de sistema system.billing.usage com usage_metadata.genie.surface definida como GENIE_CODE_CLI. Consulte Monitorar e entender seu custo Genie.

Para obter preços atuais e o valor de uso gratuito, consulte a página de preços do Databricks.

Perguntas frequentes​

Quando devo usar a CLI do Genie Code em vez do Unity Gateway com meu próprio agente de codificação?​

Use outro agente de codificação através da ug CLI, por exemplo, ug claude, se você já tiver configurado esse agente para usar habilidades de agente do Databricks e servidores MCP gerenciados pelo Databricks, como o Genie One.

Use a CLI do Genie Code se você ainda não tiver configurado isso ou se também quiser os ajustes adicionais que a Databricks aplica ao harness do agente para que ele funcione melhor com a Databricks.

Como a CLI do Genie Code é diferente de outros agentes de codificação?​

A CLI do Genie Code funciona como outros agentes de codificação de terminal, com estas diferenças:

  • Pré-configurado para Databricks : Inclui habilidades de Databricks, usa a CLI de Databricks e o Genie para descobrir e fazer query de seus dados, e é ajustado com instruções para trabalho de dados e AI. Você não instala ou configura isso sozinho.
  • Sem inscrição de modelo separada : A CLI do Genie Code usa modelos que o Databricks fornece e o uso é cobrado na sua account do Databricks da mesma forma que o Genie Code.
  • As operações do Workspace são regidas pelo Databricks : as operações em seu workspace do Databricks estão em execução sob sua identidade do Databricks, portanto, as permissões do Unity Catalog se aplicam. As operações locais, como editar arquivos e executar comandos em sua máquina, não são regidas pelo Databricks.

Para usar outro agente de codificação com Databricks, consulte Começar a usar agentes de codificação.

Quais sistemas operacionais são compatíveis com a CLI do Genie Code?​

O Genie Code CLI é compatível com macOS, Linux e Windows. Consulte Instalar e configurar.

Posso usar a CLI do Genie Code em meu IDE?​

Sim. Comece o Genie Code CLI no terminal integrado de qualquer IDE, como Visual Studio Code, Cursor ou IntelliJ IDEA. A CLI do Genie Code funciona com os arquivos no diretório onde você a começa.

Como faço para retomar uma conversa anterior?​

Toda vez que você executa o genie, a CLI do Genie Code começa uma nova conversa. Para retomar uma conversa anterior, use uma das seguintes opções:

  • genie resume: Escolha uma conversa em uma lista.
  • genie resume --last: retome sua conversa mais recente.
  • /resume: Escolha uma conversa de uma lista enquanto a CLI do Genie Code estiver em execução.

Como faço para atualizar a CLI do Genie Code?​

A CLI do Genie Code verifica se há uma nova versão quando começa e solicita que você a atualize. Para atualizar manualmente, execução genie update ou execução novamente o comando de instalação do seu sistema operacional.

Como os administradores governam a CLI do Genie Code?​

O uso da CLI do Genie Code é rastreado pelo Unity Gateway, e os administradores gerenciam seus orçamentos juntamente com outros produtos do Genie. Consulte Gerenciar orçamentos e controles de custo para o Genie.

Limitações​

  • O Genie Code CLI oferece suporte apenas à autenticação OAuth user-to-machine (U2M), usando um perfil da CLI do Databricks criado com databricks auth login. A autenticação OAuth machine-to-machine (M2M) e os access tokens pessoais não são compatíveis.
  • A CLI do Genie Code não é compatível com sessões de túnel SSH. Para usar a CLI do Genie Code, execute-a na sua máquina local.
  • A CLI do Genie Code carrega habilidades apenas de pastas locais. Ele não carrega habilidades ou instruções do seu workspace ou do Unity Catalog.
  • Se você conectar um servidor MCP no Databricks com um access token, as chamadas MCP falharão com um erro 401 após a expiração do token. Para reconectar, saia da CLI do Genie Code, defina a variável de ambiente para um novo token e execute genie.