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.

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.

1. En el área de trabajo de Databricks, haga clic en + Nueva>aplicación.

2. Haga clic en Agentes>Agente - SDK de OpenAI Agents.

3. Cree un nuevo experimento de MLflow con el nombre openai-agents-template y complete el resto de la configuración para instalar la plantilla.

4. 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:

1. Copie el primer comando en Sincronizar los archivos.

   

2. En un terminal local, ejecute el comando copiado.

Clonar 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:

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

MLflow AgentServer

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 /invocations 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.

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 creación con tipo: escriba código de agente mediante clases de Python con tipo, que se benefician del IDE y la acción de autocompletar para los 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.

Temas de creación avanzados

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

import mlflow
# Define the retriever's schema by providing your column names
# For example, the following call specifies the schema of a retriever that returns a list of objects like
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist machine learning practitioners...',
#         'doc_uri': 'https://mlflow.org/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is to use the autologging feature. Autologging automatically logs your model...',
#         'doc_uri': 'https://mlflow.org/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="mlflow_docs_vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="document_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="chunk_text",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
    # Specify any other columns returned by the retriever
    other_columns=["title"],
)

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

Configure el entorno local:

1. Instale uv (administrador de paquetes de 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

2. Cambie el directorio a la agent-openai-agents-sdk carpeta .

3. 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 empezar a chatear con el agente.

Paso 4. Configurar la autenticación

El agente necesita autenticación para acceder a los recursos de Databricks. Databricks Apps proporciona dos métodos de autenticación:

Autorización de aplicaciones (valor predeterminado)

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

Conceda permisos al experimento de MLflow:

1. Haga clic en Editar en la página principal de la aplicación.
2. Vaya al paso Configurar .
3. En la sección Recursos de la aplicación, agregue el recurso del experimento de MLflow con Can Edit permiso.

Para otros recursos (Búsqueda de vectores, espacios de Genie, puntos de conexión de servicio), agréguelos de la misma manera en la sección Recursos de la aplicación.

Consulte Autorización de aplicaciones para obtener más información.

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 al 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)

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

Configurar ámbitos: Agregue ámbitos de autorización en la interfaz de usuario de Databricks Apps para definir a qué API puede acceder el agente en nombre de los usuarios.

Consulte Autorización de usuario para obtener instrucciones de configuración completas.

Paso 5. 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 6. Despliegue el agente en aplicaciones de Databricks

Después de configurar la autenticación, implemente el agente en Databricks. Asegúrese de que tiene instalada y configurada la CLI de Databricks .

1. Si ha clonado el repositorio localmente, cree la aplicación Databricks antes de implementarlo. Si ha creado la aplicación a través de la interfaz de usuario del área de trabajo, omita este paso, ya que la aplicación y el experimento de MLflow ya están configurados.

   databricks apps create agent-openai-agents-sdk
   

2. Sincronice los archivos locales en el área de trabajo. Consulte Implementación de la aplicación.

   DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
   databricks sync . "/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk"
   

3. Implemente la aplicación de Databricks.

   databricks apps deploy agent-openai-agents-sdk --source-code-path /Workspace/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk
   

Para actualizar el agente en el futuro, sincroniza y vuelve a desplegar el agente.

Paso 7. Consulta del agente implementado

Los usuarios consultan el agente implementado mediante tokens de OAuth. Los tokens de acceso personal (PAT) no se admiten para las aplicaciones de 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>/invocations \
   -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 del tamaño de proceso para una aplicación de Databricks.