Creación de un agente de IA e implementación en Databricks Apps

Cree un agente de INTELIGENCIA ARTIFICIAL e impleméntelo mediante Aplicaciones de Databricks. Databricks Apps proporciona control total sobre el código del agente, la configuración del servidor y el flujo de trabajo de implementación. Este enfoque es ideal cuando se necesita el comportamiento del servidor personalizado, el control de versiones basado en Git o el desarrollo del IDE local.

Tip

Si el agente solo usa herramientas hospedadas Azure Databricks y no necesita lógica personalizada entre llamadas a herramientas, puede usar la API Supervisor (Beta) para permitir que Azure Databricks administre el bucle del agente automáticamente.

Vista previa de la interfaz de usuario del chat del agente

Cada plantilla de agente de conversación incluye una interfaz de usuario de chat integrada (mostrada anteriormente) sin ninguna configuración adicional necesaria. La interfaz de usuario de chat admite respuestas de streaming, representación de Markdown, autenticación de Databricks y historial de chat persistente opcional.

Requisitos

Habilite Databricks Apps en el área de trabajo. Consulte Configuración del área de trabajo y el entorno de desarrollo de Databricks Apps.

Paso 1. Clona la plantilla de la aplicación del agente

Empiece a usar una plantilla de agente precompilada desde el repositorio de plantillas de aplicación de Databricks.

En este tutorial se usa la agent-openai-agents-sdk plantilla, que incluye:

Un agente creado mediante el SDK del agente de OpenAI
Código de inicio para una aplicación de agente con una API REST conversacional y una interfaz de usuario de chat interactiva
Código para evaluar el agente mediante MLflow

Elija una de las siguientes rutas de acceso para configurar la plantilla:

Interfaz de usuario del área de trabajo

Instale la plantilla de aplicación mediante la interfaz de usuario del área de trabajo. Esto instala la aplicación y la implementa en un recurso de cómputo en el área de trabajo. Después, puede sincronizar los archivos de aplicación con el entorno local para su desarrollo posterior.

En el área de trabajo de Databricks, haga clic en + Nueva>aplicación.
Haga clic en Agentes>Agente personalizado (SDK de OpenAI).
Cree un nuevo experimento de MLflow con el nombre openai-agents-template y complete el resto de la configuración para instalar la plantilla.
Después de crear la aplicación, haga clic en la dirección URL de la aplicación para abrir la interfaz de usuario de chat.

Después de crear la aplicación, descargue el código fuente en la máquina local para personalizarla:

Copie el primer comando en Sincronizar los archivos.
En un terminal local, ejecute el comando copiado.

Clonación desde GitHub

Para empezar desde un entorno local, clone el repositorio de plantillas del agente y abra el agent-openai-agents-sdk directorio :

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Paso 2. Descripción de la aplicación del agente

La plantilla del agente muestra una arquitectura lista para producción con estos componentes clave. Abra las secciones siguientes para obtener más detalles sobre cada componente:

Diagrama sencillo del agente en la aplicación

Abra las secciones siguientes para obtener más detalles sobre cada componente:

Interfaz de usuario de chat integrado

La plantilla del agente captura y ejecuta automáticamente la plantilla de aplicación de chat como front-end. Esta interfaz de usuario de chat se incluye en la misma implementación de Databricks Apps y se proporciona junto con el agente, por lo que no se requiere ninguna configuración adicional.

Puede personalizar la interfaz de usuario de chat directamente en el proyecto. Para obtener más información sobre las características de la aplicación de chat, incluido cómo habilitar el historial de chat persistente y la recopilación de comentarios de usuarios, consulte Compilación y uso compartido de una interfaz de usuario de chat con Databricks Apps.

Servidor de Agente MLflow

Un servidor FastAPI asincrónico que controla las solicitudes del agente con seguimiento y observabilidad integrados. AgentServer proporciona el punto de conexión para consultar el /responses agente y administra automáticamente el enrutamiento de solicitudes, el registro y el control de errores.

ResponsesAgent interfaz

Databricks recomienda MLflow ResponsesAgent para compilar agentes. ResponsesAgent permite crear agentes con cualquier marco de terceros y, a continuación, integrarlos con las características de Inteligencia artificial de Databricks para lograr un registro sólido, seguimiento, evaluación, implementación y funcionalidades de supervisión.

ResponsesAgent ajusta fácilmente los agentes existentes para la compatibilidad de Databricks.

Para obtener información sobre cómo crear un ResponsesAgent, consulte los ejemplos de documentación de MLflow: ResponsesAgent for Model Serving.

