Implementar agentes de IA con Databricks: guía práctica completa

Informatec Digital » Recursos » Implementar agentes de IA con Databricks: guía práctica completa

Montar agentes de inteligencia artificial en Databricks ya no es terreno exclusivo de perfiles ultra técnicos: entre entornos visuales como AI Playground, automatización con Agent Bricks y los marcos de MLflow, hoy puedes pasar de idea a prototipo y de prototipo a producción sin morir en el intento. En esta guía condensamos todo lo que necesitas para crear, evaluar y desplegar agentes que llamen herramientas, consulten datos y se integren con la gobernanza de Unity Catalog.

Además de recorrer el enfoque “sin código” y el desarrollo con Python, verás cómo empaquetar agentes con MLflow (ChatAgent y ResponsesAgent), registrar recursos en el catálogo, activar monitorización en tiempo real y escalar en Model Serving. También incluimos un ejemplo de app con React + FastAPI para llevar tu agente a una interfaz web empresarial sin fricciones.

Opciones para crear agentes en Databricks

Si prefieres velocidad y simplicidad, Agent Bricks aporta un flujo automatizado para levantar sistemas de agentes de alta calidad alineados a un dominio. Indicas el caso de uso y conectas tus datos del Catálogo Unity; la plataforma genera variantes de agente, optimiza con evaluación y te permite refinar, todo con gobernanza y seguridad integradas.

Cuando necesitas control fino y reutilizar librerías conocidas, el enfoque en código combina Mosaic AI Agent Framework y MLflow. Con Python puedes definir la lógica del agente, habilitar llamadas a herramientas, realizar seguimiento detallado y, finalmente, empaquetar y servir en producción con el ecosistema de Databricks.

Si ya utilizas frameworks de terceros, hay soporte nativo para LangGraph/LangChain, LlamaIndex o implementaciones personalizadas de Python. Gracias a las firmas de modelos de MLflow y a las interfaces de agente, puedes enchufarlos a las capacidades de evaluación y monitorización sin reescribir desde cero.

¿Quieres prototipar a toda velocidad? Con AI Playground eliges el modelo y la máquina virtual, añades herramientas al LLM mediante una interfaz de bajo código y chateas para validar. Después, exportas el agente a código listo para producción y continúas con el ciclo de vida estándar.

Firmas de modelo y compatibilidad con las características de la plataforma

Azure Databricks utiliza firmas de modelo de MLflow para describir el esquema de entrada y salida de los agentes. Funcionalidades del producto —como AI Playground o la evaluación— esperan que el agente cumpla una de las firmas admitidas para asegurar la interoperabilidad.

Si sigues el enfoque recomendado al construir el agente, MLflow infiere automáticamente la firma compatible sin pasos extra. En caso contrario, verifica que tu implementación se ajuste a alguna de las firmas del esquema heredado para entrada y salida de agentes, evitando sorpresas al integrar con herramientas de Databricks.

Tutorial rápido: primer agente con Mosaic AI Agent Framework

El objetivo es levantar un agente que razone con un LLM hospedado en Databricks y pueda ejecutar herramientas, por ejemplo la función integrada system.ai.python_exec del Catálogo Unity para correr código Python. Además, activaremos el seguimiento con MLflow para inspeccionar trazas y diagnósticos.

Requisitos básicos del workspace: habilitar las características de agentes y disponer de acceso a Model Serving. En el entorno de ejecución, instala paquetes como mlflow, databricks-openai y el empaquetador de agentes (databricks-agent o databricks-agents, según la guía que sigas y la versión), y reinicia Python para cargar dependencias.

Define la conexión al servicio de modelos mediante el cliente OpenAI que expone WorkspaceClient, activa mlflow.openai.autolog() para instrumentación automática, y registra las herramientas disponibles. Entre ellas, system.ai.python_exec sirve como intérprete de Python sin estado y permite que el LLM resuelva cálculos o manipule datos durante el diálogo.

Con una función tipo run_agent(), envías el prompt del usuario al endpoint de chat (por ejemplo, un modelo como «databricks-claude-3-7-sonnet«) y gestionas posibles llamadas a herramientas devolviendo los mensajes del asistente y las respuestas de herramienta en un listado coherente.

