Conectar Gemini

Use a CLI Gemini com modelos, ferramentas MCP e habilidades através do Unity Gateway. A CLI do Gateway Unity (ug) gerencia o login e configuração do workspace, ou você pode configurar a conexão manualmente.

Apenas a CLI Gemini é suportada pelo Unity Gateway.

Antes de começar

Você precisa da URL do seu espaço de trabalho do Azure Databricks e acesso aos modelos, serviços MCP e habilidades que deseja usar. Para configuração manual, instale uma versão da CLI Gemini compatível com a integração atual do Unity Gateway e tenha um token de acesso pessoal do Azure Databricks.

Para configuração manual, substitua <workspace-hostname> pelo nome de host do seu workspace Azure Databricks e <databricks-pat> pelo seu token. Use os nomes completos dos modelos disponíveis no seu espaço de trabalho e mescle as entradas de configuração aos arquivos existentes, preservando as configurações não relacionadas.

Se seu administrador já configurou seu dispositivo, siga as instruções de configuração da sua organização.

Use o CLI do Unity Gateway

Instale ug, então execute este comando a partir do diretório do seu projeto:

ug gemini

Selecione seu espaço de trabalho e faça login quando solicitado. O comando abre a CLI Gemini com um modelo configurado, pronto para seu fluxo de trabalho habitual de codificação.

Para começar com um modelo diferente, use ug gemini --model "<model-name>". Para usar um Serviço de Provedor de Modelo Gemini configurado pelo seu administrador, use ug gemini --provider "<catalog>.<schema>.<provider-name>".

Configure os modelos manualmente

Instale uma versão da CLI Gemini compatível com a integração atual do Unity Gateway:

npm install -g "@google/gemini-cli@<0.45.0"

Defina estas variáveis no seu terminal:

export GEMINI_MODEL="system.ai.gemini-2-5-flash"
export GOOGLE_GEMINI_BASE_URL="https://<workspace-hostname>/ai-gateway/gemini"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"
export GEMINI_API_KEY="<databricks-pat>"

Mescle o seguinte em ~/.gemini/settings.json para selecionar a autenticação com chave de API:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Depois, execute gemini no mesmo terminal. Veja a documentação de configuração do Gemini CLI para suas configurações e variáveis de ambiente.

Adicionar ferramentas MCP

Use o CLI do Unity Gateway

Execute:

ug mcp add --agents gemini

Selecione seus serviços e reinicie com ug gemini. Entre /mcp dentro do agente para ver os servidores conectados.

Configure os serviços MCP manualmente

Misture esta entrada em ~/.gemini/settings.json:

{
  "mcpServers": {
    "dbsql": {
      "httpUrl": "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql",
      "headers": {
        "Authorization": "Bearer <databricks-pat>"
      }
    }
  }
}

Para outro serviço, mude o nome do servidor e substitua system.ai.dbsql pelo nome do Catálogo Unity em três partes. Reinicie gemini após a edição. Veja a documentação MCP da CLI Gemini.

ug gemini usa um arquivo de configurações separado em ~/.ucode/.gemini-home/.gemini/settings.json. Use esse arquivo para entradas manuais de MCP ao iniciar por meio de ug.

Adicionar habilidades

Use o CLI do Unity Gateway

Do seu diretório de projetos, baixe as habilidades publicadas para o projeto:

ug skills add --path "$PWD"

Escolha suas habilidades e reinicie a CLI do Gemini. Ele lê o diretório .agents/skills/ do projeto. Entre /skills list para ver as habilidades disponíveis.

Configurar habilidades manualmente

Para os arquivos que você já possui, coloque cada pasta completa de habilidade na pasta .gemini/skills/ do seu projeto. As habilidades do projeto funcionam com gemini e ug gemini; ug usa um diretório inicial separado para configurações e habilidades do usuário. Veja a documentação de habilidades do Gemini CLI.

Para acessar o registro de habilidades publicado via MCP, adicione um segundo servidor usando o exemplo MCP acima, nomeie-o databricks-skill-registry, e defina httpUrl para https://<workspace-hostname>/ai-gateway/skills/. Mantenha a barra de retaguarda e a cabeça do portador. Peça ao agente para usar uma habilidade usando seu nome completo.

As habilidades do Gateway Unity estão em Beta. Veja Habilidades de Governar para habilitação e permissões.

Solução de problemas

Uma solicitação de modelo falha: Verifique a URL do gateway, expiração do token, nome do modelo, permissões e a restrição da versão da CLI Gemini acima.

Um servidor MCP está faltando: Reinicie o agente. Se você o configurou com ug, inicie-o com ug gemini para que ele use as mesmas configurações. Para configuração manual, verifique ~/.gemini/settings.json e coloque a ficha de portador.

Uma habilidade baixada está faltando: Verifique se a pasta completa dela contém SKILL.md em um diretório compatível. Ao iniciar por meio de ug, use o comando de download do projeto acima. Execute novamente ug skills add com as mesmas opções para atualizar as habilidades baixadas.

Para problemas de login no workspace ou configuração de ug, execute ug doctor.

Próximas Etapas 

  • Last updated on