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.10 ou supérieur, avec pip.

• Installez la CLI Agent Bricks :

  Bash

  pip install databricks-agentbricks

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 par CLI Databricks. Authentifiez-vous sur votre workspace avec OAuth (utilisateur à machine) et enregistrez les identifiants sous forme de profil nommé.

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 terminer la connexion, puis écrit le profil dans ~/.databrickscfg:

Bash

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

Pour définir ce profil comme profil par default de la CLI afin que les commandes ultérieures puissent omettre --profile, exécutez la commande suivante :

Bash

agentbricks login --profile <profile>

agentbricks login valide les identifiants du profil. S'ils sont manquants ou rejetés, la CLI relance databricks auth login et effectue une nouvelle tentative.

É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

Liez des stockages gérés afin que votre agent puisse conserver l'historique des conversations et la mémoire à long terme. Chaque commande enregistre le nom du stockage dans agent.toml et crée le stockage s'il n'existe pas.

Pour lier un magasin de sessions et un magasin de mémoire, exécutez la commande suivante :

Bash

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

Étape 4 : Afficher le traçage

Le traçage est activé par default. agentbricks init lie une expérimentation MLflow /Shared/agentbricks_traces/<project> 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.

É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-memory"

[session_store]
name = "my-agent-session"

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

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

Pour consulter la référence complète et actualisée des commandes, comprenant l'ensemble des commandes et des options, rendez-vous sur le fichier README de la CLI Agent Bricks sur GitHub.

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.