Agentes de IA no Banco de Dados do Azure para PostgreSQL

2025-06-22

Agentes de IA (Inteligência Artificial) estão transformando como os aplicativos interagem com dados combinando LLMs (modelos de linguagem grande) com ferramentas e bancos de dados externos. Os agentes habilitam a automação de fluxos de trabalho complexos, aprimoram a precisão da recuperação de informações e facilitam interfaces de linguagem natural para bancos de dados. Este artigo explora como criar agentes inteligentes de IA capazes de pesquisar e analisar seus dados no Banco de Dados do Azure para PostgreSQL. Percorremos a instalação, a implementação e o teste usando um assistente de pesquisa legal como nosso exemplo.

O que são agentes de IA?

Os agentes de IA vão além de chatbots simples combinando LLMs (grandes modelos de linguagem) com bancos de dados e ferramentas externas. Ao contrário de LLMs autônomas ou sistemas RAG padrão, os agentes de IA podem:

Plano: dividir tarefas complexas em etapas menores e sequenciais.
Usar Ferramentas: use APIs, execução de código e sistemas de pesquisa para reunir informações ou realizar ações.
Percepção: entenda e processe entradas de várias fontes de dados.
Lembre-se: armazene e lembre-se das interações anteriores para uma melhor tomada de decisão.

Ao conectar agentes de IA a bancos de dados como o Banco de Dados do Azure para PostgreSQL, os agentes podem fornecer respostas mais precisas e com reconhecimento de contexto com base em seus dados. Os agentes de IA vão além da conversa humana básica para executar tarefas com base na linguagem natural. Essas tarefas tradicionalmente exigiam lógica codificada; no entanto, os agentes podem planejar as tarefas necessárias para serem executadas com base no contexto fornecido pelo usuário.

Implementação de agentes de IA

A implementação de agentes de IA com o Banco de Dados do Azure para PostgreSQL envolve a integração de recursos avançados de IA com funcionalidades robustas de banco de dados para criar sistemas inteligentes e com reconhecimento de contexto. Aproveitando ferramentas como pesquisa de vetor, inserções e Serviço do Agente de IA do Azure, os desenvolvedores podem criar agentes capazes de entender consultas de linguagem natural, recuperar dados relevantes e fornecer insights acionáveis. Esta seção descreve o processo passo a passo para configurar, configurar e implantar agentes de IA, permitindo a interação perfeita entre modelos de IA e seu banco de dados PostgreSQL.

Estruturas

Várias estruturas e ferramentas podem facilitar o desenvolvimento e a implantação de agentes de IA. Todas essas estruturas dão suporte ao uso do Banco de Dados do Azure para PostgreSQL como uma ferramenta

Exemplo de implementação

Usamos o Serviço do Agente de IA do Azure para planejamento de agente, uso de ferramentas e percepção ao usar o Banco de Dados do Azure para PostgreSQL como uma ferramenta para recursos de pesquisa semântica e de banco de dados vetor.

No tutorial, criamos um agente de IA que ajuda as equipes jurídicas a pesquisar casos relevantes para dar suporte a seus clientes no estado de Washington. Nosso agente:

Aceite consultas de linguagem natural sobre situações legais.
Use a pesquisa de vetor no Banco de Dados do Azure para PostgreSQL para encontrar precedentes de caso relevantes.
Analisar e resumir os resultados em um formato útil para profissionais jurídicos.

Pré-requisitos

Habilitar e configurarazure_ai e pg_vector extensão.
Crie um Projeto Azure AI Foundry.
Implantar modelosgpt-4o-mini & text-embedding-small
Instalar o Visual Studio Code.
Instale a extensão do Python .
Instale o Python 3.11.x.
Instale a CLI do Azure.(versão mais recente)

Observação

Você precisa da chave e do ponto de extremidade dos modelos implantados que criou para o agente.

Como começar

Todos os conjuntos de dados de código e de exemplo estão disponíveis neste repositório GitHub.

Etapa 1: Configurar a pesquisa de vetor no Banco de Dados do Azure para PostgreSQL

Primeiro, preparamos nosso banco de dados para armazenar e pesquisar dados de casos legais usando inserções de vetor:

Configuração do ambiente

Se estiver usando 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

Configurar variáveis de ambiente

Crie um .env arquivo com suas credenciais:

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

Carregar documentos e vetores

O arquivo Python load_data/main.py serve como o ponto de entrada central para carregar dados no Banco de Dados do Azure para PostgreSQL. O código processa os dados de casos de exemplo, incluindo informações sobre casos em Washington.

Detalhes de alto nível de main.py:

Configuração de banco de dados e criação de tabela: cria extensões necessárias, define as configurações da API OpenAI e gerencia tabelas de banco de dados descartando as existentes e criando novas para armazenar dados de caso.
Ingestão de dados: esse processo lê dados de um arquivo CSV e os insere em uma tabela temporária e, em seguida, processa e transfere-os para a tabela de casos principal.
Geração de inserção: adiciona uma nova coluna para inserções na tabela de casos e gera inserções para opiniões de caso usando a API do OpenAI, armazenando-as na nova coluna. O processo de inserção leva cerca de 3 a 5 minutos

Para iniciar o processo de carregamento de dados, execute o seguinte comando no diretório load_data :

python main.py

Aqui está a saída do 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!

Etapa 2: Criar uma ferramenta postgres para o agente

Estamos configurando ferramentas de agente de IA para recuperar dados do Postgres e, em seguida, usando o SDK do Serviço do Agente de IA do Azure para conectar seu agente de IA ao banco de dados Postgres.

Defina uma função para o agente chamar

Comece definindo uma função para seu agente chamar descrevendo sua estrutura e todos os parâmetros necessários em uma docstring. Inclua todas as definições de função em um único arquivo , legal_agent_tools.py, que você pode importar para o 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

Etapa 3: Criar e configurar o agente de IA com o Postgres

Agora, configuraremos o agente de IA e o integraremos à nossa ferramenta PostgreSQL. O src/simple_postgres_and_ai_agent.py do arquivo Python serve como o ponto de entrada central para criar e usar seu agente.

Detalhes de alto nível de simple_postgres_and_ai_agent.py:

Criar um agente: inicializa o agente em seu Projeto de IA do Azure com um modelo específico.
Adicionar Ferramenta Postgres: durante a inicialização do agente, a ferramenta Postgres é adicionada para pesquisa de vetor em seu banco de dados.
Criar um Thread: configura um thread de comunicação. Isso é usado para enviar mensagens ao agente para processar
Executar o Agente e Chamar a ferramenta Postgres: Processa a consulta do usuário usando o agente e as ferramentas. O agente pode planejar com ferramentas a serem usadas para obter a resposta correta. Nesse caso de uso, o agente chama a ferramenta Postgres com base na assinatura da função e docstring para fazer uma pesquisa de vetor e recuperar os dados relevantes para responder à pergunta.
Exibir a resposta do agente: essa função gera a resposta do agente à consulta do usuário.

Localizar a cadeia de conexão do projeto no Azure AI Foundry

Em seu projeto do Azure AI Foundry, você encontra a cadeia de conexão do projeto na página Visão geral do projeto. Usamos essa cadeia de caracteres para conectar o projeto ao SDK do agente de IA. Adicione essa cadeia de caracteres ao arquivo .env.

Captura de tela mostrando a página de configuração do projeto.

Configuração da conexão

Adicione essas variáveis ao arquivo .env no diretório raiz:

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
)

Criar tópico de comunicação

Esse trecho de código mostra como criar uma conversa e uma mensagem de agente, que o agente processa em uma execução.

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

Processar a solicitação

Esse snippet de código cria uma execução para o agente processar a mensagem e usar as ferramentas apropriadas para fornecer o melhor resultado.

Usando a ferramenta, o agente pode chamar o seu banco de dados Postgres e realizar uma busca vetorial na consulta "Vazamento de água no apartamento do andar acima" para recuperar os dados necessários para responder da melhor forma possível à pergunta.

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

Executar o agente

Para executar o agente, execute o seguinte comando no diretório src:

python simple_postgres_and_ai_agent.py

O agente produz um resultado semelhante usando a ferramenta Banco de Dados do Azure para PostgreSQL para acessar dados de caso salvos no Banco de Dados Postgres.

Trecho de saída do 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.

Etapa 4: testar e depurar com o playground da Fábrica de IA do Azure

Depois de executar seu agente com o SDK do Agente de IA do Azure, o agente é armazenado em seu projeto e você pode experimentar o agente no playground do Agente.

Usar o playground do agente

Navegue até a seção Agentes no Azure AI Foundry
Localize seu agente na lista e selecione para abrir
Use a interface do playground para testar várias consultas jurídicas
Teste a consulta "Água vazando para o apartamento do chão acima, Quais são os proeminentes precedentes legais em Washington?" O agente escolhe a ferramenta certa a ser usada e solicita a saída esperada para essa consulta. Use sample_vector_search_cases_output.json como a saída de exemplo.

Etapa 5: depuração com rastreamento da Fábrica de IA do Azure

Ao desenvolver o agente usando o SDK do Azure AI Foundry, você pode depurar o agente com o Tracing., permitindo que você depure as chamadas para ferramentas como o Postgres e veja como o agente orquestra cada tarefa.

Depuração com rastreamento

Selecione Rastreamento no menu do Azure AI Foundry
Crie um novo recurso do Application Insights ou conecte uma
Exibir rastreamentos detalhados das operações do agente

Saiba mais sobre como configurar o rastreamento com o agente de IA e o Postgres no arquivo advanced_postgres_and_ai_agent_with_tracing.py no GitHub.

Compartilhar via