Para probar, lanza una consulta que requiera código (p. ej., calcular el número 100 de Fibonacci) y revisa tanto la salida del asistente como las trazas de MLflow que se registran en el cuaderno o experimento asociado. Así podrás pulir la orquestación antes de empaquetar.

Empaquetado con MLflow y despliegue en Model Serving

Una forma recomendada de preparar el agente para producción es implementando la interfaz MLflow ChatAgent. Necesitas un método predict() que acepte mensajes, llame a tu lógica del agente y devuelva un ChatAgentResponse con la lista de mensajes (incluyendo los intermedios asociados a herramientas si aplica).

Para facilitar la servidumbre, consolida todo el código en un único archivo Python (por ejemplo, mediante %%writefile quickstart_agent.py si trabajas en un notebook). En la parte final, llama a mlflow.models.set_model() pasando la instancia de tu clase (p. ej., QuickstartAgent) para establecer el punto de entrada de inferencia.

Registra el agente en Unity Catalog con mlflow.pyfunc.log_model, incluyendo los recursos que necesitará en producción: el endpoint del modelo LLM (p. ej., DatabricksServingEndpoint) y las funciones de catálogo que el agente invocará (p. ej., DatabricksFunction con system.ai.python_exec). Así, Databricks puede configurar autenticación para estos recursos al desplegar.

Por último, usa la API de agentes para desplegar el modelo a un endpoint de servicio: from databricks import agents y agents.deploy(model_name, model_version). Cuando arranque el endpoint, podrás chatear desde AI Playground, compartirlo con interesados y empezar a recolectar feedback.

Si quieres continuar mejorando, Databricks ofrece guías para medición de la calidad del agente, construcción de agentes con recuperación (RAG) sobre datos no estructurados y control de conversaciones multi-turno, además de alternativas con LangGraph, Python puro u OpenAI.

ResponsesAgent: la interfaz moderna para agentes de producción

Aunque ChatAgent funciona bien, MLflow recomienda hoy ResponsesAgent para agentes en serio. Esta interfaz es compatible con el esquema Responses de OpenAI y permite integrar agentes de cualquier framework con las capacidades de Databricks (registro, seguimiento, evaluación, despliegue y observabilidad) sin fricciones.

Ventajas clave: soporte nativo para sistemas multiagente, salida en modo streaming, historial completo de mensajes y llamadas a herramientas, confirmación de tool-calls y herramientas de larga duración. Además, ofrece interfaces tipadas en Python, inferencia automática de firma, seguimiento automático de predict y predict_stream y tablas de inferencia mejoradas vía AI Gateway.

Requisitos de instalación para este enfoque: databricks-agents 1.2.0+, mlflow 3.1.3+ y Python 3.10+ (usando Serverless o Databricks Runtime 13.3 LTS+). Databricks recomienda, además, los paquetes de AI Bridge para integraciones comunes.

Integraciones útiles: databricks-openai (OpenAI), databricks-langchain (LangChain/LangGraph), databricks-dspy (DSPy) y databricks-ai-bridge (agentes en Python puro). Con estas piezas, puedes montar desde agentes sencillos hasta pipelines complejos con recuperación y llamada a herramientas.

Si ya tienes un agente hecho, envuélvelo en una clase que herede de mlflow.pyfunc.ResponsesAgent. Implementa predict para convertir las entradas y salidas al esquema ResponsesAgent. Para streaming, apóyate en predict_stream, emitiendo deltas y un evento final response.output_item.done que agregue la respuesta completa.

Sobre los errores en streaming, Mosaic AI propaga el fallo junto al último token dentro de databricks_output.error. Tu cliente debería capturarlo y mostrarlo correctamente, mejorando la experiencia de depuración.

Recuperadores, inputs personalizados y trazabilidad

Muchos agentes utilizan recuperadores para RAG sobre índices vectoriales. Si tus spans de recuperación exponen un esquema distinto, puedes mapearlo con mlflow.models.set_retriever_schema, declarando primary_key, text_column, doc_uri y otras columnas. Así, AI Playground mostrará vínculos a fuentes recuperadas y la evaluación aplicará puntuadores de relevancia automáticamente.

En casos donde tu agente requiera información adicional (por ejemplo, client_type o session_id), usa custom_inputs y devuelve metadatos en custom_outputs que no deben contaminar el historial de chat. Tanto AI Playground como la aplicación de revisión permiten introducir custom_inputs desde la UI.

Despliegue con deploy(), requisitos y acciones automáticas

Para publicar tu agente en Mosaic AI Model Serving, utiliza la función deploy() de la API de Python. En MLflow 3, instala mlflow >= 3.1.3 y databricks-agents >= 1.1.0 (si despliegas fuera de notebooks). En MLflow 2.x, los mínimos cambian (por ejemplo, mlflow >= 2.13.1 y databricks-agents >= 0.12.0). Asegúrate de registrar el agente en Unity Catalog antes de desplegar.

Llamar a deploy() levanta un endpoint escalable con balanceo automático, configura la autenticación segura para recursos de Databricks (índices vectoriales, funciones de catálogo) —comprobando permisos del propietario—, y activa la aplicación de revisión para colaboración con stakeholders.

También habilita el seguimiento en tiempo real en MLflow (con trazas en el experimento activo y en tablas de inferencia). En MLflow 3, puede configurarse supervisión de producción con evaluación automática de calidad; las peticiones REST y comentarios quedan registrados en las tablas de inferencia (con APIs modernas de feedback).

Para personalizar, pasa argumentos a deploy() como scale_to_zero_enabled=True, reduciendo costes tras inactividad a costa de mayor latencia en el primer request. Además, cuentas con utilidades para listar, obtener y borrar despliegues a través de la API de agentes.

Buenas prácticas de estado, configuración y patrones de ejecución

Model Serving es distribuido: evita cachés locales y asume que diferentes réplicas pueden atender distintos turnos de una conversación. Reconstruye el estado a partir del diccionario de ResponsesAgentRequest en cada predict y diseña el estado para que sea thread-safe.

Inicializa el estado dentro de predict y no en el constructor del agente, ya que una única réplica podría manejar conversaciones de distintos usuarios. Esto previene fugas de información y conflictos de concurrencia en entornos con alto throughput.

Parametriza el comportamiento del agente con ModelConfig (diccionario o YAML). Define, por ejemplo, model_serving_endpoint, parámetros del LLM y plantillas de prompts; carga esa configuración en desarrollo y promociónala a producción sin tocar el código.

Evita introducir bucles de eventos o marcos asíncronos en el servidor del agente: Databricks gestiona la concurrencia internamente. Usa código sincrónico o callbacks; de lo contrario, podrías toparte con errores del tipo «This event loop is already running» y comportamientos erráticos.

Agent Bricks: automatización «no code» para acelerar el valor

Agent Bricks, presentado en 2025, ofrece un flujo de creación de agentes sin necesidad de escribir código. Introduces la tarea en lenguaje natural, conectas tus datos y la plataforma elige modelos, genera datos sintéticos, evalúa y ajusta hasta entregar un agente listo para producción con la gobernanza de Unity Catalog.

Entre sus ventajas destacan la automatización end-to-end, la escalabilidad en Databricks —con endpoints que pueden escalar a cero tras 3 días de inactividad—, analítica de uso y costes sobre Lakehouse y tipos de agentes listos (extracción de información, LLM personalizado, asistente de conocimiento y supervisor multiagente para orquestación compleja).

Como limitaciones, hoy el código generado no es descargable, lo que reduce la personalización profunda, y el catálogo de plantillas se orienta a organizaciones ya integradas con Lakehouse y Unity Catalog. Algunos usuarios echan en falta más granularidad en métricas de coste.

Ejemplos, multiagente y agentes con estado

En la documentación oficial encontrarás cuadernos con OpenAI (chat simple y llamada a herramientas, tanto con modelos hospedados en Databricks como en OpenAI), LangGraph (invocación de herramientas) y DSPy (llamada a herramientas en un turno). Son bases estupendas para extender con herramientas personalizadas y evaluaciones de calidad.