ResponsesAgent proporciona las siguientes ventajas:

Funcionalidades avanzadas del agente
- Compatibilidad con varios agentes
- Salida de streaming: transmita la salida en fragmentos más pequeños.
- Historial completo de mensajes de llamada a herramientas: devuelve varios mensajes, incluidos los mensajes intermedios de llamada a herramientas, para mejorar la calidad y la administración de conversaciones.
- Compatibilidad con la confirmación de llamadas a herramientas
- Soporte para herramientas que han estado operativas a largo plazo
Desarrollo, implementación y supervisión simplificados
- Desarrolla agentes utilizando cualquier marco: Envuelve cualquier agente existente mediante la ResponsesAgent interfaz para obtener compatibilidad integrada con AI Playground, Agent Evaluation y Agent Monitoring.
- Interfaces de autoría tipificadas: Escribir código de agente mediante clases de Python tipificadas, beneficiándose del IDE y la función de autocompletar en entornos de trabajo y cuadernos.
- Seguimiento automático: MLflow agrega automáticamente respuestas transmitidas en seguimientos para facilitar la evaluación y visualización.
- Compatible con el esquema de OpenAI: consulte OpenAI: Respuestas vs. ChatCompletion.

SDK de agentes de OpenAI

La plantilla usa el SDK de agentes de OpenAI como marco de trabajo del agente para la administración de conversaciones y la orquestación de herramientas. Puede desarrollar agentes utilizando cualquier framework. La clave está en envolver tu agente con la interfaz MLflow ResponsesAgent.

Servidores MCP (Protocolo de contexto de modelo)

La plantilla se conecta a los servidores MCP de Databricks para proporcionar a los agentes acceso a herramientas y orígenes de datos. Consulte Protocolo de contexto de modelo (MCP) en Databricks.

Creación de agentes mediante asistentes de codificación de IA

Databricks recomienda usar asistentes de codificación de IA, como Claude, Cursor y Copilot para crear agentes. Utiliza las habilidades proporcionadas por el agente, en /.claude/skills y el archivo AGENTS.md para ayudar a los asistentes de inteligencia artificial a comprender la estructura del proyecto, las herramientas disponibles y los procedimientos recomendados. Los agentes pueden leer automáticamente esos archivos para desarrollar e implementar las aplicaciones de Databricks.

Paso 3. Añade herramientas a tu agente

Proporcione a los agentes funcionalidades como consultar bases de datos, buscar documentos o llamar a API externas mediante la conexión a servidores MCP. La plantilla del agente incluye una conexión de servidor MCP predeterminada. Para agregar más herramientas, configure servidores MCP adicionales en el código del agente y conceda los permisos necesarios en databricks.yml.

Consulte Herramientas del agente de IA para ver los tipos de herramientas y ejemplos de código admitidos.

Define herramientas de funciones locales de Python

Para las operaciones que no requieren orígenes de datos externos o API, defina herramientas directamente en el código del agente. Estas herramientas se ejecutan en el mismo proceso que el agente y son útiles para transformaciones de datos, cálculos o operaciones de utilidad.

SDK de agentes de OpenAI

Utiliza el decorador @function_tool del SDK de agentes de OpenAI.

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

Usa el @tool decorador de LangChain.

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

Las herramientas de funciones locales no requieren concesiones de recursos porque databricks.yml se ejecutan dentro del proceso del agente.

Paso 4. Gestión del uso de LLM por parte de los agentes en las aplicaciones de Databricks con Unity AI Gateway

Enrute las llamadas LLM del agente a través de AI Gateway (Beta), por lo que cada solicitud se rige por los mismos controles, independientemente de qué proveedor lo responda. Con el gateway en la ruta de acceso de solicitud, pueden centralizar los permisos, atribuir el costo por aplicación, intercambiar los modelos e inspeccionar o reproducir el tráfico sin necesidad de modificar el código de los agentes ni rotar las credenciales del proveedor.

Important

Esta característica se encuentra en su versión beta. Los administradores del área de trabajo pueden controlar el acceso a esta característica desde la página Vistas previas . Consulte Administrar versiones preliminares de Azure Databricks.

Habilite AI Gateway en el área de trabajo. AI Gateway es opcional durante la versión beta. Un administrador de cuenta debe activarlo desde la página Vista previa de la consola de cuenta para poder crear o consultar puntos de conexión de puerta de enlace. Consulte Administrar versiones preliminares de Azure Databricks.
Dirige tu agente hacia un punto de conexión de AI Gateway. En el código del agente, pase el nombre del punto de conexión de puerta de enlace de AI como argumento model y establezca use_ai_gateway=True en el cliente LLM de Azure Databricks. El cliente enruta el tráfico a través de la puerta de enlace y controla la autenticación automáticamente.

