Agentes de IA en Azure Database for PostgreSQL

2025-06-21

Los agentes de inteligencia artificial (IA) están transformando cómo interactúan las aplicaciones con los datos mediante la combinación de modelos de lenguaje grandes (LLM) con herramientas y bases de datos externas. Los agentes permiten la automatización de flujos de trabajo complejos, mejoran la precisión de la recuperación de información y facilitan las interfaces de lenguaje natural a las bases de datos. En este artículo se explora cómo crear agentes de inteligencia artificial inteligentes capaces de buscar y analizar los datos en Azure Database for PostgreSQL. Se explica la configuración, la implementación y las pruebas mediante un asistente de investigación legal como ejemplo.

¿Qué son los agentes de inteligencia artificial?

Los agentes de inteligencia artificial van más allá de bots de chat simples mediante la combinación de modelos de lenguaje grande (LLM) con herramientas y bases de datos externas. A diferencia de modelos LLM autónomos o sistemas RAG convencionales, los agentes de IA pueden:

Plan: divida las tareas complejas en pasos secuenciales más pequeños.
Usar herramientas: Usar APIs, la ejecución de código y los sistemas de búsqueda para recopilar información o realizar acciones.
Percibir: comprenda y procese las entradas de varios orígenes de datos.
Recuerde: Almacene y recuerde interacciones anteriores para mejorar la toma de decisiones.

Al conectar agentes de inteligencia artificial a bases de datos como Azure Database for PostgreSQL, los agentes pueden ofrecer respuestas más precisas y compatibles con el contexto en función de los datos. Los agentes de inteligencia artificial se extienden más allá de la conversación humana básica para realizar tareas basadas en lenguaje natural. Estas tareas tradicionalmente requerían lógica codificada; sin embargo, los agentes pueden planear las tareas necesarias para ejecutarse en función del contexto proporcionado por el usuario.

Implementación de agentes de IA

La implementación de agentes de inteligencia artificial con Azure Database for PostgreSQL implica la integración de funcionalidades avanzadas de inteligencia artificial con funcionalidades de base de datos sólidas para crear sistemas inteligentes y con reconocimiento de contexto. Al aprovechar herramientas como la búsqueda de vectores, las inserciones y el servicio agente de Azure AI, los desarrolladores pueden crear agentes capaces de comprender las consultas de lenguaje natural, recuperar datos relevantes y proporcionar información útil. En esta sección se describe el proceso paso a paso para configurar, configurar e implementar agentes de IA, lo que permite la interacción sin problemas entre los modelos de IA y la base de datos postgreSQL.

Marcos de trabajo

Varios marcos y herramientas pueden facilitar el desarrollo y la implementación de los agentes de inteligencia artificial. Todos estos marcos de trabajo admiten el uso de Azure Database for PostgreSQL como herramienta

Ejemplo de implementación

Usamos el Azure AI Agent Service para la planificación de agentes, el uso de herramientas y la percepción, mientras usamos Azure Database for PostgreSQL como una herramienta para capacidades de bases de datos vectoriales y búsqueda semántica.

En el tutorial, creamos un agente de inteligencia artificial que ayuda a los equipos legales a investigar casos relevantes para apoyar a sus clientes en el estado de Washington. Nuestro agente:

Acepte consultas de lenguaje natural sobre situaciones legales.
Use la búsqueda de vectores en Azure Database for PostgreSQL para encontrar precedentes de casos relevantes.
Analice y resuma los hallazgos en un formato útil para profesionales legales.

Prerrequisitos

Habilitar y configurarazure_ai & pg_vector extensión.
Cree un proyecto de Azure AI Foundry.
Implementación de modelosgpt-4o-mini & text-embedding-small
Instale Visual Studio Code.
Instale la extensión de Python .
Instale Python 3.11.x.
Instale la CLI de Azure.(versión más reciente)

Nota:

Necesita la clave y el punto de conexión de los modelos implementados que creó para el agente.

Cómo empezar

Todos los conjuntos de datos de código y ejemplo están disponibles en este repositorio de GitHub.

Paso 1: Configuración de la búsqueda de vectores en Azure Database for PostgreSQL

En primer lugar, preparamos nuestra base de datos para almacenar y buscar datos de casos legales mediante incrustaciones vectoriales:

Configuración del entorno

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

Configuración de las variables de entorno

Cree un .env archivo con sus credenciales:

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

Carga de documentos y vectores

El archivo de Python load_data/main.py sirve como punto de entrada central para cargar datos en Azure Database for PostgreSQL. El código procesa los datos de los casos de ejemplo, incluida la información sobre los casos en Washington.

Detalles generales de main.py:

Configuración de la base de datos y creación de tablas: crea extensiones necesarias, configura la configuración de la API de OpenAI y administra las tablas de base de datos quitando las existentes y creando otras nuevas para almacenar datos de casos.
Ingesta de datos: este proceso lee los datos de un archivo CSV e los inserta en una tabla temporal y, a continuación, los procesa y los transfiere a la tabla de casos principal.
Generación de Embeddings: agrega una nueva columna para embeddings en la tabla de casos y genera embeddings para las opiniones de casos mediante la API de OpenAI, almacenándolos en la nueva columna. El proceso de inserción tarda aproximadamente entre 3 y 5 minutos.

