CLI de l’agent Bricks

Important

Cette fonctionnalité est en version bêta. Aucun réglage d’espace de travail n’est nécessaire pour l’activer. Installez l’interface en ligne de commande Agent Bricks pour commencer.

La ligne de commande Agent Bricks (databricks-agentbricks) est un outil en ligne de commande Azure Databricks destiné aux développeurs qui créent et déploient des agents personnalisés en code.

Agent Bricks CLI est une approche orientée code pour créer des agents personnalisés depuis le terminal. La CLI Agent Bricks génère la structure de base d’un projet à l’aide d’un framework intégré fondé sur les bonnes pratiques de Databricks. Il peut ensuite exécuter le projet localement pour les tests et le déployer sur l’exécution de l’agent Azure Databricks. La CLI permet de passer d’un répertoire vide à un agent déployé sans avoir à câbler le temps d’exécution, les outils, la mémoire et les ressources gérées à la main. Pour d’autres moyens de créer des agents personnalisés, y compris le flux de travail basé sur une application, voir Exécuter des agents sur Databricks Apps en utilisant le serveur d’agents hérité.

Prerequisites

  • La Databricks CLI, installée et disponible dans votre variable PATH.

  • Python 3.11 ou version ultérieure. Le paquet Agent Bricks CLI s’installe sur Python 3.10, mais les projets qu’il génère nécessitent Python 3.11 ou plus. Databricks recommande Python 3.12.

  • uv, qui exécute le projet généré pour agentbricks init, agentbricks dev, et agentbricks deploy.

  • Installez la CLI Agent Bricks. Pour l’installer en tant qu’outil uv , exécutez les éléments suivants :

    uv tool install databricks-agentbricks

    Pour l’installer avec pip à la place, exécutez pip install databricks-agentbricks. Si l’installation échoue, consultez Dépannage.

Aperçu : de la connexion à un agent déployé

La séquence suivante résume les étapes de Créer un nouvel agent :

databricks auth login --host "https://<your-workspace-url>" --profile my-workspace
agentbricks login --profile my-workspace
agentbricks init --framework langgraph my-agent
cd my-agent
agentbricks dev
agentbricks deploy my-agent

Tip

Chaque commande et groupe de commandes prend en charge --help. Par exemple, exécutez agentbricks memory --help pour lister les commandes mémoire et leurs options.

Le cycle de vie de la CLI des Agent Bricks

La CLI Agent Bricks génère la structure d’un répertoire local contenant le code d’agent déployable à partir d’un modèle de cadre applicatif, avec l’environnement d’exécution, les tests et, en option, une interface de chat déjà configurés. Vous écrivez la logique applicative (modèle, outils et invites), et la CLI s’occupe de l’exécution locale et de son déploiement sur l’infrastructure Azure Databricks.

agent.tomlest la source déclarative de vérité pour toutes les ressources gérées par Azure Databricks dont votre agent dépend : les liaisons d’outils (bac à sable de données, services du protocole de contexte de modèle géré (MCP), fonctions du catalogue Unity), ainsi que les ressources mémoire, session et traçage. agentbricks deploy Il le lit pour provisionner et câbler tout, donc c’est le fichier, et non le code de configuration manuscrit, qui est déployé.

Les trois commandes qui passent un agent d’un répertoire vide à la production :

  • agentbricks init génère la structure du projet à partir d’un modèle intégré et peut, en option, initialiser un fichier .env avec un profil Databricks afin que le projet puisse être exécuté immédiatement.
  • agentbricks dev exécute l’agent localement avec le service de déploiement de modèles d’Azure Databricks afin que vous puissiez le tester avant de le déployer.
  • agentbricks deployprovisionne les ressources déclarées dans agent.toml et déploie l’agent vers l’exécution de l’agent Azure Databricks.

Cycle de vie de la CLI des Agents Bricks : phases d’initiation, de développement et de déploiement avec leurs actions clés

Note

