Note:

Creación de un agente AI con un servidor de protocolo de comunicación de varios agentes para la resolución de facturas

Introducción

Las empresas que se ocupan de un gran volumen de productos, como distribuidores, industrias y cadenas minoristas, a menudo se enfrentan al desafío de identificar productos basados en descripciones textuales inexactas, incompletas o variadas. En entornos donde los datos se introducen manualmente, los errores tipográficos, las abreviaturas y los diferentes nombres comerciales pueden dificultar la identificación correcta de artículos en sistemas como la planificación de recursos empresariales (ERP), la gestión de relaciones con los clientes (CRM) y las plataformas de comercio electrónico.

En este escenario, existe una necesidad común de herramientas que puedan:

En este tutorial, aprenderemos a crear un agente de IA especializado en resolver inconsistencias en las facturas de devolución de clientes. El agente es capaz de interactuar con un servidor MCP que proporciona herramientas de búsqueda vectorial y recuperación de facturas, lo que permite al agente encontrar automáticamente la factura original de AR de la compañía basada en la información proporcionada por el cliente.

Un servidor de MCP (protocolo de contexto de modelo) es un componente de software responsable de la mediación de la comunicación entre agentes inteligentes y servicios externos mediante un protocolo estandarizado de mensajes y herramientas. Actúa como un puente entre los modelos de lenguaje (LLM) y las API existentes, lo que permite a los agentes de IA acceder a funcionalidades específicas de los sistemas heredados sin necesidad de reescribirlas o adaptarlas directamente.

¿Cómo funciona?

El servidor MCP:

Uso con aplicaciones heredadas

Las aplicaciones heredadas a menudo ya proporcionan funcionalidad a través de bases de datos, archivos o API internas. Con un servidor MCP, puede:

Ventajas

Este agente se basa en un modelo de lenguaje de IA generativa de Oracle Cloud Infrastructure (OCI) y se integra con herramientas declaradas dinámicamente gestionadas por un servidor MCP.

Con estos dos componentes de integración, el sistema activa un agente basado en Oracle LLM:

Este diseño modular permite la reutilización y la fácil evolución del sistema a dominios que no sean facturas.

Objetivos

Requisitos

Tarea 1: Creación de una instancia de Oracle Database 23ai (siempre gratis)

En esta tarea, aprenderemos a aprovisionar Oracle Database 23ai en modo Siempre gratis. Esta versión ofrece un entorno totalmente gestionado, ideal para el desarrollo, las pruebas y el aprendizaje, sin costo adicional.

  1. Conéctese a la consola de OCI, vaya a Oracle Database, Autonomous Database y haga clic en Crear instancia de Autonomous Database.

  2. Introduzca la siguiente información.

    • Nombre de la base de datos: introduzca un nombre de identificación para la instancia.
    • Tipo de carga de trabajo: seleccione Almacén de datos o Procesamiento de transacciones, según sus necesidades.
    • Compartimento: seleccione un compartimento adecuado para organizar los recursos.

  3. Seleccione Siempre gratis para asegurarse de que la instancia se aprovisiona de forma gratuita.

  4. Cree una contraseña segura para el usuario ADMIN, que se utilizará para acceder a la base de datos.

  5. Revise la configuración y haga clic en Create Autonomous Database. Espere unos minutos a que la instancia se aprovisione y esté disponible para su uso.

Tarea 2: Ejecución del script de creación de tablas de Autonomous Database

Preparar la base de datos para nuestro caso de uso. Descargue y ejecute el script SQL desde aquí: script.sql que crea tres tablas esenciales (PRODUCTS, INVOICE y ITEM_INVOICE) para el escenario de conciliación de facturas con agentes de AI.

  1. Vaya a la consola de OCI, vaya a Oracle Database, Autonomous Database y haga clic en el nombre de la instancia recién creada.

  2. Haga clic en Database Actions y SQL para abrir la consola SQL en el explorador.

  3. Descargue y abra el archivo script.sql localmente y pegue todo el contenido en el editor de la consola SQL.

  4. Haga clic en Run (Ejecutar) o pulse Ctrl + Intro. Espere a que se confirme que los comandos se hayan ejecutado correctamente.

  5. Ejecute los siguientes comandos para verificar que las tablas se han creado.

    SELECT table_name FROM user_tables;

Tarea 3: Inserción de datos de ejemplo en tablas

Insertar datos ficticios que simularán un escenario real para la aplicación de agentes de IA. Utilizaremos dos scripts SQL:

