Agenti di intelligenza artificiale in Database di Azure per PostgreSQL

2025-06-21

Gli agenti di intelligenza artificiale stanno trasformando il modo in cui le applicazioni interagiscono con i dati combinando modelli di linguaggio di grandi dimensioni con strumenti e database esterni. Gli agenti consentono l'automazione di flussi di lavoro complessi, migliorano l'accuratezza del recupero delle informazioni e facilitano le interfacce del linguaggio naturale ai database. Questo articolo illustra come creare agenti di intelligenza artificiale intelligenti in grado di cercare e analizzare i dati in Database di Azure per PostgreSQL. Viene illustrata la configurazione, l'implementazione e il test usando un assistente alla ricerca legale come esempio.

Che cosa sono gli agenti di intelligenza artificiale

Gli agenti di intelligenza artificiale vanno oltre i semplici chatbot combinando modelli di linguaggio di grandi dimensioni con strumenti e database esterni. A differenza dei sistemi LLMs autonomi o rag standard, gli agenti di intelligenza artificiale possono:

Piano: suddividere le attività complesse in passaggi più piccoli e sequenziali.
Usare strumenti: usare API, esecuzione del codice e sistemi di ricerca per raccogliere informazioni o eseguire azioni.
Percezione: comprendere ed elaborare gli input da varie origini dati.
Ricorda: archiviare e richiamare le interazioni precedenti per un processo decisionale migliore.

Connettendo gli agenti di intelligenza artificiale ai database come Database di Azure per PostgreSQL, gli agenti possono fornire risposte più accurate e con riconoscimento del contesto in base ai dati. Gli agenti di intelligenza artificiale si estendono oltre la conversazione umana di base per eseguire attività basate sul linguaggio naturale. Queste attività richiedevano tradizionalmente la logica codificata; Tuttavia, gli agenti possono pianificare le attività necessarie per l'esecuzione in base al contesto fornito dall'utente.

Implementazione degli agenti IA

L'implementazione degli agenti di intelligenza artificiale con Database di Azure per PostgreSQL prevede l'integrazione di funzionalità avanzate di intelligenza artificiale con funzionalità di database affidabili per creare sistemi intelligenti e con riconoscimento del contesto. Sfruttando strumenti come la ricerca vettoriale, gli incorporamenti e il servizio Azure AI Agent, gli sviluppatori possono creare agenti in grado di comprendere le query in linguaggio naturale, recuperare i dati pertinenti e fornire informazioni dettagliate utili. Questa sezione descrive il processo dettagliato per configurare, configurare e distribuire agenti di intelligenza artificiale, consentendo un'interazione trasparente tra i modelli di intelligenza artificiale e il database PostgreSQL.

Framework

Vari framework e strumenti possono facilitare lo sviluppo e la distribuzione degli agenti IA. Tutti questi framework supportano l'uso di Database di Azure per PostgreSQL come strumento

Esempio di implementazione

Il Servizio Azure AI Agent viene utilizzato per la pianificazione degli agenti, l'utilizzo degli strumenti e la percezione, mentre si utilizza il Azure Database for PostgreSQL come strumento per le funzionalità di database vettoriali e di ricerca semantica.

Nell'esercitazione viene creato un agente di intelligenza artificiale che aiuta i team legali a cercare casi rilevanti per supportare i clienti nello stato di Washington. L'agente:

Accettare query in linguaggio naturale su situazioni legali.
Usare la ricerca vettoriale in Database di Azure per PostgreSQL per trovare i precedenti dei casi pertinenti.
Analizzare e riepilogare i risultati in un formato utile per i professionisti legali.

Prerequisiti

Abilitare e configurareazure_ai & pg_vector estensione.
Creare un progetto di Azure AI Foundry
Distribuire modelligpt-4o-mini & text-embedding-small
Installare Visual Studio Code.
Installare l'estensione Python .
Installare Python 3.11.x.
Installare l'interfaccia della riga di comando di Azure.(versione più recente)

Annotazioni

Hai bisogno della chiave e dell'endpoint dei modelli distribuiti che hai creato per l'agente.

Come iniziare

Tutti i set di dati di codice e di esempio sono disponibili in questo repository GitHub.

Passaggio 1: Configurare la ricerca vettoriale in Database di Azure per PostgreSQL

Prima di tutto, si prepara il database per archiviare e cercare i dati dei casi legali usando incorporamenti vettoriali:

Configurazione dell'ambiente

Se si usa macOS/bash:

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

Windows/PowerShell

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

Windows / cmd.exe:

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

Configurare le variabili di ambiente

Crea un .env file con le tue credenziali:

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

Caricare documenti e vettori

Il file Python load_data/main.py funge da punto di ingresso centrale per il caricamento dei dati in Database di Azure per PostgreSQL. Il codice elabora i dati dei casi di esempio, incluse le informazioni sui casi nel Washington.

Dettagli principali di main.py:

Configurazione del database e creazione di tabelle: crea estensioni necessarie, configura le impostazioni dell'API OpenAI e gestisce le tabelle di database eliminando quelle esistenti e creando nuove per l'archiviazione dei dati del case.
Inserimento dati: questo processo legge i dati da un file CSV e lo inserisce in una tabella temporanea, quindi lo elabora e lo trasferisce nella tabella del case principale.
Generazione di embedding: aggiunge una nuova colonna per gli embedding nella tabella casi e genera embedding per le opinioni sui casi usando l'API di OpenAI, archiviandoli nella nuova colonna. Il processo di incorporamento richiede circa 3-5 minuti

Per avviare il processo di caricamento dei dati, eseguire il comando seguente dalla directory load_data :

python main.py

Ecco l'output di 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!

Passaggio 2: Creare uno strumento Postgres per l'agente

Vengono configurati gli strumenti dell'agente di intelligenza artificiale per recuperare i dati da Postgres e quindi si usa Azure AI Agent Service SDK per connettere l'agente di intelligenza artificiale al database Postgres.

Definire una funzione che l'agente deve chiamare

Per iniziare, definire una funzione per chiamare l'agente descrivendone la struttura e tutti i parametri necessari in una docstring. Includere tutte le definizioni di funzione in un singolo file , legal_agent_tools.py, che è quindi possibile importare nello script principale.

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 cases 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

Passaggio 3: Creare e configurare l'agente di intelligenza artificiale con Postgres

A questo punto si configurerà l'agente di intelligenza artificiale e lo si integrerà con lo strumento PostgreSQL. Il file Python src/simple_postgres_and_ai_agent.py funge da punto di ingresso centrale per la creazione e l'uso dell'agente.

Dettagli di alto livello di simple_postgres_and_ai_agent.py:

Creare un agente: inizializza l'agente nel progetto di intelligenza artificiale di Azure con un modello specifico.
Aggiungere lo strumento Postgres: durante l'inizializzazione dell'agente, viene aggiunto lo strumento Postgres per la ricerca vettoriale nel database.
Creare un thread: configura un thread di comunicazione. Viene usato per inviare all'agente messaggi da elaborare
Esegui l'agente e lo strumento Call Postgres: Processa la query dell'utente utilizzando l'agente e gli strumenti. L'agente può pianificare con gli strumenti da usare per ottenere la risposta corretta. In questo caso d'uso, l'agente chiama lo strumento Postgres in base alla firma della funzione e alla docstring per eseguire una ricerca vettoriale e recuperare i dati pertinenti per rispondere alla domanda.
Visualizzare la risposta dell'agente: questa funzione restituisce la risposta dell'agente alla query dell'utente.

Trovare la stringa di connessione del progetto in Azure AI Foundry

Nel progetto Azure AI Foundry, trovi la stringa di connessione del progetto nella pagina Panoramica del progetto. Questa stringa viene usata per connettere il progetto all'SDK dell'agente di intelligenza artificiale. Aggiungi questa stringa al file .env.

Screenshot che mostra la pagina di installazione del progetto.

Configurazione connessione

Aggiungi queste variabili al file .env nella directory radice:

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 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/src/simple_postgres_and_ai_agent.py).

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

# Initialize 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
)

Creare un thread di comunicazione

Questo frammento di codice illustra come creare un thread e un messaggio dell'agente, che l'agente elabora in un'esecuzione.

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

# Create 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?"
)

Elaborare la richiesta

Questo frammento di codice crea un'esecuzione per l'agente per elaborare il messaggio e usare gli strumenti appropriati per fornire il risultato migliore.

Usando lo strumento, l'agente può chiamare Postgres e la ricerca vettoriale sulla query "Perdita di acqua nell'appartamento dal piano sopra"* per recuperare i dati necessari per rispondere al meglio alla domanda.

from pprint import pprint

# Create and process agent run in 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'])

Eseguire l'agente

Per eseguire l'agente, eseguire il comando seguente dalla directory src:

python simple_postgres_and_ai_agent.py

L'agente produce un risultato simile usando lo strumento Database di Azure per PostgreSQL per accedere ai dati del caso salvati nel database Postgres.

Frammento di output dell'agente:

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.

Passaggio 4: Test e debug con Azure AI Foundry Playground

Dopo aver eseguito l'agente con Azure AI Agent SDK, l'agente viene archiviato nel progetto ed è possibile provare l'agente nel playground di Agent.

Uso del playground dell'agente

Passare alla sezione Agenti in Azure AI Foundry
Trovare l'agente nell'elenco e Selezionare per aprire
Usare l'interfaccia del playground per testare varie query legali
Testare l'interrogazione “Perdita d'acqua nell'appartamento dal piano superiore, Quali sono i precedenti legali più rilevanti a Washington?” L'agente seleziona lo strumento giusto e chiede l'output previsto per l'interrogazione. Usare sample_vector_search_cases_output.json come output di esempio.

Passaggio 5: Debug con la traccia di Fonderia Azure AI

Quando si sviluppa l'agente usando Azure AI Foundry SDK, è possibile eseguire il debug dell'agente con Tracing., consentendo di eseguire il debug delle chiamate a strumenti come Postgres e vedere come l'agente orchestra ogni attività.

Debug con la traccia

Selezionare Traccia nel menu di Fonderia Azure AI
Crea una nuova risorsa di Application Insights o connetti una esistente
Visualizzare tracce dettagliate delle operazioni dell'agente

Altre informazioni su come configurare la traccia con l'agente di intelligenza artificiale e Postgres nel file advanced_postgres_and_ai_agent_with_tracing.py su GitHub.

Condividi tramite