Vous pouvez aussi ajouter des outils et associer des stockages de mémoire et de session à tout moment, pas seulement lors de l’initialisation. Utilisez agentbricks tools add, agentbricks memory bind, et agentbricks sessions bind pour mettre à jour la configuration de votre agent entre chacune de ces étapes.

Capacités de la CLI d’Agent Bricks

Capacité Description
Accès aux modèles La ligne de ligne de commande Agent Bricks prévoit automatiquement l’accès au modèle afin que votre agent puisse appeler un modèle servi par Azure Databricks sans gérer les identifiants ou les points de terminaison. Consultez API Databricks Foundation Model.
Mémoire gérée Mémoires à long terme qu’un agent peut enregistrer et rechercher, partitionnées par acteur et stockées dans des magasins de données gérés. Utilisez la mémoire pour conserver les faits et préférences entre les sessions, et utilisez agentbricks memory pipeline pour distiller les mémoires d’un magasin de sessions. Voir mémoire de l’agent et pipelines de mémoire de l’agent.
Sessions gérées Les transcriptions de conversations sont conservées dans des espaces de stockage de sessions gérés et partitionnées par acteur, avec prise en charge de la duplication des sessions en copies indépendantes. Voir sessions de l’agent.
Tools Fonctionnalités gérées par Azure Databricks déclarées dans agent.toml : un bac à sable Unity Catalog à périmètre restreint, un service MCP géré par Azure Databricks, ou une fonction Unity Catalog. Les outils Python personnalisés sont écrits directement dans le code du projet. Voir MCPs.
Tracing Le traçage MLflow, activé par défaut, achemine les traces de chaque exécution vers une expérience MLflow propre à chaque projet pour le débogage et la surveillance. Voir aperçu du traçage.
Deployment Déploie un agent dans l’environnement d’exécution des agents d’Azure Databricks, accorde au principal de service de l’agent l’accès aux magasins associés et gère le cycle de vie du déploiement.

Créer un nouvel agent

Étape 1 : Authentifier avec OAuth et enregistrer un profil

La CLI Agent Bricks utilise l’authentification de la CLI Databricks. Authentifiez votre espace de travail avec OAuth (utilisateur-vers-machine) et enregistrez les identifiants comme un profil nommé. Exécutez les deux commandes suivantes.

Note

Un profil est un ensemble nommé de paramètres de connexion (une URL d’espace de travail et ses identifiants) enregistrés dans ~/.databrickscfg. Les exemples sur cette page utilisent un profil nommé my-workspace. Choisissez n’importe quel nom, puis transmettez-le avec --profile.

  1. Pour lancer le flux OAuth, exécutez ce qui suit, en remplaçant l’hôte par l’URL de votre espace de travail. La commande ouvre un navigateur pour finaliser la connexion, puis écrit le profil my-workspace dans ~/.databrickscfg:

    databricks auth login --host "https://<your-workspace-url>" --profile my-workspace

  2. Pour valider le profil et le sauvegarder comme la valeur par défaut d’Agent Bricks CLI afin que les commandes ultérieures puissent omettre --profile, exécutez ce qui suit :

    agentbricks login --profile my-workspace

    Si les identifiants du profil manquent ou sont rejetés, agentbricks login relance databricks auth login et réessaie.

Étape 2 : Créer la structure du projet d’agent

Échafaudez un nouveau projet d’agent, puis passez --framework pour choisir le modèle. Cet exemple utilise le modèle LangGraph, qui inclut une application de chat navigateur :

agentbricks init --framework langgraph my-agent
cd my-agent

La CLI fournit un modèle groupé par framework et --framework sélectionne celui à partir de lequel s’appuyer : langgraph pour LangGraph ou openai pour le SDK OpenAI Agents. La CLI écrit les ressources gérées du projet et les liaisons d’outils dans agent.toml, et les informations de provenance du modèle dans .agentbricks/project.toml. Pour générer le backend uniquement API sans l’application de chat, ajoutez --disable-chat-app.

