Agent Bricks CLI

info

Beta

Cette fonctionnalité est en bêta. Aucun paramètre de workspace n'est requis pour l'activer. Installez l'Agent Bricks CLI pour start.

L'Agent Bricks CLI (databricks-agentbricks) est un outil de ligne de commande Databricks destiné aux développeurs qui créent et déploient des agents personnalisés dans le code.

La CLI Agent Bricks est une approche orientée code pour créer des agents personnalisés depuis le terminal. La CLI Agent Bricks crée la structure 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 à des fins de test et le déployer sur le runtime d’agent Databricks. La CLI vous permet de passer d’un répertoire vide à un agent déployé sans configurer manuellement le runtime, les outils, la mémoire et les ressources gérées. Pour découvrir d’autres méthodes de création d’agents personnalisés, notamment le workflow basé sur des applications, consultez la page Exécuter des agents sur Databricks Apps avec l’ancien serveur d’agents.

Prérequis

• La CLI Databricks, installée et accessible via votre variable PATH.

• Python 3.11 ou supérieur. Le package CLI d'Agent Bricks s'installe sur Python 3.10, mais les projets qu'il échafaude nécessitent Python 3.11 ou supérieur. Databricks recommande Python 3.12.

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

• Installez l'Agent Bricks CLI. Pour l'installer en tant qu'outil uv, exécutez ce qui suit :

  Bash

  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.

Vue d’ensemble : de la connexion à l’agent déployé

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

Bash

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

astuce

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

Le cycle de vie de la CLI Agent Bricks

L'interface CLI Agent Bricks génère automatiquement une structure de répertoire locale contenant du code d'agent déployable à partir d'un template de framework, avec le runtime, les tests et une interface de chat facultative déjà configurés. Vous écrivez la logique de l'application (modèle, outils et prompts), et la CLI se charge de son exécution locale et de son déploiement sur l'infrastructure Databricks.

agent.toml est la source de vérité déclarative pour toutes les ressources gérées par Databricks dont dépend votre agent : liaisons d’outils (sandbox de données, services MCP [Model Context Protocol] gérés, fonctions Unity Catalog) et ressources de mémoire, de session et de suivi. agentbricks deploy lit le fichier pour assurer le provisionnement et la configuration de l’ensemble, ce qui signifie que c’est le fichier, et non un code de configuration rédigé manuellement, qui fait l’objet du déploiement.

Les trois commandes permettant de faire passer un agent d'un répertoire vide à la production :

• agentbricks init crée l'ossature du projet à partir d'un bundled Template, en alimentant éventuellement un fichier .env avec un profil Databricks afin que le projet s'exécute immédiatement.
• agentbricks dev exécute l'agent localement par rapport au service de modèles Databricks pour vous permettre de le tester avant le déploiement.
• agentbricks deploy effectue le provisionnement des ressources déclarées dans agent.toml et déploie l'agent sur l'environnement d'exécution de l'agent Databricks.

remarque

Vous pouvez également ajouter des outils et lier des magasins de mémoire et de session à tout moment, et 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 l’une de ces étapes.

Fonctionnalités de l'interface CLI Agent Bricks

Compétence	Description
Accès aux modèles	La CLI Agent Bricks effectue automatiquement le provisionnement de l'accès aux modèles afin que votre agent puisse appeler un modèle hébergé par Databricks sans gérer d'informations d'identification ni d'endpoints. Voir les API Databricks Foundation Model.
Mémoire gérée	Des mémoires à long terme qu’un agent peut écrire et rechercher, partitionnées par acteur et sauvegardées par des magasins gérés. Utilisez la mémoire pour conserver les faits et les préférences entre les sessions, et utilisez agentbricks memory pipeline pour extraire des mémoires à partir d'un magasin de session. Voir Mémoire des agents et Pipelines de mémoire des agents.
Sessions gérées	Des transcriptions de conversation conservées dans des magasins de session gérés et partitionnées par acteur, avec prise en charge de la bifurcation des sessions en copies indépendantes. Voir Sessions d'agent.
Outils	Fonctionnalités gérées par Databricks déclarées dans agent.toml: un sandbox Unity Catalog réduit, un service MCP géré par Databricks ou une fonction Unity Catalog. Les outils Python personnalisés sont écrits directement dans le code du projet. Voir MCP.
Traçage	Traçage MLflow activé par default, qui achemine les traces de chaque exécution vers une Experimentation MLflow par projet à des fins de debugging et de monitoring. Consultez la section Présentation du traçage.
Déploiement	Déploie un agent sur l'environnement d'exécution de l'agent Databricks, octroie au service principal de l'agent l'accès aux stockages liés et gère le cycle de vie du déploiement.

