Creación de agentes de IA en el código

En este artículo se muestra cómo crear un agente de INTELIGENCIA ARTIFICIAL en Python mediante El marco del agente de IA de Mosaico y bibliotecas populares de creación de agentes, como LangGraph, PyFunc y OpenAI.

Requisitos

Databricks recomienda instalar la versión más reciente del cliente de Python de MLflow al desarrollar agentes.

Para crear e implementar agentes mediante el enfoque de este artículo, debe tener las siguientes versiones mínimas del paquete:

• databricks-agents versión 0.16.0 y posteriores
• mlflow versión 2.20.2 y posteriores

%pip install -U -qqqq databricks-agents>=0.16.0 mlflow>=2.20.2

Databricks también recomienda instalar Databricks AI Bridge paquetes de integración al crear agentes. Estos paquetes de integración (como databricks-langchain, databricks-openai) proporcionan una capa compartida de API para interactuar con las características de inteligencia artificial de Databricks, como Databricks AI/BI Genie y Vector Search, entre marcos de creación de agentes y SDK.

LangChain/LangGraph

%pip install -U -qqqq databricks-langchain

OpenAI

%pip install -U -qqqq databricks-openai

Agentes puros de Python

%pip install -U -qqqq databricks-ai-bridge

Uso de ChatAgent para crear agentes

Databricks recomienda usar la interfaz ChatAgent de MLflow para crear agentes de nivel de producción. Esta especificación de esquema de chat está diseñada para escenarios de agente y es similar a, pero no es estrictamente compatible, con el esquema de ChatCompletion openAI. ChatAgent también agrega funcionalidad para agentes de llamada a herramientas de varios turnos.

La creación del agente mediante ChatAgent proporciona las siguientes ventajas:

• Funcionalidades avanzadas del agente

  • Transmisión de salida: Permita experiencias de usuario interactivas transmitiendo la salida en trozos 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 sistema multiagente

• Desarrollo, implementación y supervisión simplificados

  • Integración de características de Databricks independiente del marco: escriba el agente en cualquier marco de su elección y obtenga compatibilidad integrada con AI Playground, Evaluación del agente y Supervisión del agente.
  • 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.
  • inferencia automática de firmas: MLflow deduce automáticamente ChatAgent firmas al registrar el agente, lo que simplifica el registro y la implementación. Consulte Deducción de la firma del modelo durante el registro.
  • tablas de inferencia mejoradas por AI Gateway: las tablas de inferencia de AI Gateway se habilitan automáticamente para los agentes implementados, lo que proporciona acceso a metadatos detallados del registro de solicitudes.

Para obtener información sobre cómo crear un ChatAgent, consulte los ejemplos en la sección siguiente y la documentación de MLflow - ¿Qué es la interfaz de ChatAgent?

ejemplos de ChatAgent

En los cuadernos siguientes se muestra cómo crear ChatAgents de streaming y sin streaming mediante las bibliotecas populares de OpenAI y LangGraph.

Agente de llamada a herramientas de LangGraph

Obtener el cuaderno

Agente de llamada a herramientas de OpenAI

Obtener el cuaderno

Agente de solo chat de OpenAI

Obtener el cuaderno

Para obtener información sobre cómo expandir las funcionalidades de estos agentes mediante la adición de herramientas, consulte herramientas del agente de IA.

Creación de ChatAgent listos para la implementación para el servicio de modelos de Databricks

Databricks implementa ChatAgenten un entorno distribuido en Databricks Model Serving, lo que significa que, en una conversación de varios turnos, es posible que no todas las solicitudes sean gestionadas por la misma réplica de servicio. Preste atención a las siguientes implicaciones para administrar el estado del agente:

• Evitar el almacenamiento en caché local: al implementar un ChatAgent, no supongamos que la misma réplica controlará todas las solicitudes en una conversación multiturno. Reconstruya el estado interno mediante un esquema ChatAgentRequest de diccionario para cada turno.

• estado seguro para subprocesos: diseñe el estado del agente para que sea seguro para subprocesos, lo que impide conflictos en entornos multiproceso.

• Inicializar el estado en la función predict: Inicializar el estado cada vez que se llama a la función predict, no durante la inicialización de ChatAgent. Almacenar el estado en el nivel ChatAgent podría filtrar información entre conversaciones y provocar conflictos porque una sola réplica ChatAgent podría controlar las solicitudes de varias conversaciones.

entradas y salidas personalizadas

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

En estos escenarios, MLflow ChatAgent admite de forma nativa los campos custom_inputs y custom_outputs.

Advertencia

La aplicación de revisión de la evaluación del agente actualmente no admite la representación de trazados para agentes con campos de entrada adicionales.

Consulte los ejemplos siguientes para obtener información sobre cómo establecer entradas y salidas personalizadas para agentes OpenAI/PyFunc y LangGraph.

OpenAI + Cuaderno del agente de esquema personalizado de PyFunc