Étape 3 : Joindre les espaces de stockage de session et de mémoire gérés

Les magasins gérés permettent à votre agent de conserver l’historique des conversations et la mémoire à long terme. agentbricks init déclare un magasin de session et un stockage en mémoire dans agent.toml, nommés d’après le projet avec un suffixe aléatoire, tel que my-agent-cuzvas-memory. agentbricks deploy crée tout magasin déclaré qui n’existe pas déjà et accorde à l’agent déployé l’accès à celui-ci, donc la plupart des agents peuvent sauter cette étape.

Pour utiliser un autre magasin de données, liez-le par nom. Chaque commande remplace le nom du magasin dans agent.toml. Cela ne crée pas le store. Pour lier un magasin de session nommé my-agent-sessions et un magasin en mémoire nommé my-agent-memory, exécutez ce qui suit :

agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory

Pour démarrer l’agent avec des mémoires déjà dans le stockage, créez le stockage et ajoutez des entrées avant de déployer. Voir l’onglet Agent Bricks CLI dans Commencer avec la mémoire d’agent.

Étape 4 : Visualiser le traçage

Le traçage est activé par défaut. agentbricks init lie une expérience MLflow par défaut /Shared/agentbricks_traces/<project>-<suffix> , et agentbricks dev envoie agentbricks deploy les traces de chaque exécution vers celle-ci.

Pour afficher la liste des traces une fois que votre agent en a généré, exécutez la commande suivante :

agentbricks tracing list

Pour lier une expérience MLflow spécifique, exécutez agentbricks tracing bind --experiment-id <experiment-id>. Pour désactiver le tracé, exécutez agentbricks tracing unbind.

Étape 5 : Faites passer l’agent localement

Faites tourner l’agent sur votre machine pour le tester avant de déployer.

agentbricks dev

Cela lance un serveur local sur le port 8000 en utilisant la même commande et le même environnement que l’exécution de l’agent Azure Databricks. L’interface de ligne de commande Agent Bricks connecte l’agent au service de modèles d’Azure Databricks pour qu’il puisse appeler le modèle localement. Le modèle définit un modèle par défaut sur la valeur MODEL dans agent/agent.py. Pour utiliser un modèle différent, modifie cette valeur. Envoyez des requêtes à http://localhost:8000 pour interagir avec l’agent.

Note

agentbricks dev ne se connecte pas aux magasins mémoire ou aux magasins de session. La mémoire à long terme est désactivée, et l’historique des conversations ne dure que pendant que le serveur local fonctionne. L’application de chat affiche « Non connecté » pour la mémoire localement même lorsqu’un store est associé. La mémoire se connecte après agentbricks deploy.

Étape 6 : Déployer l’agent

Déploie l’agent dans l’exécution de l’agent Azure Databricks. L’interface CLI approvisionne les magasins associés, accorde au principal de service de l’agent l’accès à ceux-ci et effectue le déploiement. L’agent déployé porte le nom agent-bricks-<name>.

agentbricks deploy my-agent

À la fin du déploiement, la CLI renvoie l’URL du déploiement. Ouvrez cette URL pour interagir avec votre agent en direct, qui est automatiquement connecté au service du modèle Azure Databricks. Pour gérer le déploiement par la suite, utilisez les agentbricks deployments commandes, telles que agentbricks deployments logs et agentbricks deployments stop.

Amenez un agent existant

Si vous avez déjà construit un agent avec LangGraph ou le SDK OpenAI Agents, utilisez l’indicateur --existing pour le déplacer vers la CLI Agent Bricks et DurableAgentServer. La CLI ne réécrit pas votre code. Au lieu de cela, il prépare des instructions de migration qu’un agent de codage, tel que Claude Code ou Codex, suit pour convertir le projet.

Étape 1 : Préparer la migration

Depuis le répertoire de projets de l’agent, préparez la migration. Passez le cadre utilisé par l’agent : langgraph pour LangGraph ou openai pour le SDK OpenAI Agents.

