Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Esta característica se encuentra en su versión beta. No se requiere ninguna configuración de espacio de trabajo para activarlo. Instala la CLI de Agent Bricks para empezar.
La CLI Agent Bricks (databricks-agentbricks) es una herramienta de línea de comandos de Azure Databricks para desarrolladores que crean y despliegan agentes personalizados en código.
Utilice la CLI de Agent Bricks para escribir lógica de agente personalizada en código usando una plantilla LangGraph o OpenAI Agents SDK y desplegarla desde su terminal. Para crear un agente sin código para preguntas sobre tus datos, utiliza Genie Agents en la interfaz de Azure Databricks. Para más información, consulta ¿Qué es Agent Bricks?, las preguntas frecuentes sobre Agent Bricks y el programa de inicio rápido de Agent Bricks.
La CLI de Agent Bricks estructura un proyecto utilizando un marco integrado basado en las mejores prácticas de Databricks. Luego puede ejecutar el proyecto localmente para pruebas y desplegarlo en el entorno de ejecución del agente de Azure Databricks. La CLI te permite pasar de un directorio vacío a un agente desplegado sin tener que cablear a mano el tiempo de ejecución, herramientas, memoria y recursos gestionados. Para otras formas de crear agentes personalizados, incluido el flujo de trabajo basado en aplicaciones, consulta Ejecutar agentes en aplicaciones de Databricks usando el servidor de agentes heredado.
Prerequisites
La CLI de Databricks, instalada y disponible en la ruta de acceso.
Python 3.11 o superior. El paquete de la CLI Agent Bricks se instala en Python 3.10, pero los proyectos que genera requieren Python 3.11 o superior. Databricks recomienda Python 3.12.
uv, que ejecuta el proyecto generado paraagentbricks init,agentbricks devyagentbricks deploy.Instala la CLI de Agent Bricks. Para instalarlo como una herramienta de
uv, ejecute lo siguiente:uv tool install databricks-agentbricksPara instalarlo con
pipen su lugar, ejecutapip install databricks-agentbricks. Si la instalación falla, consulta Solución de problemas.
Resumen: desde iniciar sesión hasta un agente desplegado
La siguiente secuencia resume los pasos en Crear un nuevo agente:
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
Cada comando y grupo de comandos admite --help. Por ejemplo, ejecuta agentbricks memory --help para listar los comandos de memoria y sus flags.
El ciclo de vida de la CLI de Agent Bricks
La CLI de Agent Bricks estructura un directorio local de código de agente desplegable desde una plantilla de framework, con el tiempo de ejecución, las pruebas y una interfaz de chat opcional ya conectadas. Escribes la lógica de la aplicación (modelo, herramientas y prompts), y la CLI se encarga de ejecutarla localmente y desplegarla en la infraestructura de Azure Databricks.
agent.tomles la fuente declarativa de verdad para todos los recursos gestionados por Azure Databricks de los que depende tu agente: enlaces de herramientas (sandbox de datos, servicios gestionados del Protocolo de Contexto de Modelo (MCP), funciones del Catálogo de Unity), y recursos de memoria, sesión y trazado.
agentbricks deploy lo lee para provisionar y configurarlo todo, así que el archivo, no el código de instalación escrito a mano, es lo que se despliega.
Los tres comandos que llevan a un agente de un directorio en blanco a producción:
-
agentbricks initgenera la estructura del proyecto a partir de una plantilla incluida, rellenando opcionalmente un archivo.envcon un perfil de Databricks para que el proyecto se ejecute de inmediato. -
agentbricks devEjecuta el agente localmente contra el serving de modelos de Azure Databricks para que puedas probarlo antes de desplegarlo. -
agentbricks deployprovisiona los recursos declarados enagent.tomly despliega el agente al entorno de ejecución del agente de Azure Databricks.
Note
También puedes añadir herramientas y asignar memoria y almacenes de sesión en cualquier momento, no solo en init. Usa agentbricks tools add, agentbricks memory bind, y agentbricks sessions bind para actualizar la configuración de tu agente entre cualquiera de estos pasos.
Capacidades de la CLI de Agent Bricks
| Capacidad | Description |
|---|---|
| Acceso al modelo | La CLI de Agent Bricks provisiona automáticamente el acceso al modelo para que tu agente pueda llamar a un modelo servido por Azure Databricks sin gestionar credenciales ni endpoints. Vea API de modelo de Databricks Foundation. |
| Memoria gestionada | Memorias a largo plazo en las que un agente puede escribir y consultar, particionadas por actor y respaldadas por almacenes gestionados. Use la memoria para conservar datos y preferencias entre sesiones, y use agentbricks memory pipeline para destilar las memorias desde un almacén de sesiones. Consulta Memoria del agente y Flujos de memoria del agente. |
| Sesiones gestionadas | Las transcripciones de conversaciones se almacenan en almacenes de sesiones administrados y se particionan por actor, con capacidad para bifurcar sesiones en copias independientes. Consulta las sesiones de los agentes. |
| Tools | Capacidades gestionadas por Azure Databricks declaradas en agent.toml: un sandbox, un servicio MCP gestionado por Azure Databricks o una función de Unity Catalog. Las herramientas personalizadas de Python se escriben directamente en el código del proyecto. Consulta MCPs. |
| Tracing | El trazado de MLflow, activado de forma predeterminada, que dirige las trazas de cada ejecución al experimento de MLflow de cada proyecto para depuración y supervisión. Consulte la visión general del seguimiento. |
| Deployment | Despliega un agente en el entorno de ejecución del agente de Azure Databricks, concede acceso al principal de servicio del agente a almacenes vinculados y gestiona el ciclo de vida del despliegue. |
Crea un nuevo agente
Paso 1: Autentica con OAuth y guarda un perfil
La CLI de Agent Bricks utiliza la autenticación de la CLI de Databricks. Autentica tu espacio de trabajo con OAuth (usuario-a-máquina) y guarda las credenciales como un perfil nombrado. Ejecuta ambos comandos a continuación.
Note
Un perfil es un conjunto nombrado de ajustes de conexión (una URL de espacio de trabajo y sus credenciales) guardados en ~/.databrickscfg. Los ejemplos en esta página utilizan un perfil llamado my-workspace. Elige cualquier nombre y pásalo con --profile.
Para iniciar el flujo OAuth, ejecuta lo siguiente, reemplazando el host por la URL de tu espacio de trabajo. El comando abre un navegador para completar el inicio de sesión, y luego escribe el
my-workspaceperfil en~/.databrickscfg:databricks auth login --host "https://<your-workspace-url>" --profile my-workspacePara validar el perfil y guardarlo como la CLI por defecto de Agent Bricks para que los comandos posteriores puedan omitir
--profile, ejecuta lo siguiente:agentbricks login --profile my-workspaceSi las credenciales del perfil faltan o se rechazan,
agentbricks loginvuelve a ejecutardatabricks auth loginy reintenta.
Paso 2: Estructura el proyecto del agente
Estructura un nuevo proyecto de agente y pasa --framework para elegir la plantilla. Este ejemplo utiliza la plantilla LangGraph, que incluye una aplicación de chat para navegador:
agentbricks init --framework langgraph my-agent
cd my-agent
La CLI incluye una plantilla integrada por cada framework y --framework selecciona a partir de cuál generar la estructura: langgraph para LangGraph o openai para el SDK de agentes de OpenAI. La CLI escribe los recursos gestionados del proyecto y las asignaciones de herramientas a agent.toml y la procedencia de la plantilla en .agentbricks/project.toml. Para generar el backend únicamente de API sin la aplicación de chat, añade --disable-chat-app.
Paso 3: Asociar almacenes administrados de sesiones y de memoria
Los almacenes administrados permiten que tu agente mantenga el historial de conversaciones y la memoria a largo plazo.
agentbricks init declara un almacén de sesión y un almacén de memoria en agent.toml, nombrados así como el proyecto, como my-agent-cuzvas-memory.
agentbricks deploy crea almacenes que faltan y otorga acceso al agente, así que la mayoría de los agentes pueden saltarse este paso.
Para usar un almacén diferente, vincúlelo por nombre. Cada comando reemplaza el nombre de la tienda en agent.toml. No se crea la tienda. Para vincular un almacén de sesión nombrado my-agent-sessions y un almacén de memoria nombrado my-agent-memory, ejecuta lo siguiente:
agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory
Para iniciar el agente con memorias ya en el almacén, cree el almacén y añada entradas antes de implementar. Consulta la pestaña de CLI de Agent Bricks en Empezar con la memoria del agente.
Paso 4: Ver seguimiento
El trazado está activado por defecto.
agentbricks init vincula un experimento de MLflow por defecto /Shared/agentbricks_traces/<project>-<suffix> y agentbricks dev y agentbricks deploy envían las trazas de cada ejecución a él.
Para listar trazas después de que tu agente haya presentado algunas, ejecuta lo siguiente:
agentbricks tracing list
Para vincular un experimento MLflow específico, ejecuta agentbricks tracing bind --experiment-id <experiment-id>. Para desactivar el trazado, ejecuta agentbricks tracing unbind.
Paso 5: Gestiona el agente localmente
Ejecuta el agente en tu máquina para probarlo antes de desplegarlo.
agentbricks dev
Esto inicia un servidor local en el puerto 8000 usando el mismo comando y entorno que el runtime del agente de Azure Databricks. La CLI de Agent Bricks conecta el agente al servicio de model serving de Azure Databricks para que pueda invocar el modelo localmente. La plantilla establece un modelo predeterminado como el valor de MODEL en agent/agent.py. Para usar un modelo diferente, edita ese valor. Envía solicitudes a http://localhost:8000 para interactuar con el agente.
Note
agentbricks dev No se conecta a memoria ni a los almacenes de sesión. La memoria a largo plazo está desactivada y el historial de conversaciones solo dura mientras el servidor local está en funcionamiento. La aplicación de chat muestra Not connected para la memoria localmente aunque haya un almacén vinculado. La memoria se conecta tras agentbricks deploy.
Paso 6: Desplega el agente
Despliega el agente en el runtime del agente de Azure Databricks. La CLI aprovisiona los almacenes asociados, concede al principal de servicio del agente acceso a estos y realiza la implementación. El agente desplegado se denomina agent-bricks-<name>.
agentbricks deploy my-agent
Cuando termina el despliegue, la CLI devuelve la URL del despliegue. Abre esa URL para interactuar con tu agente en vivo, que está conectado automáticamente a Azure Databricks model serving. Para gestionar el despliegue posterior, utiliza los agentbricks deployments comandos, como agentbricks deployments logs y agentbricks deployments stop.
El primer despliegue tarda unos minutos, principalmente para iniciar la capacidad de cómputo de la app. Los despliegues posteriores son más rápidos. Si el despliegue expira o la URL no responde, consulta El despliegue expira o la URL no responde. Para errores MCP_USER_AUTH_REQUIRED al llamar al agente desplegado, consulta Solución de problemas.
Trae un agente existente
Si ya creó un agente con LangGraph o el SDK de OpenAI Agents, utilice el marcador --existing para moverlo a la CLI de Agent Bricks y a DurableAgentServer. La CLI no reescribe tu código. En su lugar, prepara instrucciones de migración que un agente codificador, como Claude Code o Codex, sigue para convertir el proyecto.
Paso 1: Preparar la migración
Desde el directorio del proyecto del agente, prepara la migración. Pásame el framework que usa el agente: langgraph para LangGraph o openai para el SDK de Agentes OpenAI.
agentbricks init --framework langgraph --existing .
La CLI escribe un directorio agent-bricks-migrate/ que contiene las instrucciones de migración, un prompt para tu agente de codificación y un proyecto de referencia generado a partir de las plantillas de la CLI. También agrega aptitudes en .claude/skills/ y .agent/skills/ que apuntan a los agentes de codificación hacia las instrucciones. El comando no cambia el código de tu aplicación, las dependencias ni el archivo .env, y no crea recursos en tu espacio de trabajo.
Paso 2: Convierte el proyecto con tu agente de codificación
Pega el prompt de agent-bricks-migrate/ en tu agente de programación. El agente de codificación convierte el proyecto para que use agent.toml y un punto de entrada de DurableAgentServer y verifica la conversión.
Paso 3: Revisa la conversión
Ejecuta agentbricks doctor en el directorio del proyecto:
agentbricks doctor .
agentbricks doctorinspecciona los archivos del proyecto sin ejecutar su código ni contactar con Azure Databricks. Lo consigue cuando el proyecto tiene un agent.toml válido, inicia DurableAgentServer con un controlador de invocación y llama al adaptador para su marco. Un informe con error significa que la conversión no se ha completado.
Paso 4: Limpiar, ejecutar y desplegar
Elimine agent-bricks-migrate/ y las dos aptitudes que apuntan a él, y manténgalos fuera de sus confirmaciones. Luego ejecuta el agente con agentbricks dev y despliégalo con agentbricks deploy.
Considerations
-
--existingsoporta LangGraph y el SDK de Agentes OpenAI conDurableAgentServer. No admite--server custom. - Cambiar el agente a un almacén de sesiones gestionado no mueve su historial de conversaciones existente. Las instrucciones de migración te piden que decidas cómo manejar conversaciones anteriores.
- Las
--disable-chat-appopciones ,--memory-store, y--session-storemoldean el proyecto de referencia. No crean recursos.
Añadir herramientas MCP
Si construyes tu agente con la CLI de Agent Bricks, añade un servicio MCP a tu proyecto con agentbricks tools add mcp <catalog>.<schema>.<service>. El comando acepta cualquier Servicio MCP en tu espacio de trabajo al que puedas acceder, incluyendo servicios integrados system.ai y servicios MCP en otros catálogos y esquemas. El comando comprueba que el servicio existe en tu espacio de trabajo y registra la herramienta en agent.toml. El agente se conecta a la herramienta en tiempo de ejecución, así que no escribes ningún código de conexión.
Para listar los servicios MCP integrados system.ai que puedes añadir, ejecuta el siguiente comando:
agentbricks tools list --kind mcp
Para listar los servicios MCP en otro esquema, ejecute agentbricks tools list --kind mcp --schema <catalog>.<schema>.
Los siguientes ejemplos añaden servicios integrados comunes:
# 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
Para añadir un Servicio MCP de otro catálogo y esquema, como un servidor MCP externo, pasa su nombre de tres partes. La --name opción establece el ID de la herramienta en agent.toml:
agentbricks tools add mcp main.tools.ticket_search --name tickets
Por defecto, una herramienta se ejecuta con los permisos del usuario que envió la solicitud a tu agente. Para ejecutarlo como el principal de servicio de la app, añade --auth app. Para Google Drive, Gmail, Google Calendar y Microsoft 365, cada usuario realiza un inicio de sesión OAuth único antes de la primera llamada. Ver Aplicaciones conectadas.
Para revisar o eliminar herramientas, ejecutar agentbricks tools list o agentbricks tools remove mcp <service>.
Para otras herramientas, véanse las siguientes páginas:
- Todos los servicios integrados y lo que hacen: MCPs proporcionados por Databricks.
- Registra tus propios servidores MCP externos: servidores MCP externos.
- El Catálogo de Unity funciona como herramienta: Crea herramientas de agente usando funciones del Catálogo de Unity.
- Un único Genie Agent seleccionado: servidor MCP de Genie Agent.
agent.toml Referencia
agent.tomles la fuente declarativa de verdad para los recursos gestionados por Azure Databricks que utiliza tu agente.
agentbricks init lo crea, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, y agentbricks tracing bind lo actualiza, y agentbricks deploy lo lee para aprovisionar recursos y conceder acceso. También puedes editarlo directamente.
| Sección o campo | Description |
|---|---|
schema_version |
La versión del formato agent.toml. Los proyectos generados utilizan 1. |
[agent]
framework
|
La plantilla de marco: langgraph o openai. |
[agent]
server
|
El servidor agente: agentbricks para DurableAgentServer, o custom para tu propio servidor. |
[memory_store]
name
|
El almacén de memoria gestionado que utiliza el agente. |
[session_store]
name
|
El almacén de sesiones gestionado que utiliza el agente. |
[tracing]
experiment_name
|
El experimento MLflow para trazas. Elimine la sección para desactivar el seguimiento. |
[[tools]] |
Un enlace de herramienta. Cada herramienta tiene un id, un valor de user o app para auth, y un source que identifica la herramienta, más un opcional policy. |
[auth.user] |
Autorización de solicitud de usuario para las herramientas que escriba en el código: required y additional_api_scopes. Consulte Autorización de solicitud de usuario. |
El ejemplo siguiente es el archivo que agentbricks init genera para un agente de LangGraph llamado 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"
El sufijo aleatorio (cuzvas en este ejemplo) es diferente para cada proyecto, por lo que los proyectos con el mismo nombre no comparten almacenes ni experimentos.
El siguiente ejemplo muestra asignaciones de herramientas que agentbricks tools add escriben: un servicio MCP integrado, un agente Genie y un sandbox:
[[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" }
Las herramientas que llaman a una función del Catálogo de Unity usan auth = "app" y solo admiten source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" }.
Referencia de comandos
La siguiente tabla enumera los comandos CLI de Agent Bricks.
| Command | Description |
|---|---|
agentbricks login |
Autentica un perfil y guárdalo como predeterminado. |
agentbricks logout |
Olvida el perfil guardado predeterminado sin borrar sus credenciales. |
agentbricks init |
Genera la estructura de un nuevo proyecto de agente, o prepara un agente existente para la migración con --existing. |
agentbricks doctor |
Comprueba que un agente existente esté configurado para la CLI de Agent Bricks. |
agentbricks dev |
Ejecuta el agente localmente con una interfaz de chat. |
agentbricks memory |
Gestionar la memoria a largo plazo: vincular o desvincular un repositorio, y gestionar repositorios, registros y canalizaciones de memoria. |
agentbricks sessions |
Gestiona las sesiones de conversación: vincula o desvincula un almacén y gestiona los almacenes de sesión. |
agentbricks tools |
Enumera, añade y elimina las herramientas del agente. |
agentbricks mcp |
Descubre los servicios MCP gestionados. |
agentbricks tracing |
Vincular, desvincular e inspeccionar el rastreo. |
agentbricks deploy |
Despliega el agente en el runtime del agente de Azure Databricks. |
agentbricks deployments |
Gestionar los agentes desplegados: list, get, wait, logs, start, stop, , y delete. |
agentbricks endpoint |
Invocar un endpoint HTTP. |
agentbricks experimental |
Comandos experimentales que podrían cambiar sin avisar: experimental models y experimental prompts. |
Para cada bandera y opción, consulta la referencia del comando CLI de Agent Bricks en GitHub.
Troubleshooting
El despliegue falla porque el espacio de trabajo ha alcanzado su límite
Los almacenes de memoria gestionada y los almacenes de sesión tienen cada uno un límite por espacio de trabajo. Si agentbricks deploy falla con Workspace has reached the maximum of <N> managed memory stores, haz una de las siguientes acciones, luego vuelve a ejecutar agentbricks deploy:
- Libera una ranura. Corre
agentbricks memory stores list --alla buscar tiendas que ya no necesitas y luego elimínalas conagentbricks memory stores delete <name>. Para los almacenes de sesiones, ejecutaagentbricks sessions stores listy elimina almacenes no utilizados conagentbricks sessions stores delete <name>. - Desplegar sin almacén. Para un límite del almacén en memoria, ejecuta
agentbricks memory unbind. Para un límite de almacenamiento de sesiones, ejecutaagentbricks sessions unbind. El agente entonces se ejecuta sin esa memoria a largo plazo ni historial de conversación.
El despliegue expira o la URL no responde
Si despliegas desde un script o un agente de codificación con un corto tiempo de espera de comando, despliega sin esperar y luego espera por separado:
agentbricks deploy my-agent --no-wait
agentbricks deployments wait agent-bricks-my-agent
Por defecto, agentbricks deployments wait finaliza después de unos 100 segundos. Sus códigos de salida son:
-
0: El agente está desplegado y en funcionamiento. -
1: El despliegue falló. Deje de reintentarlo. Comprueba el error y la salida deagentbricks deployments logs agent-bricks-my-agent. -
75: El despliegue sigue en marcha. Ejecuta el mismo comando otra vez.
En un script que usa set -e, el código de salida 75 detiene el script, así que vuelve a intentarlo solo en 75:
while true; do
agentbricks deployments wait agent-bricks-my-agent && break
status=$?
[ "$status" -eq 75 ] || exit "$status"
done
Si el despliegue falla porque el cálculo de la app no se ha iniciado a tiempo, ejecuta agentbricks deployments get agent-bricks-my-agent para comprobar el estado de la app. Si la app está detenida, ejecuta agentbricks deployments start agent-bricks-my-agent. Luego vuelve a ejecutar agentbricks deploy my-agent.
Las solicitudes al agente desplegado fallan con MCP_USER_AUTH_REQUIRED
Si una herramienta MCP utiliza auth = "user", el agente desplegado requiere que Databricks Apps reenvíe el token del usuario iniciado sesión. Esto se aplica a todas las solicitudes, incluidas las indicaciones que no llaman a la herramienta. Las solicitudes que usan directamente un bearer token, como llamadas a curl o trabajos de CI, fallan con MCP_USER_AUTH_REQUIRED.
Para llamar al agente programáticamente, añade la herramienta con --auth app, por ejemplo agentbricks tools add mcp system.ai.dbsql --auth app. Para cambiar una herramienta existente, elimínala con agentbricks tools remove mcp <service>, añádela de nuevo con --auth app, y vuelve a desplegar.
La instalación falla en un Mac Intel mientras se compila cryptography
Si la instalación falla en un Mac Intel mientras compilas el cryptography paquete desde el código fuente, instala paquetes precompilados en su lugar. Para instalar con pip, ejecuta lo siguiente:
pip install --only-binary :all: databricks-agentbricks
La instalación o agentbricks dev falla por la versión de Python
Si la instalación o agentbricks dev fallan al compilar las dependencias, compruebe su versión de Python con python3 --version. Los proyectos estructurados requieren Python 3.11 o superior, y Databricks recomienda Python 3.12. En las versiones más recientes de Python, algunas dependencias pueden no tener paquetes precompilados. Para instalar la CLI con Python 3.12, ejecuta lo siguiente:
uv tool install --python 3.12 databricks-agentbricks
Recursos adicionales
- Agentes de consulta: Consulta a un agente que utiliza
DurableAgentServer. - Desplegar agentes: Desplegar agentes en Azure Databricks.
- Conectar a modelos: Consulta modelos fundacionales y de incrustación.
- Preguntas frecuentes sobre Agent Bricks: Preguntas frecuentes sobre Agent Bricks.
- Herramientas para agentes y servicios MCP: MCPs.
- Conceptos y API de la memoria del agente: Memoria del agente.
- Conceptos de sesiones de agente y API: sesiones de agente.
- Destila el historial de sesiones en memoria a largo plazo: pipelines de memoria de agentes.
- Trazabilidad de MLflow para agentes: Descripción general de la trazabilidad.