OpenAI
```
from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)
```
LangGraph
```
from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(
    model="<ai-gateway-endpoint>",
    use_ai_gateway=True,
)
```
Para obtener más interfaces de API (API de respuestas de OpenAI, API de mensajes de Anthropic, Google Gemini) y ejemplos de REST, consulte los puntos de conexión de la puerta de enlace de IA de Unity.

Temas de creación avanzados

Respuestas de transmisión

Respuestas de streaming

El streaming permite a los agentes enviar respuestas en fragmentos en tiempo real en lugar de esperar a que se complete la respuesta. Para implementar el streaming con ResponsesAgent, emita una serie de eventos delta seguidos de un evento de finalización final:

Emitir eventos delta: envíe varios output_text.delta eventos con el mismo item_id para transmitir fragmentos de texto en tiempo real.
Finalizar con evento terminado: envíe un evento final response.output_item.done con el mismo item_id que los eventos delta que contienen el texto de salida final completo.

Cada evento delta transmite un fragmento de texto al cliente. El evento final hecho contiene el texto de respuesta completo y indica a Databricks que haga lo siguiente:

Rastrea la salida de tu agente con el seguimiento de MLflow
Agregar respuestas transmitidas en tablas de inferencia de AI Gateway
Mostrar la salida completa en la interfaz de usuario del entorno de pruebas de IA

Propagación de errores de streaming

Mosaic AI propaga los errores detectados durante el streaming con el último token en databricks_output.error. Depende del cliente que realiza la llamada manejar y mostrar adecuadamente este error.

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Entradas y salidas personalizadas

Algunos escenarios pueden requerir entradas adicionales del agente, como client_type y session_id, o salidas como enlaces de fuentes de recuperación que no deben incluirse en el historial del chat para interacciones futuras.

En estos escenarios, MLflow ResponsesAgent admite de forma nativa los campos custom_inputs y custom_outputs. Puede acceder a las entradas personalizadas a través de request.custom_inputs en los ejemplos de marco anteriores.

La Agent Evaluation review app no admite la representación de trazas para agentes con campos de entrada adicionales.

Proporcione custom_inputs en el AI Playground y revise la aplicación

Si tu agente acepta entradas adicionales mediante el campo custom_inputs, puedes proporcionar manualmente estas entradas tanto en el AI Playground como en la Aplicación de Revisión.

En el AI Playground o la aplicación Agent Review, seleccione el icono de engranaje
Habilite custom_inputs.
Proporcione un objeto JSON que coincida con el esquema de entrada definido del agente.

Paso 5. Ejecución local de la aplicación del agente

Configure el entorno local:

Instale uv (administrador de paquetes Python), nvm (administrador de versiones de Node) y la CLI de Databricks:
- uv instalación
- nvm instalación
- Ejecute lo siguiente para usar Node 20 LTS:
```
nvm use 20
```
- databricks CLI instalación
Cambie el directorio a la agent-openai-agents-sdk carpeta .
Ejecute los scripts de inicio rápido proporcionados para instalar dependencias, configurar el entorno e iniciar la aplicación.
```
uv run quickstart
uv run start-app
```

En un navegador, vaya a http://localhost:8000 para abrir la interfaz de usuario de chat integrada y empezar a chatear con el agente.

Paso 6. Configurar la autenticación

El agente necesita autenticación para acceder a los recursos de Azure Databricks. Databricks Apps proporciona dos métodos de autenticación: autorización de aplicación (servicio principal) y autorización de usuario (en nombre del usuario). Puede configurar cualquiera de estos a través de la interfaz de usuario del área de trabajo o de manera declarativa en databricks.yml con Paquetes de Automatización Declarativa. Las plantillas de agente incluyen un databricks.yml, por lo que esa ruta es la predeterminada cuando se inicia desde una plantilla.

Para obtener la referencia completa, incluidos todos los tipos de recursos admitidos, los valores de permisos y un databricks.yml tutorial completo, consulte Autenticación para agentes de IA.

Autorización de aplicaciones (valor predeterminado)

La autorización de aplicaciones utiliza una entidad de servicio que Azure Databricks crea automáticamente para tu aplicación. Todos los usuarios comparten los mismos permisos.

Declare todos los recursos que usa el agente bajo resources.apps.<app>.resources en databricks.yml. Implemente el paquete para conceder al principal de servicio los permisos declarados.

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para obtener la lista completa de tipos de recursos, consulte Autorización de aplicaciones.