agentbricks init --framework langgraph --existing .

La CLI écrit un agent-bricks-migrate/ répertoire contenant les instructions de migration, un prompt pour votre agent de codage, et un projet de référence généré à partir des modèles de la CLI. Cela ajoute aussi des compétences dans .claude/skills/ et .agent/skills/ qui orientent les agents de codage vers les instructions. La commande ne modifie pas le code de votre application, les dépendances ou le fichier .env, et ne crée aucune ressource dans votre espace de travail.

Étape 2 : Convertir le projet avec votre agent de codage

Collez l’invite depuis agent-bricks-migrate/ dans votre agent de codage. L’agent de codage convertit le projet pour utiliser agent.toml et un point d’entrée DurableAgentServer, puis vérifie la conversion.

Étape 3 : Vérifiez la conversion

Exécutez agentbricks doctor dans le répertoire du projet :

agentbricks doctor .

agentbricks doctor inspecte les fichiers du projet sans exécuter son code ni contacter Azure Databricks. L’opération réussit lorsque le projet possède un agent.toml valide, commence DurableAgentServer avec un gestionnaire d’invocation, et appelle l’adaptateur pour son infrastructure. Un échec du rapport signifie que la conversion n’est pas terminée.

Étape 4 : Nettoyer, lancer et déployer

Supprimez agent-bricks-migrate/ ainsi que les deux skills qui y mènent, et ne les incluez pas dans vos commits. Ensuite, exécuter l’agent avec agentbricks dev et le déployer avec agentbricks deploy.

Considérations

  • --existing prend en charge LangGraph et le SDK OpenAI Agents avec DurableAgentServer. Il ne prend pas en charge --server custom.
  • Passer l’agent à un stockage de session géré ne déplace pas son historique de conversation existant. Les instructions de migration vous demandent de décider comment gérer les conversations précédentes.
  • Les --disable-chat-appoptions , --memory-store, et --session-store façonnent le projet de référence. Ils ne créent pas de ressources.

Ajouter des outils MCP

Si vous construisez votre agent avec la CLI Agent Bricks, ajoutez un service MCP intégré system.ai à votre projet avec agentbricks tools add mcp. La commande vérifie que le service existe dans votre espace de travail et enregistre l’outil dans agent.toml. L’agent se connecte à l’outil à l’exécution, donc vous n’écrivez aucun code de connexion.

Pour lister les services MCP que vous pouvez ajouter, exécutez la commande suivante :

agentbricks tools list --kind mcp

Les exemples suivants ajoutent des services intégrés courants :

# Answer analytics questions across your workspace with Genie One.
agentbricks tools add mcp system.ai.genie_one_mcp

# Run SQL on a SQL warehouse.
agentbricks tools add mcp system.ai.dbsql

# Connect to third-party applications.
agentbricks tools add mcp system.ai.slack
agentbricks tools add mcp system.ai.github

Par défaut, un outil s’exécute avec les permissions de l’utilisateur qui a envoyé la requête à votre agent. Pour l’exécuter comme principal de service de l’application, ajoutez --auth app. Pour Google Drive, Gmail, Google Calendar et Microsoft 365, chaque utilisateur effectue une connexion OAuth unique avant le premier appel. Voir Applications connectées.

Pour examiner ou retirer des outils, exécuter agentbricks tools list ou agentbricks tools remove mcp <service>.

Pour d’autres outils, voir les pages suivantes :

agent.toml Référence

agent.toml est la source de référence déclarative pour les ressources gérées par Azure Databricks que votre agent utilise. agentbricks init le crée, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, et agentbricks tracing bind le met à jour, puis agentbricks deploy le lit pour provisionner des ressources et accorder l’accès. Vous pouvez aussi le modifier directement.