Los agentes de IA utilizarán estos datos para resolver incoherencias en las facturas de devolución.

  1. Vaya a la consola de OCI, vaya a Oracle Database, Autonomous Database y haga clic en el nombre de la instancia recién creada.

  2. Haga clic en Database Actions y SQL para abrir la consola SQL en el explorador.

  3. Descargue el contenido del archivo insert_products_books.sql desde aquí: insert_products_books.sql y péguelo en el editor SQL.

  4. Haga clic en Run (Ejecutar) o pulse Ctrl + Intro.

  5. Ahora, descargue el contenido del archivo invoice_data_insert.sql desde aquí: archivo invoice_data_insert.sql y péguelo en el editor.

  6. Haga clic en Run (Ejecutar) o pulse Ctrl + Intro.

  7. Ejecute el siguiente comando para comprobar los datos.

    SELECT * FROM PRODUCTS;
SELECT * FROM INVOICE;
SELECT * FROM ITEM_INVOICE;

Tarea 4: Creación y compilación de la función de búsqueda avanzada en la base de datos

Cree una función PL/SQL denominada fn_advanced_search, que realiza búsquedas inteligentes de palabras clave en las descripciones de productos. Esta función será utilizada por los agentes de AI como parte de la herramienta resolve_ean, lo que les permitirá encontrar el código EAN más cercano en función de la descripción proporcionada por un cliente en la nota de devolución.

¿Qué hace la función?

Realice los pasos:

  1. Copie y pegue el script similarity_search.sql completo en la consola SQL de la base de datos autónoma.

    Esto incluye:

    • Creando la tabla products (si aún no se ha realizado).
    • Creación de un índice de texto.
    • Tipos product_result y product_result_tab.
    • La función fn_advanced_search.
    • Pruebas opcionales.

  2. Ejecute el script completo. El resultado debe ser Function created y Type created.

  3. Ejecute la siguiente consulta para probar la función con descripciones simuladas.

    SELECT *
FROM TABLE(fn_advanced_search('harry poter askaban'))
ORDER BY similarity DESC;

Tarea 5: Vectorización de productos para la búsqueda semántica con IA

En esta tarea, complementaremos la búsqueda avanzada basada en SQL con un nuevo enfoque basado en vectores semánticos. Esto será especialmente útil para los agentes de IA que utilizan incrustaciones (representaciones numéricas de frases) para comparar la similitud entre las descripciones de productos, de manera más flexible e inteligente que las búsquedas fonéticas o de palabras.

Para ello, utilizaremos el script de Python (process_vector_products.py), que se conecta a la base de datos Oracle, extrae los productos de la tabla PRODUCTS, transforma sus descripciones en vectores (embeddings) y crea un índice vectorial mediante la propia base de datos Oracle.

¿Qué hace el script?

Nota: Las incrustaciones se convierten en bytes con np.float32.tobytes() para almacenarse como BLOB. Para recuperar los vectores, utilice np.frombuffer(blob, dtype=np.float32).

Este formato permite realizar búsquedas de similitud futuras directamente mediante SQL o cargando los vectores de la base de datos para operaciones con np.dot, cosine_similarity o integración con LLM.

Este script genera incrustaciones semánticas para productos y escribe estos vectores en Oracle Database 23ai. Los puntos principales se destacan a continuación:

Ejecución del script:

Nota: Debe descargar y configurar Oracle Wallet.

Ejecutar en el terminal.

python process_vector_products.py

Listo Los productos de la base de datos se han vectorizado.

¿Por qué es esto importante?

La búsqueda vectorial es muy eficaz para encontrar productos incluso cuando la descripción es subjetiva, imprecisa o en lenguaje natural.

Descripción del Código: Agente LLM con Servidor MCP

Este proyecto se compone de 3 componentes principales:

Comprender la funcionalidad de cada componente y resaltar detalladamente las partes más importantes del código.

Tarea 6: Configuración del modelo y las incrustaciones en el agente MCP

Configuremos el modelo de lenguaje y las incrustaciones utilizadas por el agente conversacional según el protocolo MCP, utilizando los servicios de OCI Generative AI.

  1. Configure el modelo de idioma (LLM).

    El modelo de lenguaje es responsable de interpretar los mensajes, generar respuestas y actuar como el cerebro principal del agente.

    • Configure en el archivo main.py.

      from langchain_community.chat_models.oci_generative_ai import ChatOCIGenAI