Autorización de usuario

La autorización de usuario permite al agente actuar con los permisos individuales de cada usuario. Úselo cuando necesite seguimientos de auditoría o control de acceso por usuario.

Agregue este código a su agente:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important

Inicialice get_user_workspace_client() dentro de las @invoke o las @stream funciones, no durante el inicio de la aplicación. Las credenciales de usuario solo existen al manejar una solicitud.

Configure qué APIs de Azure Databricks el agente puede invocar en nombre del usuario añadiendo ámbitos en user_api_scopes en la aplicación en databricks.yml:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para obtener la lista de ámbitos disponibles y completar las instrucciones de configuración, consulte Autorización de usuario.

Paso 7. Evaluación del agente

La plantilla incluye código de evaluación del agente. Consulte agent_server/evaluate_agent.py para obtener más información. Evalúe la relevancia y la seguridad de las respuestas del agente ejecutando lo siguiente en un terminal:

uv run agent-evaluate

Paso 8. Despliegue el agente en aplicaciones de Databricks

Después de configurar la autenticación, implemente el agente en Azure Databricks. Las plantillas de agente usan Conjuntos de activos (DAB) de Databricks para la implementación. El databricks.yml archivo de la plantilla define la configuración de la aplicación y los permisos de recursos. Asegúrese de que tiene instalada y configurada la CLI de Databricks .

Nota

Si creó la aplicación a través de la interfaz de usuario de Workspace en el paso 1, ejecute databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve antes de implementar para enlazar la aplicación existente a su paquete. De lo contrario, databricks bundle deploy se produce un error con "Ya existe una aplicación con el mismo nombre".

Valide la configuración de agrupación para detectar errores antes de implementar:
```
databricks bundle validate
```
Despliegue el paquete. Esto carga el código y configura los recursos (experimento de MLflow, servicios de puntos de conexión, etc.) definidos en databricks.yml:
```
databricks bundle deploy
```
Inicie o reinicie la aplicación:
```
databricks bundle run agent_openai_agents_sdk
```
Nota

bundle deploy solo carga archivos y configura los recursos. bundle run es necesario para iniciar o reiniciar la aplicación con el nuevo código.

Para futuras actualizaciones, ejecute databricks bundle deploy y, a continuación, databricks bundle run agent_openai_agents_sdk para volver a implementar.

Paso 9. Consulta del agente implementado

En el ejemplo siguiente se usa una solicitud rápida curl con un token de OAuth. Los tokens de acceso personal (PAT) no se admiten para las aplicaciones de Databricks.

Para obtener la lista completa de métodos de consulta, incluido el cliente openAI de Databricks y la API REST, consulte Query un agente implementado en Azure Databricks.

Genere un token de OAuth mediante la CLI de Databricks:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Use el token para consultar al agente:

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Limitaciones

Solo se admiten tamaños de cálculo medianos y grandes. Consulte Configuración de recursos de proceso para una aplicación de Databricks.
La interfaz de usuario de MLflow Review App Chat no admite actualmente agentes implementados en Aplicaciones de Databricks. Para evaluar los seguimientos existentes, use sesiones de etiquetado, que funcionan independientemente del método de implementación. Databricks está creando soporte de revisión y comentarios directamente en la plantilla de chatbot.

Pasos siguientes

Prueba de carga del agente de Databricks Apps

Oharrak

Lagungarria al da orri hau?

Last updated on 2026-05-03

Creación de un agente de IA e implementación en Databricks Apps

Requisitos

Paso 1. Clona la plantilla de la aplicación del agente

Interfaz de usuario del área de trabajo

Clonación desde GitHub

Paso 2. Descripción de la aplicación del agente

Creación de agentes mediante asistentes de codificación de IA

Paso 3. Añade herramientas a tu agente

Define herramientas de funciones locales de Python

SDK de agentes de OpenAI

LangGraph

Paso 4. Gestión del uso de LLM por parte de los agentes en las aplicaciones de Databricks con Unity AI Gateway

OpenAI

LangGraph

Temas de creación avanzados

Respuestas de streaming

Entradas y salidas personalizadas

Paso 5. Ejecución local de la aplicación del agente

Paso 6. Configurar la autenticación

Autorización de aplicaciones (valor predeterminado)

Autorización de usuario

Paso 7. Evaluación del agente

Paso 8. Despliegue el agente en aplicaciones de Databricks

Paso 9. Consulta del agente implementado

Limitaciones

Pasos siguientes

Oharrak

Baliabide gehigarriak