Para iniciar el proceso de carga de datos, ejecute el siguiente comando desde el directorio load_data :

python main.py

Esta es la salida 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!

Paso 2: Creación de una herramienta postgres para el agente

Estamos configurando herramientas de agentes de IA para recuperar datos de PostgreSQL y luego utilizar el SDK del servicio de agente de Azure AI para conectar tu agente de IA a la base de datos de PostgreSQL.

Definición de una función para que la llame su agente

Comience definiendo una función para que el agente llame mediante la descripción de su estructura y los parámetros necesarios en una docstring. Incluya todas las definiciones de función en un único archivo, legal_agent_tools.py, que puede importar en el 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 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

Paso 3: Creación y configuración del agente de IA con Postgres

Ahora configuraremos el agente de INTELIGENCIA ARTIFICIAL e lo integraremos con nuestra herramienta PostgreSQL. El archivo de Python src/simple_postgres_and_ai_agent.py sirve como punto de entrada central para crear y usar el agente.

Detalles generales de simple_postgres_and_ai_agent.py:

Creación de un agente: inicializa el agente en el proyecto de Azure AI con un modelo específico.
Agregar herramienta Postgres: durante la inicialización del agente, se agrega la herramienta Postgres para la búsqueda de vectores en la base de datos.
Crear un subproceso: configura un subproceso de comunicación. Se usa para enviar mensajes al agente para procesar
Ejecute la herramienta Agente y Llame a Postgres: procesa la consulta del usuario mediante el agente y las herramientas. El agente puede planificar utilizando herramientas para obtener la respuesta correcta. En este caso de uso, el agente llama a la herramienta Postgres basada en la firma de función y docstring para realizar una búsqueda vectorial y recuperar los datos pertinentes para responder a la pregunta.
Mostrar la respuesta del agente: esta función genera la respuesta del agente a la consulta del usuario.

Búsqueda de la cadena de conexión del proyecto en Azure AI Foundry

En el proyecto de Azure AI Foundry, encontrará la cadena de conexión del proyecto en la página Información general del proyecto. Usamos esta cadena para conectar el proyecto al SDK del agente de IA. Agregue esta cadena al archivo .env.

Captura de pantalla que muestra la página de configuración del proyecto.

Configuración de conexión

Agregue estas variables al archivo .env en el directorio raíz:

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
)

Crear hilo de comunicación

Este fragmento de código muestra cómo crear un subproceso de agente y un mensaje, que el agente procesa en una ejecución.

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

Procesamiento de la solicitud

Este fragmento de código crea una ejecución para que el agente procese el mensaje y use las herramientas adecuadas para proporcionar el mejor resultado.

Con la herramienta, el agente puede llamar a Postgres y la búsqueda de vectores en la consulta “Agua filtrando en el apartamento desde el piso anterior”* para recuperar los datos que necesita para responder mejor a la pregunta.

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'])

Ejecución del agente

Para ejecutar el agente, ejecute el siguiente comando desde el directorio src:

python simple_postgres_and_ai_agent.py

El agente genera un resultado similar mediante la herramienta Azure Database for PostgreSQL para acceder a los datos de casos guardados en la base de datos de Postgres.

Fragmento de salida del 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.

Paso 4: Prueba y depuración con el área de juegos de la Fundición de IA de Azure

Después de ejecutar tu agente con el SDK del agente de Azure AI, el agente se almacena en tu proyecto y puedes experimentar con el agente en la zona de pruebas del agente.

Uso del área de juegos del agente

Vaya a la sección Agentes de Azure AI Foundry.
Busque su agente en la lista y seleccione para abrir.
Use la interfaz del área de juegos para probar varias consultas legales
Pruebe la consulta "Agua filtrándose en el apartamento desde el piso de arriba, ¿Cuáles son los precedentes legales destacados en Washington?" El agente elige la herramienta adecuada que se va a usar y solicita el resultado esperado para esa consulta. Use sample_vector_search_cases_output.json como salida de ejemplo.

Paso 5: Depuración con seguimiento de Fundición de IA de Azure

Al desarrollar el agente mediante el SDK de Azure AI Foundry, puede depurar el agente con Tracing., lo que le permite depurar las llamadas a herramientas como Postgres y ver cómo el agente organiza cada tarea.

Depuración con seguimiento

Seleccione Seguimiento en el menú Azure AI Foundry.
Cree un nuevo recurso de Application Insights o conecte una
Vea los seguimientos detallados de las operaciones del agente

Obtenga más información sobre cómo configurar el seguimiento con el agente de IA y Postgres en el archivo advanced_postgres_and_ai_agent_with_tracing.py en GitHub.

Compartir a través de