Section ou champ Description
schema_version La version du format agent.toml. Les projets générés utilisent 1.
[agent] framework Le modèle de cadre : langgraph ou openai.
[agent] server Le serveur agent : agentbricks pour DurableAgentServer, ou custom pour votre propre serveur.
[memory_store] name Le stockage de mémoire managée que l’agent utilise.
[session_store] name Le stockage de session géré utilisé par l’agent.
[tracing] experiment_name L’expérience MLflow pour les traces. Supprimez la section pour désactiver le tracé.
[[tools]] Une liaison d’outil. Chaque outil possède une id, une valeur auth de user ou app, et un source qui identifie l’outil, ainsi qu’un policy facultatif.
[auth.user] Demandez l’autorisation de l’utilisateur pour les outils que vous écrivez en code : required et additional_api_scopes. Voir la demande d’autorisation de l’utilisateur.

L’exemple suivant est le fichier que agentbricks init génère pour un agent LangGraph nommé my-agent:

schema_version = 1

[agent]
framework = "langgraph"
server = "agentbricks"

[memory_store]
name = "my-agent-cuzvas-memory"

[session_store]
name = "my-agent-cuzvas-sessions"

[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent-cuzvas"

Le suffixe aléatoire (cuzvas dans cet exemple) est différent pour chaque projet, donc les projets portant le même nom ne partagent pas de magasins ni d’expérimentations.

L’exemple suivant montre des liaisons d’outils que agentbricks tools add génère : un service MCP intégré, un agent Genie, et un bac à sable limité à une seule table :

[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<space-id>" }

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "table:samples.nyctaxi.trips", permission = "read_only" }] }

Les outils qui appellent une fonction du catalogue Unity utilisent source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } et supportent uniquement auth = "app".

Référence de commande

Le tableau suivant liste les commandes CLI Agent Bricks.

Command Description
agentbricks login Authentifie un profil et enregistre-le comme profil par défaut.
agentbricks logout Oublier le profil par défaut sauvegardé sans supprimer ses identifiants.
agentbricks init Créez un nouveau projet d’agent, ou préparez un agent existant en vue d’une migration avec --existing.
agentbricks doctor Vérifiez qu’un agent existant est configuré pour la CLI Agent Bricks.
agentbricks dev Faites tourner l’agent localement avec une interface de chat.
agentbricks memory Gérer la mémoire à long terme : lier ou délier un magasin de données, et gérer les magasins de données, les entrées et les pipelines de mémoire.
agentbricks sessions Gérez les sessions de conversation : liez ou déliez un stockage, et gérez les stockages de session.
agentbricks tools Listez, ajoutez et retirez les outils de l’agent.
agentbricks mcp Découvrez les services MCP gérés.
agentbricks tracing Liez, dissociez et inspectez le tracé.
agentbricks deploy Déploie l’agent dans l’exécution de l’agent Azure Databricks.
agentbricks deployments Gérer les agents déployés : list, get, wait, logs, start, stop, et delete.
agentbricks endpoint Invoquez un point de terminaison HTTP.
agentbricks experimental Commandes expérimentales qui pourraient changer sans prévenir : experimental models et experimental prompts.

Pour chaque drapeau et option, consultez la référence de commande CLI Agent Bricks sur GitHub.

Troubleshooting

L’installation échoue sur un Mac Intel pendant la compilation cryptography

Si l’installation échoue sur un Mac Intel lors de la compilation du cryptography package à partir du code source, installez plutôt des packages pré-construits. Pour installer avec pip, exécutez ce qui suit :

pip install --only-binary :all: databricks-agentbricks

Installer ou agentbricks dev échoue en raison de la version de Python

Si l’installation ou agentbricks dev échoue lors de la création des dépendances, vérifiez votre version de Python avec python3 --version. Les projets générés par scaffolding nécessitent Python 3.11 ou supérieur, et Databricks recommande Python 3.12. Sur les versions Python plus récentes, certaines dépendances peuvent ne pas avoir de paquets préconstruits. Pour installer l’interface en ligne de commande avec Python 3.12, exécutez ce qui suit :

uv tool install --python 3.12 databricks-agentbricks

Ressources additionnelles

  • Dernière mise à jour :