Para orquestar varios especialistas, puedes montar sistemas que cooperen usando piezas como Genie. Y si te interesa la memoria por conversación, hay soporte para agentes con estado que permiten checkpoints y persistencia por hilo de chat.

En la documentación oficial encontrarás cuadernos con OpenAI (chat simple y llamada a herramientas, tanto con modelos hospedados en Databricks como en OpenAI), LangGraph (invocación de herramientas) y DSPy (llamada a herramientas en un turno). Son bases estupendas para extender con herramientas personalizadas y evaluaciones de calidad.

Apps en Databricks: UI con React y backend en FastAPI

Las Databricks Apps proporcionan una plataforma robusta para entregar interfaces ricas sin montar infraestructura externa. Se integran de forma nativa con Databricks SQL, Unity Catalog, Model Serving, Jobs y heredan controles de seguridad y cumplimiento de la plataforma.

Un patrón muy práctico es crear un frontend con React (soporte de streaming, render de mensajes, UX con Markdown) y un backend con FastAPI que actúe de puente hacia el endpoint del agente. El backend enruta la petición del usuario al servicio de modelos y devuelve la respuesta estructurada al cliente.

En FastAPI, el orden de montaje de subaplicaciones es importante: app.mount("/api", api_app) dirige las rutas de API (por ejemplo, /api/chat) y app.mount("/", ui_app) sirve los estáticos del build de React en la raíz. Este esquema mantiene claridad de rutas y separa UI de endpoints.

Configura variables de entorno (p. ej., SERVING_ENDPOINT_NAME o el FQN del modelo de agente en Unity Catalog) desde la definición de la app en Databricks. Compila el frontend (npm run build), sincroniza archivos, declara dependencias (requirements.txt) y arranca con Gunicorn + Uvicorn workers para ASGI.

Caso real: chatbot para operaciones de fabricación

En escenarios MOM (Manufacturing Operations Management), un chatbot sobre Databricks puede ayudar a jefes de producción con análisis de cuellos de botella, seguimiento de inventario y generación de informes. Las funciones se exponen como herramientas en Unity Catalog (via SQL o Python) y el agente las invoca según el contexto.

Ejemplos: una función identify_bottleneck_station ejecuta consultas en Databricks SQL para detectar la etapa que provoca más retrasos; otra, check_inventory_levels, devuelve stock en tiempo real. El agente puede además enviar correos, producir informes y realizar análisis de sentimiento, todo orquestado con tool-calls.

El despliegue como endpoint de Model Serving actúa como backend estándar. La app React consume ese endpoint, mostrando respuestas en tiempo real con una experiencia cuidada y soporte de streaming de tokens cuando lo habilites en tu ResponsesAgent.

Migración desde ChatCompletions y compatibilidad

Si tu agente heredado usa la API de ChatCompletions de OpenAI, puedes migrar a ResponsesAgent con un contenedor que traduzca mensajes entrantes/salientes y, opcionalmente, mapee los deltas de streaming a ResponsesAgentStreamEvent. Así modernizas telemetría y observabilidad sin reescribir la lógica central.

Para el listado y gestión de despliegues, la API de agentes te permite listar lo existente, obtener un despliegue concreto (por nombre y versión) y eliminar endpoints que ya no necesitas. Recuerda gestionar credenciales de recursos externos con variables de entorno y secretos.

Databricks ofrece una ruta completa: desde ideación con AI Playground o automatización con Agent Bricks, pasando por desarrollo en código (Mosaic AI, MLflow, LangGraph, DSPy), hasta empaquetado, registro en Unity Catalog, despliegue con deploy() y monitorización en producción. Con prácticas como firmas de modelo correctas, estado seguro en entornos distribuidos y configuración parametrizada, puedes entregar agentes fiables, gobernados y listos para integrarse en aplicaciones web sobre la plataforma.

Artículo relacionado:

Claude 4: Anthropic renueva la inteligencia artificial con modelos avanzados para programación y agentes autónomos