Remarques :

Création d'un agent AI avec le serveur Multi-Agent Communication Protocol pour la résolution des factures

Introduction

Les entreprises qui traitent un grand nombre de produits - tels que les distributeurs, les industries et les chaînes de vente au détail - sont souvent confrontées au défi d'identifier des produits sur la base de descriptions textuelles inexactes, incomplètes ou variées. Dans les environnements où les données sont saisies manuellement, les fautes de frappe, les abréviations et les différents noms commerciaux peuvent rendre difficile l'identification correcte des articles dans des systèmes tels que Enterprise Resource Planning (ERP), Customer Relationship Management (CRM) et les plates-formes de commerce électronique.

Dans ce scénario, il existe un besoin commun d'outils qui peuvent :

Dans ce tutoriel, nous allons apprendre à créer un agent d'IA spécialisé dans la résolution des incohérences dans les factures de retour client. L'agent est capable d'interagir avec un serveur MCP qui fournit des outils de recherche vectorielle et de récupération de factures, ce qui permet à l'agent de trouver automatiquement la facture A/R d'origine de la société en fonction des informations fournies par le client.

Un serveur MCP (Model Context Protocol) est un composant logiciel responsable de la communication entre les agents intelligents et les services externes via un protocole standardisé de messages et d'outils. Il sert de pont entre les modèles de langage (LLM) et les API existantes, permettant aux agents d'IA d'accéder à des fonctionnalités spécifiques des systèmes hérités sans avoir à les réécrire ou à les adapter directement.

Comment ça fonctionne ?

Le serveur MCP :

Utilisation avec les applications héritées

Les applications héritées fournissent souvent déjà des fonctionnalités via des bases de données, des fichiers ou des API internes. Avec un serveur MCP, vous pouvez :

Avantages

Cet agent est basé sur un modèle de langage d'IA générative Oracle Cloud Infrastructure (OCI) et s'intègre aux outils déclarés dynamiquement gérés par un serveur MCP.

Avec l'intégration de ces deux composants, le système active un agent basé sur Oracle LLM :

Cette conception modulaire permet une réutilisation et une évolution facile du système vers des domaines autres que les factures.

Objectifs

Prérequis

Installez le fichier requirements.txt avec :

pip install -r requirements.txt

Tâche 1 : créer une base de données Oracle Database 23ai (toujours gratuit)

Dans cette tâche, nous allons apprendre à provisionner une instance Oracle Database 23ai en mode Toujours gratuit. Cette version offre un environnement entièrement géré, idéal pour le développement, les tests et l'apprentissage, sans frais supplémentaires.

  1. Connectez-vous à la console OCI, accédez à Oracle Database, à Autonomous Database et cliquez sur Créer une instance Autonomous Database.

  2. Saisissez les informations suivantes .

    • Nom de base de données : entrez un nom d'identification pour l'instance.
    • Type de charge globale : sélectionnez Data Warehouse ou Transaction Processing en fonction de vos besoins.
    • Compartiment : sélectionnez un compartiment approprié pour organiser vos ressources.

  3. Sélectionnez Toujours gratuit pour vous assurer que l'instance est provisionnée gratuitement.

  4. Créez un mot de passe sécurisé pour l'utilisateur ADMIN, qui sera utilisé pour accéder à la base de données.

  5. Vérifiez les paramètres et cliquez sur Create Autonomous Database (Créer une base de données autonome). Attendez quelques minutes que l'instance soit provisionnée et disponible pour utilisation.

Tâche 2 : exécution du script de création de table Autonomous Database

Préparez la base de données pour notre cas d'utilisation. Téléchargez et exécutez le script SQL à partir d'ici : script.sql, qui crée trois tables essentielles (PRODUCTS, INVOICE et ITEM_INVOICE) pour le scénario de rapprochement des factures avec les agents AI.

  1. Accédez à la console OCI, accédez à Oracle Database, à Autonomous Database et cliquez sur le nom de l'instance que vous venez de créer.

  2. Cliquez sur Database Actions et sur SQL pour ouvrir la console SQL dans le navigateur.

  3. Téléchargez et ouvrez le fichier script.sql en local et collez tout le contenu dans l'éditeur de console SQL.

  4. Cliquez sur Run (Exécuter) ou appuyez sur Ctrl + Entrée. Attendez la confirmation que les commandes ont été exécutées avec succès.

  5. Exécutez les commandes suivantes pour vérifier que les tables ont été créées.

    SELECT table_name FROM user_tables;

