Connetti Gemini

Usa la CLI Gemini con modelli, strumenti MCP e competenze tramite Unity Gateway. La CLI Unity Gateway (ug) gestisce l'accesso e la configurazione dello spazio di lavoro, oppure puoi configurare la connessione manualmente.

Solo la CLI Gemini è supportata tramite Unity Gateway.

Prerequisites

Hai bisogno dell'URL dello spazio di lavoro di Azure Databricks e dell'accesso ai modelli, ai servizi MCP e alle competenze che vuoi utilizzare. Per la configurazione manuale, installa una versione della CLI Gemini compatibile con l'attuale integrazione di Unity Gateway e hai un token di accesso personale Azure Databricks.

Per la configurazione manuale, sostituisci <workspace-hostname> con il nome host dello spazio di lavoro Azure Databricks e <databricks-pat> con il token. Usa i nomi completi dei modelli disponibili nel tuo workspace e unisci le voci di configurazione ai file esistenti, mantenendo impostazioni non correlate.

Se il tuo amministratore ha già configurato il tuo dispositivo, segui le istruzioni di configurazione della tua organizzazione.

Utilizzare l'interfaccia a riga di comando di Unity Gateway

Installa ug, poi esegui questo comando dalla cartella del progetto:

ug gemini

Seleziona il tuo spazio di lavoro e accedi quando ti viene chiesto. Il comando apre la CLI Gemini con un modello configurato, pronto per il tuo solito flusso di lavoro di codifica.

Per iniziare con un modello diverso, usa ug gemini --model "<model-name>". Per utilizzare un servizio Gemini Model Provider configurato dal tuo amministratore, usa ug gemini --provider "<catalog>.<schema>.<provider-name>".

Configurare i modelli manualmente

Installa una versione della CLI Gemini compatibile con l'attuale integrazione di Unity Gateway:

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

Imposta queste variabili nel tuo terminale:

export GEMINI_MODEL="system.ai.gemini-3-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>"

Unisci i seguenti elementi in ~/.gemini/settings.json per selezionare l'autenticazione tramite chiave API:

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

Poi corri gemini dallo stesso terminale. Consulta la documentazione di configurazione di Gemini CLI per le sue impostazioni e le variabili ambientali.

Aggiungi strumenti MCP

Per utilizzare system.ai.dbsql, system.ai.sandbox, o system.ai.web_search, un amministratore dell'account deve abilitare la beta Unity Gateway dalla pagina delle anteprime della console account. Vedi Gestisci anteprime dell'account.

Utilizzare l'interfaccia a riga di comando di Unity Gateway

Corri!

ug mcp add --agents gemini

Seleziona i tuoi servizi, poi riavvia con ug gemini. Entra /mcp all'interno dell'agente per vedere i server connessi.

Configura manualmente i servizi MCP

Unisci questa voce in ~/.gemini/settings.json:

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

Per un altro servizio, cambia il nome del server e sostituisci system.ai.dbsql con il nome Unity Catalog in tre parti. Riavvia gemini dopo la modifica. Consulta la documentazione MCP di Gemini CLI.

ug gemini usa un file di impostazioni separato a ~/.ucode/.gemini-home/.gemini/settings.json. Usa quel file per gli inserimenti manuali di MCP quando avvii MCP tramite ug.

Aggiungere competenze

Utilizzare l'interfaccia a riga di comando di Unity Gateway

Dalla directory del progetto, scarica le competenze pubblicate nel progetto:

ug skills add --path "$PWD"

Scegli le tue abilità, poi riavvia la CLI di Gemini. Legge la directory del .agents/skills/ progetto. Inserisci /skills list per vedere le competenze disponibili.

Configura manualmente le competenze

Per i file che già possiedi, inserisci ogni cartella di skill completa nel file del .gemini/skills/tuo progetto. Le competenze di Project funzionano sia con gemini sia con ug gemini; ug utilizza una directory home separata per le impostazioni utente e le competenze. Consulta la documentazione sulle competenze di Gemini CLI.

Per accedere al registro delle abilità pubblicato tramite MCP, aggiungi un secondo server usando l'esempio MCP sopra, chiamalo databricks-skill-registry, e imposta httpUrl .https://<workspace-hostname>/ai-gateway/skills/ Tieni la barra posteriore e la testa del portaporte. Chiedi all'agente di usare un'abilità con il nome completo.

Le abilità Unity Gateway sono in Beta. Vedi Competenze di Governo per abilitazione e permessi.

Troubleshooting

Una richiesta modello fallisce: Controlla l'URL del gateway, la scadenza del token, il nome del modello, i permessi e la restrizione della versione della CLI Gemini sopra.

Manca un server MCP: Riavvia l'agente. Se l'hai configurato con ug, avvialo con ug gemini in modo che utilizzi le stesse impostazioni. Per la configurazione manuale, controlla ~/.gemini/settings.json e il bearer token.

Manca una skill scaricata: Verifica che la relativa cartella completa contenga SKILL.md in una directory supportata. Quando avvii tramite ug, usa il comando di download del progetto riportato sopra. Rigioca ug skills add con le stesse opzioni per aggiornare le abilità scaricate.

Per problemi di login o ug configurazione dello spazio di lavoro, esegui ug doctor.

Passaggi successivi

  • Ultimo aggiornamento: