Agents IA dans Azure Database pour PostgreSQL

Les agents IA transforment la façon dont les applications interagissent avec des données en combinant des modèles de langage volumineux (LLMs) avec des outils et des bases de données externes. Les agents permettent l’automatisation des flux de travail complexes, améliorent la précision de la récupération des informations et facilitent les interfaces en langage naturel aux bases de données.

Cet article explique comment créer des agents IA intelligents qui peuvent rechercher et analyser vos données dans Azure Database pour PostgreSQL. Il décrit l’installation, l’implémentation et le test à l’aide d’un assistant de recherche juridique comme exemple.

Présentation des agents d’IA

Les agents d'intelligence artificielle dépassent les simples chatbots en combinant des LLMs à l'aide d'outils et de bases de données externes. Contrairement aux LLM autonomes ou aux systèmes standard de génération augmentée par récupération (RAG), les agents IA peuvent :

Plan : décomposez les tâches complexes en étapes plus petites et séquentielles.
Utilisez des outils : utilisez des API, l’exécution du code et des systèmes de recherche pour collecter des informations ou effectuer des actions.
Percevoir : Comprendre et traiter les entrées de différentes sources de données.
Rappelez-vous : Stocker et rappeler les interactions précédentes pour une meilleure prise de décision.

En connectant des agents IA à des bases de données telles qu’Azure Database pour PostgreSQL, les agents peuvent fournir des réponses plus précises et contextuelles basées sur vos données. Les agents IA s’étendent au-delà de la conversation humaine de base pour effectuer des tâches basées sur le langage naturel. Par le passé, ces tâches nécessitaient une logique codée. Toutefois, les agents peuvent planifier les tâches nécessaires à l’exécution en fonction du contexte fourni par l’utilisateur.

Implémentation d’agents IA

L’implémentation d’agents IA avec Azure Database pour PostgreSQL implique l’intégration de fonctionnalités d’IA avancées avec des fonctionnalités de base de données robustes pour créer des systèmes intelligents et prenant en charge le contexte. À l’aide d’outils tels que la recherche vectorielle, les incorporations et le service Azure AI Foundry Agent, les développeurs peuvent créer des agents qui comprennent les requêtes en langage naturel, récupérer des données pertinentes et fournir des insights actionnables.

Les sections suivantes décrivent le processus pas à pas pour configurer, configurer et déployer des agents IA. Ce processus permet une interaction transparente entre les modèles IA et votre base de données PostgreSQL.

Frameworks

Divers frameworks et outils peuvent faciliter le développement et le déploiement d’agents IA. Toutes ces infrastructures prennent en charge l’utilisation d’Azure Database pour PostgreSQL en tant qu’outil :

Exemple d’implémentation

L’exemple de cet article utilise le service Azure AI Foundry Agent pour la planification de l’agent, l’utilisation des outils et la perception. Il utilise Azure Database pour PostgreSQL comme outil pour les fonctionnalités de recherche sémantique et de base de données vectorielles.

Les sections suivantes vous guident tout au long de la création d’un agent IA qui aide les équipes juridiques à rechercher des cas pertinents pour soutenir leurs clients à Washington State. Agent :

Accepte des requêtes en langage naturel sur les situations juridiques.
Utilise la recherche vectorielle dans Azure Database pour PostgreSQL pour trouver des précédents de cas pertinents.
Analyse et résume les résultats dans un format utile pour les professionnels juridiques.

Conditions préalables

Activez et configurez les extensions azure_ai et pg_vector.
Créez un projet Azure AI Foundry.
Déployer des modèlesgpt-4o-mini et text-embedding-small.
Installez Visual Studio Code.
Installez l’extension Python .
Installez Python 3.11.x.
Installez Azure CLI (dernière version).

Remarque

Vous avez besoin de la clé et du point de terminaison des modèles déployés que vous avez créés pour l’assistant Copilot.

Mise en route

Tout le code et les exemples de jeux de données sont disponibles dans ce dépôt GitHub.

Étape 1 : Configurer la recherche vectorielle dans Azure Database pour PostgreSQL

Tout d’abord, préparez votre base de données pour stocker et rechercher des données de cas juridiques à l’aide d’incorporations vectorielles.

Configurer l’environnement

Si vous utilisez macOS et Bash, exécutez ces commandes :

python -m venv .pg-azure-ai 
source .pg-azure-ai/bin/activate 
pip install -r requirements.txt

Si vous utilisez Windows et PowerShell, exécutez ces commandes :

python -m venv .pg-azure-ai 
.pg-azure-ai \Scripts\Activate.ps1 
pip install -r requirements.txt

Si vous utilisez Windows et que cmd.exe, exécutez ces commandes :

python -m venv .pg-azure-ai 
.pg-azure-ai \Scripts\activate.bat 
pip install -r requirements.txt

Configurer les variables d’environnement

Créez un .env fichier avec vos informations d’identification :