Tâche 3 : insérer des exemples de données dans des tables

Insérez des données fictives qui simuleront un scénario réel pour l'application des agents d'IA. Nous allons utiliser deux scripts SQL :

Ces données seront utilisées par les agents d'IA pour résoudre les incohérences dans les factures de retour.

  1. Accédez à la console OCI, accédez à Oracle Database, à Autonomous Database et cliquez sur le nom de l'instance que vous venez de créer.

  2. Cliquez sur Database Actions et sur SQL pour ouvrir la console SQL dans le navigateur.

  3. Téléchargez et ouvrez le contenu du fichier insert_products_books.sql et collez-le dans l'éditeur SQL.

  4. Cliquez sur Run (Exécuter) ou appuyez sur Ctrl + Entrée.

  5. A présent, téléchargez et ouvrez le contenu du fichier invoice_data_insert.sql et collez-le dans l'éditeur.

  6. Cliquez sur Run (Exécuter) ou appuyez sur Ctrl + Entrée.

  7. Exécutez la commande suivante pour vérifier les données.

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

Tâche 4 : créer et compiler la fonction de recherche avancée dans la base de données

Créez une fonction PL/SQL appelée fn_advanced_search, qui effectue des recherches intelligentes pour les mots-clés dans les descriptions de produit. Cette fonction sera utilisée par les agents d'IA dans le cadre de l'outil resolve_ean, ce qui leur permettra de trouver le code EAN le plus proche en fonction de la description fournie par un client sur la note de retour.

Que fait la fonction ?

