CLI de Agent Bricks

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.

La CLI de Agent Bricks es una ruta basada en código para construir agentes personalizados desde el terminal. 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.10 o superior, con pip.

• Instala la CLI de Agent Bricks:

  pip install databricks-agentbricks
  

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.toml es la fuente declarativa fiable para todos los recursos administrados por Azure Databricks de los que depende el agente: vinculaciones de herramientas (entorno aislado de datos, servicios gestionados de Model Context Protocol (MCP) y funciones de Unity Catalog) y recursos de memoria, sesión y trazado. agentbricks deploy lo lee para provisionar y conectar todo por cable, 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 init estructura el proyecto a partir de una plantilla agrupada, opcionalmente semiendo un .env archivo con un perfil Databricks para que el proyecto se ejecute de inmediato.
• agentbricks devEjecuta el agente localmente contra el modelo de servicio de Azure Databricks para que puedas probarlo antes de desplegarlo.
• agentbricks deployprovisiona los recursos declarados en agent.toml y 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. Utiliza la memoria para conservar los hechos y preferencias entre las sesiones. Consulte Memoria del agente administrado.
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 Sesiones de agentes gestionados.
Tools	Capacidades gestionadas por Azure Databricks declaradas en: agent.tomlun sandbox de Unity Catalog con alcance reducido, 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.

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 perfil en ~/.databrickscfg:

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

Para establecer ese perfil como el predeterminado de la CLI y que los comandos posteriores puedan omitir --profile, ejecuta lo siguiente:

agentbricks login --profile <profile>

agentbricks login valida las credenciales del perfil. Si faltan o son rechazados, la CLI vuelve a ejecutar databricks auth login y lo vuelve a intentar.

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

Vincula almacenes gestionados para que tu agente pueda conservar el historial de conversaciones y la memoria a largo plazo. Cada comando registra el nombre de la tienda en agent.toml y crea la tienda si no existe.

Para vincular un almacén de sesión y un almacén de memoria, ejecuta lo siguiente:

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

Paso 4: Ver seguimiento

El trazado está activado por defecto. agentbricks init vincula un experimento MLflow por defecto /Shared/agentbricks_traces/<project> y agentbricks devagentbricks deploy envía 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.

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.

Trae un agente existente

Si ya has creado un agente con LangGraph o el SDK de Agentes de OpenAI, usa la marca --existing para moverlo a la CLI de Agent Bricks y usar 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 añade habilidades en .claude/skills/ y .agent/skills/ que orientan 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 usar agent.toml y un punto de entrada 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. Se ejecuta correctamente cuando el proyecto tiene un agent.toml válido, comienza DurableAgentServer con un manejador de invocación y llama al adaptador para su framework. Un informe con error significa que la conversión no se ha completado.

Paso 4: Limpiar, ejecutar y desplegar

Elimina agent-bricks-migrate/ y las dos aptitudes que lo señalan, y mantenlas fuera de tus commits. Luego ejecuta el agente con agentbricks dev y despliégalo con agentbricks deploy.

Considerations

• --existing soporta LangGraph y el SDK de Agentes OpenAI con DurableAgentServer. 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-store moldean 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 integrado system.ai a tu proyecto con agentbricks tools add mcp. 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 que puedes añadir, ejecuta el siguiente comando:

agentbricks tools list --kind mcp

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

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.
• 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: Genie Agent MCP server (legacy).

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 actualizan, 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. Quite la selección para desactivar el trazado.
[[tools]]	Vinculación de herramientas 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]	Solicita autorización del usuario para herramientas que escribes en código: required y additional_api_scopes. Consulte "Solicitud de autorización de usuario".

El siguiente ejemplo es el archivo que genera agentbricks init para un agente LangGraph llamado my-agent:

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"

El siguiente ejemplo muestra asignaciones de herramientas que agentbricks tools add genera: un servicio MCP integrado, un agente Genie y un sandbox con alcance en una sola tabla:

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

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

Para consultar la referencia completa y actualizada de comandos, incluidos todos los comandos y opciones, consulte el README de la CLI de Agent Bricks en GitHub.

Recursos adicionales

• Herramientas para agentes y servicios MCP: MCPs.
• Conceptos de memoria y API de agentes gestionados: Memoria de agente gestionada.
• Conceptos y API de sesiones de agentes gestionados: Sesiones de agentes gestionados.
• Trazabilidad de MLflow para agentes: Descripción general de la trazabilidad.