Obtener el cuaderno

Cuaderno del agente de esquema personalizado de LangGraph

Obtener el cuaderno

Proporcione custom_inputs en AI Playground y la aplicación de revisión de agentes

Si su agente acepta entradas adicionales mediante el campo custom_inputs, puede proporcionar manualmente estas entradas tanto en AI Playground como en la aplicación de revisión del agente.

1. En AI Playground o en la aplicación de revisión del agente, seleccione el icono de engranaje .

2. Habilite custom_inputs.

3. Proporcione un objeto JSON que coincida con el esquema de entrada definido del agente.

   

Especificar esquemas personalizados del recuperador

Los agentes de inteligencia artificial suelen usar recuperadores para buscar y consultar datos no estructurados de índices de búsqueda vectorial. Para ver herramientas de recuperación de ejemplo, consulte Herramientas de agente de IA de recuperación no estructurados.

Realice un seguimiento de estos recuperadores dentro del agente con intervalos de RECUPERACIÓN de MLflow para habilitar las características del producto de Databricks, entre las que se incluyen:

• Mostrar automáticamente vínculos a documentos de origen recuperados en la interfaz de usuario de AI Playground
• Ejecución automática de la recuperación del fundamento y evaluadores de relevancia en la evaluación del agente

Nota

Databricks recomienda usar las herramientas del recuperador proporcionadas por paquetes de Databricks AI Bridge como databricks_langchain.VectorSearchRetrieverTool y databricks_openai.VectorSearchRetrieverTool porque ya se ajustan al esquema del recuperador de MLflow. Consulte Desarrollo local de herramientas de recuperación de vectores de búsqueda con AI Bridge.

Si el agente incluye intervalos del recuperador con un esquema personalizado, llame a mlflow.models.set_retriever_schema al definir el agente en el código. Esto asigna las columnas de salida del recuperador a los campos esperados de MLflow (primary_key, text_column, doc_uri).

import mlflow
# Define the retriever's schema by providing your column names
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="chunk_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="text_column",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
)

Nota

La columna doc_uri es especialmente importante al evaluar el rendimiento del recuperador. doc_uri es el identificador principal de los documentos devueltos por el recuperador, lo que le permite compararlos con los conjuntos de evaluación de la verdad fundamental. Consulte Conjuntos de evaluación.

Parametrizar el código de agente para la implementación entre entornos

Puede parametrizar el código del agente para reutilizar el mismo código de agente en distintos entornos.

Los parámetros son pares clave-valor que se definen en un diccionario de Python o en un archivo .yaml.

Para configurar el código, cree un ModelConfig mediante un diccionario de Python o un archivo .yaml . ModelConfig es un conjunto de parámetros clave-valor que permite la administración flexible de la configuración. Por ejemplo, puede usar un diccionario durante el desarrollo y, a continuación, convertirlo en un archivo .yaml para la implementación de producción y CI/CD.

Para obtener más información sobre ModelConfig, consulte la documentación de MLflow.

A continuación se muestra un ejemplo ModelConfig:

llm_parameters:
  max_tokens: 500
  temperature: 0.01
model_serving_endpoint: databricks-dbrx-instruct
vector_search_index: ml.docs.databricks_docs_index
prompt_template: 'You are a hello world bot. Respond with a reply to the user''s
  question that indicates your prompt template came from a YAML file. Your response
  must use the word "YAML" somewhere. User''s question: {question}'
prompt_template_input_vars:
  - question

En el código del agente, puede hacer referencia a una configuración predeterminada (desarrollo) desde el archivo o diccionario .yaml:

import mlflow
# Example for loading from a .yml file
config_file = "configs/hello_world_config.yml"
model_config = mlflow.models.ModelConfig(development_config=config_file)

# Example of using a dictionary
config_dict = {
    "prompt_template": "You are a hello world bot. Respond with a reply to the user's question that is fun and interesting to the user. User's question: {question}",
    "prompt_template_input_vars": ["question"],
    "model_serving_endpoint": "databricks-dbrx-instruct",
    "llm_parameters": {"temperature": 0.01, "max_tokens": 500},
}

model_config = mlflow.models.ModelConfig(development_config=config_dict)

# Use model_config.get() to retrieve a parameter value
# You can also use model_config.to_dict() to convert the loaded config object
# into a dictionary
value = model_config.get('sample_param')

A continuación, al registrar el agente, especifique el parámetro model_config estableciéndolo en log_model para definir un conjunto personalizado de parámetros que se usará al cargar el agente registrado. Consulte la Documentación de MLflow: ModelConfig.

Propagación de errores de streaming

Propagación de errores de Mosaic AI encontrados durante el streaming con el último token bajo 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."
    }
  }
}

Pasos siguientes

• Creación de sus propias herramientas de agente.
• Registro de un agente de IA.
• Adición de trazados a un agente de IA.
• Implementación de un agente de IA.