Compétence	Description
Accès aux modèles	La CLI Agent Bricks effectue automatiquement le provisionnement de l'accès aux modèles afin que votre agent puisse appeler un modèle hébergé par Databricks sans gérer d'informations d'identification ni d'endpoints. Voir les API Databricks Foundation Model.
Mémoire gérée	Des mémoires à long terme qu’un agent peut écrire et rechercher, partitionnées par acteur et sauvegardées par des magasins gérés. Utilisez la mémoire pour conserver les faits et les préférences entre les sessions, et utilisez agentbricks memory pipeline pour extraire des mémoires à partir d'un magasin de session. Voir Mémoire des agents et Pipelines de mémoire des agents.
Sessions gérées	Des transcriptions de conversation conservées dans des magasins de session gérés et partitionnées par acteur, avec prise en charge de la bifurcation des sessions en copies indépendantes. Voir Sessions d'agent.
Outils	Fonctionnalités gérées par Databricks déclarées dans agent.toml: un sandbox Unity Catalog réduit, un service MCP géré par Databricks ou une fonction Unity Catalog. Les outils Python personnalisés sont écrits directement dans le code du projet. Voir MCP.
Traçage	Traçage MLflow activé par default, qui achemine les traces de chaque exécution vers une Experimentation MLflow par projet à des fins de debugging et de monitoring. Consultez la section Présentation du traçage.
Déploiement	Déploie un agent sur l'environnement d'exécution de l'agent Databricks, octroie au service principal de l'agent l'accès aux stockages liés et gère le cycle de vie du déploiement.

Créer un nouvel agent

Étape 1 : s'authentifier avec OAuth et enregistrer un profil

L'Agent Bricks CLI utilise l'authentification Databricks CLI. Authentifiez-vous sur votre workspace avec OAuth (utilisateur à machine) et enregistrez les identifiants sous la forme d'un profil nommé. Exécutez les deux commandes suivantes.

remarque

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

1. Pour start le flux OAuth, exécutez la commande suivante, en remplaçant l'hôte par l'URL de votre workspace. La commande ouvre un navigateur pour effectuer la connexion, puis écrit le profil my-workspace dans ~/.databrickscfg:

   Bash

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

2. Pour valider le profil et l'enregistrer comme default pour le CLI d'Agent Bricks afin que les commandes ultérieures puissent omettre --profile, exécutez ce qui suit :

   Bash

   agentbricks login --profile my-workspace

   Si les informations d’identification du profil sont manquantes ou rejetées, agentbricks login relance databricks auth login et réessaie.

Étape 2 : créez le projet d’agent

Générez un nouveau projet d'agent et transmettez --framework pour choisir le template. Cet exemple utilise le template LangGraph, qui inclut une application de chat par navigateur :

Bash

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

La CLI intègre un Template fourni par framework et --framework sélectionne celui à déployer : langgraph pour LangGraph ou openai pour le SDK OpenAI Agents. La CLI écrit les ressources gérées et les liaisons d'outils du projet dans agent.toml et la provenance du Template dans .agentbricks/project.toml. Pour générer le backend compatible uniquement avec l'API sans l'application de chat, ajoutez --disable-chat-app.

Étape 3 : Associer les magasins de sessions et de mémoire gérés

Les magasins gérés permettent à votre agent de conserver l'historique de la conversation et la mémoire à long terme. agentbricks init déclare un magasin de session et un magasin de 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 encore et donne à l'agent déployé un accès à celui-ci, donc la plupart des agents peuvent ignorer cette étape.

Pour utiliser un magasin différent, liez-le par nom. Chaque commande remplace le nom du magasin dans agent.toml. Cela ne crée pas le magasin. Pour lier un magasin de session nommé my-agent-sessions et un magasin de mémoire nommé my-agent-memory, exécutez les commandes suivantes :

Bash

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

Pour start l’agent avec des mémoires déjà présentes dans la boutique, créez la boutique et ajoutez des entrées avant de déployer. Consultez la Agent Bricks CLI tab dans Démarrer avec la mémoire de l'agent.

Étape 4 : Afficher le traçage

Le traçage est activé par default. agentbricks init lie une expérimentation MLflow /Shared/agentbricks_traces/<project>-<suffix> par default, et agentbricks dev et agentbricks deploy y envoient les traces de chaque run.

Pour lister les traces une fois que votre agent en a produit, exécutez la commande suivante :

Bash

agentbricks tracing list

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

Étape 5 : Exécuter l'agent localement

Exécutez l'agent sur votre machine pour le tester avant le déploiement.

Bash

agentbricks dev