AZURE_OPENAI_API_KEY="" 
AZURE_OPENAI_ENDPOINT="" 
EMBEDDING_MODEL_NAME="" 
AZURE_PG_CONNECTION=""

Charger des documents et des vecteurs

Le fichier Python load_data/main.py sert de point d’entrée central pour le chargement de données dans Azure Database pour PostgreSQL. Le code traite les données des exemples de cas, y compris des informations sur les cas à Washington.

Le fichier main.py :

Crée les extensions nécessaires, configure les paramètres de l’API OpenAI et gère les tables de base de données en supprimant les tables existantes et en créant de nouvelles pour stocker les données de cas.
Lit les données d’un fichier CSV et les insère dans une table temporaire, puis les traite et les transfère dans la table de cas principale.
Ajoute une nouvelle colonne pour les incorporations dans la table de cas et génère des incorporations pour les opinions de cas à l’aide de l’API d’OpenAI. Il stocke les incorporations dans la nouvelle colonne. Le processus d’incorporation prend environ 3 à 5 minutes.

Pour démarrer le processus de chargement des données, exécutez la commande suivante à partir du load_data répertoire :

python main.py

Voici la sortie de main.py:

Extensions created successfully 
OpenAI connection established successfully 
The case table was created successfully 
Temp cases table created successfully 
Data loaded into temp_cases_data table successfully 
Data loaded into cases table successfully.
Adding Embeddings will take a while, around 3-5 mins.
Embeddings added successfully All Data loaded successfully!

Étape 2 : Créer un outil Postgres pour l’agent

Ensuite, configurez les outils de l’agent IA pour récupérer des données à partir de Postgres. Utilisez ensuite le Kit de développement logiciel (SDK) du service Azure AI Foundry Agent pour connecter votre agent IA à la base de données Postgres.

Définir une fonction que votre agent va appeler

Commencez par définir une fonction pour que votre agent appelle en décrivant sa structure et tous les paramètres requis dans une documentation. Incluez toutes vos définitions de fonction dans un fichier unique , legal_agent_tools.py. Vous pouvez ensuite importer le fichier dans votre script principal.

def vector_search_cases(vector_search_query: str, start_date: datetime ="1911-01-01", end_date: datetime ="2025-12-31", limit: int = 10) -> str:
    """
 Fetches the case information in Washington State for the specified query.

 :param query(str): The query to fetch cases specifically in Washington.
 :type query: str
 :param start_date: The start date for the search defaults to "1911-01-01"
 :type start_date: datetime, optional
 :param end_date: The end date for the search, defaults to "2025-12-31"
 :type end_date: datetime, optional
 :param limit: The maximum number of cases to fetch, defaults to 10
 :type limit: int, optional

 :return: Cases information as a JSON string.
 :rtype: str
 """
        
 db = create_engine(CONN_STR)
    
 query = """
 SELECT id, name, opinion, 
 opinions_vector <=> azure_openai.create_embeddings(
 'text-embedding-3-small', %s)::vector as similarity
 FROM cases
 WHERE decision_date BETWEEN %s AND %s
 ORDER BY similarity
 LIMIT %s;
 """
    
    # Fetch case information from the database
 df = pd.read_sql(query, db, params=(vector_search_query,datetime.strptime(start_date, "%Y-%m-%d"), datetime.strptime(end_date, "%Y-%m-%d"),limit))

 cases_json = json.dumps(df.to_json(orient="records"))
    return cases_json

Étape 3 : Créer et configurer l’agent IA avec Postgres

À présent, configurez l’agent IA et intégrez-le à l’outil Postgres. Le fichier Python src/simple_postgres_and_ai_agent.py sert de point d’entrée central pour la création et l’utilisation de votre agent.

Le fichier simple_postgres_and_ai_agent.py :

Initialise l’agent dans votre projet Azure AI Foundry avec un modèle spécifique.
Ajoute l’outil Postgres pour la recherche vectorielle sur votre base de données, pendant l’initialisation de l’agent.
Configure un thread de communication. Ce thread est utilisé pour envoyer des messages à l’agent à des fins de traitement.
Traite la requête de l’utilisateur à l’aide de l’agent et des outils. L’agent peut planifier avec des outils pour obtenir la réponse correcte. Dans ce cas d’usage, l’agent appelle l’outil Postgres en fonction de la signature de fonction et de la documentation pour effectuer une recherche vectorielle et récupérer les données pertinentes pour répondre à la question.
Affiche la réponse de l’agent à la requête de l’utilisateur.

Rechercher la chaîne de connexion de projet dans Azure AI Foundry

Dans votre projet Azure AI Foundry, vous trouverez la chaîne de connexion de votre projet à partir de la page de vue d’ensemble du projet. Vous utilisez cette chaîne pour connecter le projet au Kit de développement logiciel (SDK) du service Azure AI Foundry Agent. Ajoutez cette chaîne au .env fichier.