Suivez les étapes décrites:

  1. Copiez et collez le script similarity_search.sql complet dans la console SQL de base de données autonome.

    Il s'agit notamment de :

    • Création de la table products (si elle n'a pas encore été effectuée).
    • Créer un index de texte.
    • Types product_result et product_result_tab.
    • Fonction fn_advanced_search.
    • Tests facultatifs.

  2. Exécutez le script complet. Le résultat doit être Function created et Type created.

  3. Exécutez la requête suivante pour tester la fonction avec des descriptions simulées.

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

Tâche 5 : vectoriser les produits pour la recherche sémantique avec l'IA

Dans cette tâche, nous compléterons la recherche SQL avancée par une nouvelle approche basée sur des vecteurs sémantiques. Cela sera particulièrement utile pour les agents d'IA qui utilisent des incorporations (représentations numériques de phrases) pour comparer la similitude entre les descriptions de produits - plus flexible et intelligemment que les recherches verbales ou phonétiques.

Pour ce faire, nous allons utiliser le script Python (process_vector_products.py), qui se connecte à la base de données Oracle, extrait les produits de la table PRODUCTS, transforme leurs descriptions en vecteurs (embeddings) et crée un index vectoriel à l'aide de la base de données Oracle elle-même.

Que fait le script ?

Remarque : les incorporations sont converties en octets avec np.float32.tobytes() pour être stockées en tant qu'objet BLOB. Pour extraire les vecteurs, utilisez np.frombuffer(blob, dtype=np.float32).

Ce format permet d'effectuer des recherches de similarité futures directement à l'aide de SQL ou en chargeant les vecteurs de la base de données pour les opérations avec np.dot, cosine_similarity ou l'intégration aux LLM.

Ce script génère des incorporations sémantiques pour les produits et écrit ces vecteurs dans la base de données Oracle 23ai. Les principaux points sont soulignés ci-dessous :

Exécutez le script :

N'oubliez pas qu'Oracle Wallet doit être téléchargé et configuré. Exécutez-le dans le terminal.

python process_vector_products.py

Terminé ! Les produits de la base de données ont été vectorisés.

Pourquoi est-ce important ?

La recherche vectorielle est très efficace pour trouver des produits même lorsque la description est subjective, imprécise ou en langage naturel.

Comprendre le code : agent LLM avec serveur MCP

Ce projet est composé de 3 composantes principales :

Comprendre la fonctionnalité de chaque composant et mettre en évidence en détail les parties les plus importantes du code.

Tâche 6 : configurer le modèle et les incorporations dans l'agent MCP

Configurez le modèle de langage et les intégrations utilisés par l'agent conversationnel en fonction du protocole MCP, à l'aide des services OCI Generative AI.

  1. Configurez le modèle de langue (LLM).

    Le modèle de langage est chargé d'interpréter les messages, de générer des réponses et d'agir en tant que cerveau principal de l'agent.

    • Configurez-le dans le fichier 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}
)
      Paramètre Description
      model_id ID de modèle d'IA générative, par exemple cohere.command-r-08-2024
      service_endpoint Adresse régionale du service d'IA générative
      compartment_id OCID du compartiment OCI
      auth_profile Nom du profil configuré dans le fichier ~/.oci/config
      model_kwargs Température, top-p et taille de réponse

    • Répertoriez les modèles disponibles.

      • Utilisation de l'interface de ligne d'interface de ligne de commande OCI :

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

      • Utilisation du kit SDK 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. Configurez les incorporations pour la recherche sémantique.

    La recherche de produits similaires ou d'informations contextuelles dépend de l'intégration de vecteurs.

    Exemple d'utilisation dans l'agent :

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

    Modifiez les paramètres (product_search.py) comme indiqué ci-dessous :

    
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"
    ):
    Paramètre Description
    top_k Nombre de suggestions renvoyées.
    minimum_distance Distance maximale pour prendre en compte le résultat pertinent.
    model_id ID du modèle d'intégration dans OCI (par exemple, cohere.embed-english-light-v3.0).
    service_endpoint Adresse régionale OCI Generative AI.
    compartment_id l'OCID de compartiment.
    auth_profile Nom du profil dans le fichier ~/.oci/config.
    wallet_path Chemin d'accès au portefeuille Oracle Database 23ai.
    db_alias Alias base données.
    username Utilisateur de base de données.
    password Mot de passe de base de données.

    Configurez le serveur MCP :

    Comme vous l'avez fait lors de l'exécution du code process_vector_products.py, vous devrez configurer Oracle Wallet pour la base de données Oracle Database 23ai.

    Modifiez les paramètres en fonction de vos paramètres :

    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

    Exécutez ensuite le fichier process_vector_products.py pour vectoriser les produits dans Oracle Database 23ai.

    python process_vector_products.py

Ainsi, le modèle LLM et les intégrations sont prêts à être utilisés par l'agent MCP avec LangGraph et LangChain.

  1. Exécutez le fichier main.py à l'aide de la commande suivante.

    python main.py

  2. Lorsque l'invite You : s'affiche, entrez l'instruction suivante.

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

    Remarque : le nom du livre Harry Potter et Azkaban est mal orthographié, mais le moteur peut le trouver sans aucun problème.

    img.png

    img_1.png

    Notez que les services ont été exécutés :

    fetch_vectorized_product
resolve_ean
search_invoices_by_criteria

  3. Maintenant, entrez l'instruction suivante.

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

    Aucun enregistrement de facture n'a été trouvé. En effet, le lieu est la clé pour trouver une facture.

    img_2.png

  4. Maintenant, entrez l'instruction suivante.

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

    Cette fois, nous entrons dans le lieu mais omettons le prix unitaire.

    img_3.png

    La facture a été trouvée. C'est parce que le prix n'est pas fondamental, mais il aide à combler l'écart pour être plus affirmé.

    Voici quelques exemples de tests :

     { "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"}

Tâche 8 : voir l'observabilité avec Phoenix

Entrez http://localhost:6006/ dans votre navigateur pour afficher l'observabilité avec Phoenix.

img.png

img.png

img.png

Accusés de réception

Ressources de formation supplémentaires

Explorez d'autres ateliers sur le site docs.oracle.com/learn ou accédez à d'autres contenus d'apprentissage gratuits sur le canal Oracle Learning YouTube. En outre, visitez le site education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

Pour obtenir de la documentation sur le produit, consultez Oracle Help Center.