Cette commande permet de démarrer un serveur local sur le port 8000 en utilisant la même commande et le même environnement que le runtime de l'agent Databricks. L'interface CLI Agent Bricks connecte l'agent au service de modèles Databricks afin qu'il puisse appeler le modèle localement. Le Template définit un modèle par default comme valeur MODEL dans agent/agent.py. Pour utiliser un autre modèle, modifiez cette valeur. Envoyez des requêtes à http://localhost:8000 pour interagir avec l'agent.

remarque

agentbricks dev ne se connecte pas aux magasins de mémoire ou de session. La mémoire à long terme est désactivée et l'historique de la conversation ne dure que pendant l'exécution du serveur local. L'application de chat affiche Non connecté pour la mémoire localement, même lorsqu'un magasin est lié. La mémoire se connecte après agentbricks deploy.

Étape 6 : Déployez l’agent

Déployez l’agent dans le runtime d’agent Databricks. La CLI assure le provisionnement des magasins liés, accorde au Service Principal de l’agent l’accès à ces derniers et déploie l’application. L’agent déployé s’appelle agent-bricks-<name>.

Bash

agentbricks deploy my-agent

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

Ajouter un agent existant

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

Step 1 : Prepare the migration

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

Bash

agentbricks init --framework langgraph --existing .

La CLI écrit un répertoire agent-bricks-migrate/ qui contient les instructions de migration, une invite pour votre agent de codage et un projet de référence généré à partir des templates de la CLI. Il ajoute également 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, vos dépendances ou le fichier .env, et ne crée aucune ressource dans votre workspace.

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

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

Étape 3 : vérifier la conversion

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

Bash

agentbricks doctor .

agentbricks doctor examine les fichiers du projet sans exécuter son code ni contacter Databricks. Il réussit lorsque le projet possède un agent.toml valide, start DurableAgentServer avec un gestionnaire d'appel et appelle l'adaptateur pour son framework. Un rapport échoué signifie que la conversion n’est pas terminée.

Étape 4 : Nettoyage, exécution et déploiement

Supprimez agent-bricks-migrate/ et les deux compétences qui y font référence, et excluez-les de vos commits. Exécutez ensuite l’agent avec agentbricks dev et déployez-le 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.
• Le fait de basculer l’agent vers un stockage de sessions 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 antérieures.
• Les options --disable-chat-app, --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 créez votre agent avec l'outil Agent Bricks CLI, ajoutez un service MCP system.ai intégré à votre projet avec agentbricks tools add mcp. La commande vérifie que le service existe dans votre workspace et enregistre l'outil dans agent.toml. L'agent se connecte à l'outil lors de l'exécution, vous n'avez donc pas à écrire de code de connexion.

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

Bash

agentbricks tools list --kind mcp

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

Bash

# Search the public web.
agentbricks tools add mcp system.ai.web_search

# 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 default, un outil s’exécute avec les autorisations de l’utilisateur qui a envoyé la requête à votre agent. Pour l’exécuter à la place en tant que Service Principal 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 supprimer des outils, exécutez agentbricks tools list ou agentbricks tools remove mcp <service>.

Pour les autres outils, consultez les pages suivantes :

• Tous les services intégrés et leurs fonctionnalités : MCP fournis par Databricks.
• Vos propres serveurs MCP externes : External MCP servers.
• Fonctions Unity Catalog en tant qu'outils : Create agent tools using Unity Catalog functions.
• Un seul Genie Agent curaté : serveur MCP Genie Agent.

référenceagent.toml

agent.toml est la source de vérité déclarative pour les ressources gérées par Databricks que votre agent utilise. agentbricks init le crée, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind et agentbricks tracing bind le mettent à jour, et agentbricks deploy le lit pour assurer le provisionnement des ressources et accorder l’accès. Vous pouvez également 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 template du framework : langgraph ou openai.
[agent] server	Le serveur d’agent : agentbricks pour DurableAgentServer, ou custom pour votre propre serveur.
[memory_store] name	Le magasin de mémoire géré utilisé par l'agent.
[session_store] name	Le magasin de sessions géré utilisé par l’agent.
[tracing] experiment_name	The MLflow Experimentation for traces. Remove the section to turn tracing off.
[[tools]]	Liaison d'outils. Chaque outil possède un id, une valeur auth de user ou app, et un source qui identifie l'outil, ainsi qu'un policy facultatif.
[auth.user]	Demander l’autorisation de l’utilisateur pour les outils que vous écrivez dans le code : required et additional_api_scopes. Consultez Demander l’autorisation de l’utilisateur.