Capture d’écran montrant la page de configuration du projet.

Configurer la connexion

Ajoutez ces variables à votre .env fichier dans le répertoire racine :

PROJECT_CONNECTION_STRING=" " 
MODEL_DEPLOYMENT_NAME="gpt-4o-mini" 
AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED="true"

### Create the agent with tool access
We created the agent in the Azure AI Foundry project and added the Postgres tools needed to query the database. The code snippet below is an excerpt from the file [simple_postgres_and_ai_agent.py](https://github.com/Azure-Samples/postgres-agents/blob/main/azure-ai-agent-service/src/simple_postgres_and_ai_agent.py).

# Create an Azure AI Foundry client
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

# Initialize the agent toolset with user functions
functions = FunctionTool(user_functions)
toolset = ToolSet()
toolset.add(functions)

agent = project_client.agents.create_agent(
    model= os.environ["MODEL_DEPLOYMENT_NAME"], 
    name="legal-cases-agent",
    instructions= "You are a helpful legal assistant who can retrieve information about legal cases.", 
    toolset=toolset
)

Créer un thread de communication

Cet extrait de code montre comment créer un thread et un message d’agent, que l’agent traite dans une exécution :

# Create a thread for communication
thread = project_client.agents.create_thread()

# Create a message to thread
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="Water leaking into the apartment from the floor above. What are the prominent legal precedents in Washington regarding this problem in the last 10 years?"
)

Traiter la demande

L’extrait de code suivant crée une exécution pour que l’agent traite le message et utilise les outils appropriés pour fournir le meilleur résultat.

À l’aide des outils, l’agent peut appeler Postgres et la recherche vectorielle sur la requête « Fuite d’eau dans l’appartement au-dessus » pour récupérer les données dont il a besoin pour répondre le mieux à la question.

from pprint import pprint

# Create and process an agent run in the thread with tools
run = project_client.agents.create_and_process_run(
thread_id=thread.id, 
agent_id=agent.id
)

# Fetch and log all messages
messages = project_client.agents.list_messages(thread_id=thread.id)
pprint(messages['data'][0]['content'][0]['text']['value'])

Exécuter l’agent

Pour exécuter l’agent, exécutez la commande suivante à partir du src répertoire :

python simple_postgres_and_ai_agent.py

L’agent produit un résultat similaire à l’aide de l’outil Azure Database pour PostgreSQL pour accéder aux données de cas enregistrées dans la base de données Postgres.

Voici un extrait de sortie de l’assistant :

1.     Pham v. Corbett

Citation: Pham v. Corbett, No. 4237124
Summary: This case involved tenants who counterclaimed against their landlord for relocation assistance and breached the implied warranty of habitability due to severe maintenance issues, including water and sewage leaks. The trial court held that the landlord had breached the implied warranty and awarded damages to the tenants.

2.     Hoover v. Warner

Citation: Hoover v. Warner, No. 6779281
Summary: The Warners appealed a ruling finding them liable for negligence and nuisance after their road grading project caused water drainage issues affecting Hoover's property. The trial court found substantial evidence supporting the claim that the Warners' actions impeded the natural water flow and damaged Hoover's property.

Étape 4 : Tester et déboguer avec le terrain de jeu de l’agent

Une fois que vous avez exécuté votre agent à l’aide du Kit de développement logiciel (SDK) azure AI Foundry Agent, l’agent est stocké dans votre projet. Vous pouvez expérimenter avec l’agent dans l’environnement d'expérimentation :

Dans Azure AI Foundry, accédez à la section Agents .
Recherchez votre agent dans la liste et sélectionnez-le pour l’ouvrir.
Utilisez l’interface de terrain de jeu pour tester différentes requêtes juridiques.
Testez la requête « Fuite d’eau dans l’appartement de l’étage ci-dessus, Quels sont les précédents juridiques importants à Washington ? » L’agent sélectionne l’outil approprié à utiliser et demande la sortie attendue pour cette requête. Utilisez sample_vector_search_cases_output.json comme exemple de sortie.

Étape 5 : Débogage avec le suivi d’Azure AI Foundry

Lorsque vous développez l’assistant à l’aide du Kit de développement logiciel (SDK) Azure AI Foundry Agent Service, vous pouvez déboguer l’agent avec le suivi. Le suivi vous permet de déboguer les appels à des outils comme Postgres et de voir comment l’agent orchestre chaque tâche.

Dans Azure AI Foundry, accédez au Suivi.
Pour créer une ressource Application Insights, sélectionnez Créer nouveau. Pour connecter une ressource existante, sélectionnez-en une dans la zone Nom de la ressource Application Insights , puis sélectionnez Se connecter.
Affichez les traces détaillées des opérations de votre agent.

Découvrez comment configurer le suivi avec l’agent IA et Postgres dans le fichier advanced_postgres_and_ai_agent_with_tracing.py sur GitHub.

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-07-24