llm = ChatOCIGenAI(
    model_id="cohere.command-r-08-2024",
    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
    compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    auth_profile="DEFAULT",
    model_kwargs={"temperature": 0.1, "top_p": 0.75, "max_tokens": 2000}
)
      parámetro Descripción
      model_id ID de modelo de IA generativa, por ejemplo, cohere.command-r-08-2024
      service_endpoint Punto final regional del servicio de IA generativa
      compartment_id OCID del compartimento OCI
      auth_profile Nombre del perfil configurado en el archivo ~/.oci/config
      model_kwargs Temperatura, p superior y tamaño de respuesta

    • Lista de modelos disponibles.

      • Uso de la CLI de OCI:

        oci generative-ai model list --compartment-id <seu_compartment_id>

      • Uso del SDK de Python:

        from oci.generative_ai import GenerativeAiClient
from oci.config import from_file

config = from_file(profile_name="DEFAULT")
client = GenerativeAiClient(config)

models = client.list_models(compartment_id=config["compartment_id"])
for model in models.data:
    print(model.display_name, model.model_id)

  2. Permite configurar incrustaciones para la búsqueda semántica.

    La búsqueda de productos similares o información contextual depende de incrustaciones vectoriales.

    Ejemplo de uso en el agente:

    @mcp.tool()
def search_vectorized_product(description: str) -> dict:
    """
        Searches for a product by description using embeddings.
    """
    return sercher.search_similar_products(description)

    Cambie los parámetros (product_search.py) como se muestra a continuación:

    
class SimilarProductSearch:
    def __init__(
            self,
            top_k=5,
            minimum_distance=1.0,
            model_id="cohere.embed-english-light-v3.0",
            service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
            compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            auth_profile="DEFAULT",
            wallet_path="/WALLET_PATH/Wallet_oradb23ai",
            db_alias="oradb23ai_high",
            username="USER",
            password="Password"
    ):
    parámetro Descripción
    top_k Número de propuestas devueltas.
    minimum_distance Distancia máxima para considerar el resultado relevante.
    model_id ID del modelo de embebido en OCI (por ejemplo, cohere.embed-english-light-v3.0).
    service_endpoint Punto final regional de OCI Generative AI.
    compartment_id OCID de compartimiento.
    auth_profile Nombre de perfil en el archivo ~/.oci/config.
    wallet_path Ruta de acceso a la cartera de Oracle Database 23ai.
    db_alias Alias de Base de Datos.
    username Usuario de Base de Datos.
    password Contraseña de Base de Datos.

    Configure el servidor MCP:

    Al igual que al ejecutar el código process_vector_products.py, deberá configurar Oracle Wallet para la base de datos Oracle Database 23ai.

    Modifique los parámetros según su configuración:

    import os

# Oracle Wallet settings
WALLET_PATH = "/path/to/Wallet"
DB_ALIAS = "oradb23ai_high"
USERNAME = "admin"
PASSWORD = "..."

# Define the environment variable required for the Oracle client
os.environ["TNS_ADMIN"] = WALLET_PATH

    A continuación, ejecute process_vector_products.py para vectorizar los productos en Oracle Database 23ai.

    python process_vector_products.py

Con esto, el modelo de LLM y las incrustaciones están listos para ser utilizados por el agente de MCP con LangGraph y LangChain.

  1. Ejecute el archivo main.py con el siguiente comando.

    python main.py

  2. Cuando aparezca el indicador You:, introduzca la siguiente sentencia.

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

    Nota: El nombre del libro Harry Potter y Azkaban está escrito mal, pero el motor puede encontrarlo sin ningún problema.

    img.png

    img_1.png

    Tenga en cuenta que los servicios se han ejecutado:

    fetch_vectorized_product
resolve_ean
search_invoices_by_criteria

  3. Ahora, introduzca la siguiente sentencia.

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

    Verá que no se encontró ningún registro de factura de venta. Esto se debe a que la ubicación es clave para buscar una factura.

    img_2.png

  4. Ahora, introduzca la siguiente sentencia.

    { "customer": "Customer 108",  "description": "Harry Poter", "location": "SP"}

    Esta vez, introducimos la ubicación pero omitimos el precio unitario.

    img_3.png

    Sin embargo, se ha encontrado la facturación. Esto se debe a que el precio no es fundamental, pero sí ayuda a cerrar la brecha para ser más asertivo.

    Algunos ejemplos de pruebas son:

     { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "RJ"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.16, "location": "SP"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.15, "location": "SP"}

Tarea 8: Visualización de la observabilidad con Phoenix

Introduzca http://localhost:6006/ en el explorador para ver la observabilidad con Phoenix.

img.png

img.png

img.png

Acuses de recibo

Más recursos de aprendizaje

Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en un explorador de Oracle Learning.

Para obtener documentación sobre el producto, visite Oracle Help Center.