Tutoriel : découvrir et utiliser les compétences Unity Gateway
Bêta
Cette fonctionnalité est en Bêta. Pour l'utiliser, un administrateur de workspace doit activer Unity Gateway skills in Genie à partir de la page Previews . Consultez Gérer les aperçus Databricks.
Connectez votre agent de codage aux compétences que votre équipe a publiées dans Unity Catalog, puis découvrez-les et utilisez-les depuis n'importe quelle session d'agent. Tout le monde pointe vers les mêmes schémas régis, vous réutilisez donc ce qui existe au lieu de le reconstruire. Pour créer et publier vos propres compétences, voir Créer et partager des compétences Unity Gateway.
Vous pouvez utiliser une compétence pour une session, la download sur le disque pour chaque session ou la charger en direct depuis le serveur MCP Databricks Skills pour obtenir la dernière version publiée.
Exigences
- Un workspace Databricks compatible avec Unity Catalog, et votre URL de workspace (par exemple,
https://my-company.cloud.databricks.com). - Python 3.12+ et uv sur votre machine (utilisés pour installer la CLI Unity Gateway).
- Un agent de codage compatible MCP (MCP, le Model Context Protocol, est le standard ouvert utilisé par les agents pour se connecter aux serveurs).
USE CATALOG,USE SCHEMAetREAD VOLUMEsur les compétences que vous souhaitez utiliser. Votre administrateur Databricks les accorde. Si une commande échoue avec une erreur de permission, demandez-les à votre administrateur sur le schéma de votre équipe.
Connectez-vous au registre de compétences Databricks
Installez la CLI Unity Gateway et utilisez-la pour connecter votre agent de codage au registre de compétences de votre workspace Databricks.
La CLI Unity Gateway vous connecte à votre Workspace et enregistre le serveur MCP Databricks Skills (databricks-skill-registry) que votre agent utilise pour lister, charger et download des compétences.
Demandez à votre agent d’installer et de connecter la CLI Unity Gateway pour vous :
Install the :re[UG] CLI from its Git source and connect my coding agent to Databricks:
1. Run: uv tool install git+https://github.com/databricks/unity-gateway
2. Run: ug configure --agents <your-agent> --workspace https://<workspace-host>
3. Run: ug skills
Use <your-agent> = my coding agent (claude, codex, gemini, opencode, or copilot) and
<workspace-host> = my workspace URL host (for example, my-company.cloud.databricks.com).
A browser opens during step 2 for me to sign in.
If no browser can open, install the Databricks CLI, run `databricks configure --host https://<workspace-host>` to create a profile named DEFAULT, then run `ug configure --agents <your-agent> --profile DEFAULT --use-pat` in a terminal instead.
Pour le faire vous-même, exécutez les mêmes commandes dans votre terminal :
uv tool install git+https://github.com/databricks/unity-gateway
ug configure --agents <your-agent> --workspace https://<workspace-host>
ug skills
Remplacez <your-agent> par le nom de l'agent de codage que vous utilisez (par exemple, claude, codex, gemini, opencode ou copilot) et <workspace-host> par l'hôte de l'URL de votre workspace. Un navigateur s’ouvre pendant ug configure pour que vous puissiez vous connecter. Redémarrez ensuite votre agent (ug <your-agent>) afin qu’il charge la connexion au registre des compétences.
Sur une machine sans interface graphique ou dans une CI, où aucun navigateur ne peut s'ouvrir, exécutez ug configure --agents <your-agent> --profile DEFAULT --use-pat dans un terminal pour vous connecter avec un jeton d'accès personnel à partir d'un profil de configuration CLI Databricks existant. Ce chemin nécessite le CLI Databricks, que vous pouvez installer. Pour créer le profil, exécutez d'abord databricks configure --host <workspace-url>. Voir la référence CLI ug.
Découvrir les compétences
Demandez à votre agent en langage clair. Le serveur MCP databricks-skill-registry renvoie uniquement les compétences que vous êtes autorisé à utiliser.
Répertoriez un schéma pour voir toutes les compétences qu'il contient. Les exemples sur cette page utilisent acme.sql_skills; remplacez-le par votre propre <catalog>.<schema>.
List the Databricks skills in acme.sql_skills.
L’agent indique les skills auxquelles vous pouvez accéder dans le schéma. Si la liste est vide, soit vous ne disposez pas des privilèges requis sur le schéma, soit personne n’y a publié de skills. Pour en publier une, voir Créer et partager des Unity Gateway Skills.
Utiliser des compétences
Choisissez comment utiliser une compétence que vous avez trouvée :
Méthode | Persiste entre les sessions | Fonctionne hors ligne | Obtient les mises à jour | Idéal pour |
|---|---|---|---|---|
Non | Non | Charge la version actuelle | Une seule tâche | |
Oui | Oui | Download à nouveau pour une version plus récente | Compétences que vous utilisez régulièrement | |
Oui | Non | Charge la dernière version publiée | Un large ensemble de compétences qui change souvent |
Charger une compétence pour une session
Pour n'utiliser une compétence que pour cette session, demandez à votre agent de l'utiliser par son nom :
Use acme.sql_skills.databricks-sql-guide to review this query.
L'agent lit les instructions de la compétence et les fichiers de support nécessaires pour la tâche.
Download une compétence
Pour conserver une compétence disponible lors de chaque session, download-la dans vos dossiers de compétences locaux.
Demandez à votre agent :
Download acme.sql_skills.databricks-sql-guide with the :re[UG] CLI so I have it every session:
run ug skills add --names acme.sql_skills.databricks-sql-guide.
Ou exécutez la commande vous-même :
ug skills add --names acme.sql_skills.databricks-sql-guide # one skill
ug skills add --names acme.sql_skills.databricks-sql-guide,acme.sql_skills.dbt-conventions # several skills
ug skills add --location acme.sql_skills # a whole schema
--names prend une liste séparée par des virgules de compétences <catalog>.<schema>.<name> entièrement qualifiées. Pour download à la place chaque compétence d’un schéma, transmettez ce <catalog>.<schema> à --location.
Redémarrez ensuite votre agent (ug <your-agent>). Les download sont stockées dans vos dossiers de compétences locaux (.claude/skills/ et .agents/skills/) et sont chargées à chaque session. Pour tester la compétence download, demandez :
Using our SQL guide skill, write a query on samples.nyctaxi.trips for average fare by trip distance.
samples.nyctaxi.trips existe dans chaque Workspace ; cela fonctionne donc sans aucune configuration.
Une compétence download est une copie ponctuelle. Download-la à nouveau pour obtenir une version plus récente, ou chargez le schéma en direct pour obtenir la plus récente.
Charger un schéma en direct
Limitez le serveur MCP Databricks Skills à un schéma afin que votre agent puisse lire ses compétences à la demande.
Demandez à votre agent :
Load the skills in acme.sql_skills live so I always get the latest version:
run ug skills add --location acme.sql_skills --via mcp.
Ou exécutez la commande vous-même :
ug skills add --location acme.sql_skills --via mcp
Redémarrez ensuite votre agent (ug <your-agent>) pour qu'il se connecte au schéma. Lorsqu'une tâche correspond à la description d'une compétence, l'agent peut la charger à la demande ; publiez une nouvelle version et tous les utilisateurs de la connexion la recevront immédiatement. Ceci s'associe bien à un schéma qu'une équipe centrale synchronise à partir de Git.
Le chargement en direct fonctionne sur l'ensemble d'un schéma à la fois. Vous ne pouvez pas le limiter à une seule compétence. Pour utiliser une seule compétence sans charger la totalité de son schéma, chargez-la pour une session.
Pour les agents pris en charge, la CLI Unity Gateway configure la connexion pour charger automatiquement les compétences en direct. D’autres agents peuvent exposer leur propre paramètre « always load » (ou équivalent) que vous devrez activer.
Référence
La CLI Unity Gateway est open source. Pour obtenir la référence complète et actuelle des commandes, consultez le repository de la CLI Unity Gateway. Les commandes utilisées dans ce tutoriel apparaissent en ligne dans les étapes ci-dessus.
Pour les interfaces prises en charge par le serveur Skills MCP et la compatibilité des clients, consultez Accéder aux compétences via MCP.
Dépannage
- Votre agent cesse de fonctionner après
ug configureexécutions. Start ou redémarrez votre agent (ug <your-agent>). La commande modifie la façon dont votre agent se connecte à son modèle.
Étapes suivantes
- Prise en charge des compétences dans Unity Gateway pour les concepts derrière ce tutoriel.
- Créez et partagez des compétences Unity Gateway pour publier les vôtres.
- Gérez les compétences pour les privilèges qui contrôlent qui peut lire et partager les compétences.