Section ou champ	Description
schema_version	La version du format agent.toml. Les projets générés utilisent 1.
[agent] framework	Le template du framework : langgraph ou openai.
[agent] server	Le serveur d’agent : agentbricks pour DurableAgentServer, ou custom pour votre propre serveur.
[memory_store] name	Le magasin de mémoire géré utilisé par l'agent.
[session_store] name	Le magasin de sessions géré utilisé par l’agent.
[tracing] experiment_name	The MLflow Experimentation for traces. Remove the section to turn tracing off.
[[tools]]	Liaison d'outils. Chaque outil possède un id, une valeur auth de user ou app, et un source qui identifie l'outil, ainsi qu'un policy facultatif.
[auth.user]	Demander l’autorisation de l’utilisateur pour les outils que vous écrivez dans le code : required et additional_api_scopes. Consultez Demander l’autorisation de l’utilisateur.

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

Toml

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, de sorte que les projets portant le même nom ne partagent pas de magasins ni d'expérimentations.

L’exemple suivant montre les liaisons d’outils que agentbricks tools add écrit : un service MCP intégré, un Genie Agent et un sandbox limité à une seule table :

Toml

[[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" }] }

Tools that call a Unity Catalog function use source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } and support only auth = "app".

Référence des commandes

Le tableau suivant liste les commandes de l'Agent Bricks CLI.

Commande	Description
agentbricks login	Authentifiez un profil et enregistrez-le default.
agentbricks logout	Oubliez le profil default enregistré sans supprimer ses identifiants.
agentbricks init	Créez un nouveau projet d'agent ou préparez un agent existant pour une migration avec --existing.
agentbricks doctor	Vérifiez qu'un agent existant est configuré pour l'Agent Bricks CLI.
agentbricks dev	Exécutez l'agent localement avec une interface utilisateur de chat.
agentbricks memory	Gérer la mémoire à long terme : lier ou délier un stockage, et gérer les stockages, les entrées et les pipelines de mémoire.
agentbricks sessions	Gérer les sessions de conversation : lier ou délier un dépôt, et gérer les dépôts de session.
agentbricks tools	Lister, ajouter et supprimer les outils de l'agent.
agentbricks mcp	Découvrez les services MCP gérés.
agentbricks tracing	Lier, délier et inspecter le traçage.
agentbricks deploy	Déployez l'agent sur le runtime d'agent Databricks.
agentbricks deployments	Gérez les agents déployés : list, get, wait, logs, start, stop et delete.
agentbricks endpoint	Appeler un endpoint HTTP.
agentbricks experimental	Commandes expérimentales susceptibles d'être modifiées sans préavis : experimental models et experimental prompts.

Commande	Description
agentbricks login	Authentifiez un profil et enregistrez-le default.
agentbricks logout	Oubliez le profil default enregistré sans supprimer ses identifiants.
agentbricks init	Créez un nouveau projet d'agent ou préparez un agent existant pour une migration avec --existing.
agentbricks doctor	Vérifiez qu'un agent existant est configuré pour l'Agent Bricks CLI.
agentbricks dev	Exécutez l'agent localement avec une interface utilisateur de chat.
agentbricks memory	Gérer la mémoire à long terme : lier ou délier un stockage, et gérer les stockages, les entrées et les pipelines de mémoire.
agentbricks sessions	Gérer les sessions de conversation : lier ou délier un dépôt, et gérer les dépôts de session.
agentbricks tools	Lister, ajouter et supprimer les outils de l'agent.
agentbricks mcp	Découvrez les services MCP gérés.
agentbricks tracing	Lier, délier et inspecter le traçage.
agentbricks deploy	Déployez l'agent sur le runtime d'agent Databricks.
agentbricks deployments	Gérez les agents déployés : list, get, wait, logs, start, stop et delete.
agentbricks endpoint	Appeler un endpoint HTTP.
agentbricks experimental	Commandes expérimentales susceptibles d'être modifiées sans préavis : experimental models et experimental prompts.

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

Dépannage

L’installation échoue sur un Mac Intel lors de la construction cryptography

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

Bash

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

L'installation ou agentbricks dev échoue en raison de la version de Python

Si l'installation ou agentbricks dev échoue lors de la construction des dépendances, vérifiez votre version de Python avec python3 --version. Les projets échafaudés nécessitent Python 3.11 ou version ultérieure, et Databricks recommande Python 3.12. Sur les versions Python plus récentes, certaines dépendances peuvent ne pas avoir de packages préconstruits. Pour installer le CLI avec Python 3.12, exécutez ce qui suit :

Bash

uv tool install --python 3.12 databricks-agentbricks

Ressources supplémentaires

• Agent tools and MCP services: MCPs.
• Concepts et API de la mémoire des agents : Mémoire des agents.
• Concepts et API des sessions d’agent : Sessions d’agent.
• Distiller l’historique des sessions en mémoire à long terme : Pipelines de mémoire d’agent.
• MLflow Tracing pour les agents : Présentation du traçage.