Agentes de IA no Banco de Dados do Azure para PostgreSQL

2025-06-27

Os agentes de IA estão transformando a forma como os aplicativos interagem com os dados, combinando grandes modelos de linguagem (LLMs) com ferramentas e bancos de dados externos. Os agentes permitem a automação de fluxos de trabalho complexos, aumentam 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 de IA inteligentes que podem pesquisar e analisar seus dados no Banco de Dados do Azure para PostgreSQL. Ele percorre a configuração, implementação e teste usando um assistente de pesquisa jurídica como exemplo.

O que são agentes de IA?

Os agentes de IA vão além de simples chatbots, combinando LLMs com ferramentas e bancos de dados externos. Ao contrário dos LLMs autónomos ou dos sistemas padrão de geração com recuperação aumentada (RAG), os agentes de IA podem:

Planejar: divida tarefas complexas em etapas menores e sequenciais.
Use ferramentas: Use APIs, execução de código e sistemas de pesquisa para recolher informações ou executar ações.
Perceção: Compreender e processar entradas de várias fontes de dados.
Lembre-se: armazene e relembre 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 sensíveis ao contexto com base em seus dados. Os agentes de IA vão além da conversação humana básica para executar tarefas baseadas em linguagem natural. Essas tarefas tradicionalmente exigiam lógica codificada. No entanto, os agentes podem planejar as tarefas necessárias para executar 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 sensíveis ao contexto. Usando ferramentas como pesquisa vetorial, incorporações e Azure AI Foundry Agent Service, os desenvolvedores podem criar agentes que entendem consultas de linguagem natural, recuperam dados relevantes e fornecem insights acionáveis.

As seções a seguir descrevem o processo passo a passo para configurar, configurar e implantar agentes de IA. Esse processo permite uma interação perfeita entre os 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 estas estruturas suportam a utilização da Base de Dados do Azure para PostgreSQL como ferramenta:

Exemplo de implementação

O exemplo deste artigo usa o Azure AI Foundry Agent Service para planejamento de agentes, uso de ferramentas e perceção. Ele usa o Banco de Dados do Azure para PostgreSQL como uma ferramenta para banco de dados vetorial e recursos de pesquisa semântica.

As seções a seguir orientam você na criação de um agente de IA que ajuda as equipes jurídicas a pesquisar casos relevantes para apoiar seus clientes no Estado de Washington. O agente:

Aceita consultas em linguagem natural sobre situações legais.
Usa a pesquisa vetorial no Banco de Dados do Azure para PostgreSQL para encontrar precedentes de casos relevantes.
Analisa e resume os resultados num formato útil para os profissionais do direito.

Pré-requisitos

Habilite e configure as extensões azure_ai e pg_vector.
Crie um projeto do Azure AI Foundry.
Implantar modelosgpt-4o-mini e text-embedding-small.
Instalar o Visual Studio Code.
Instale a extensão Python .
Instale 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 exemplo estão disponíveis neste repositório GitHub.

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

Primeiro, prepare seu banco de dados para armazenar e pesquisar dados de casos legais usando incorporações vetoriais.

Configurar o ambiente

Se você estiver usando macOS e Bash, execute estes comandos:

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

Se você estiver usando o Windows e o PowerShell, execute estes comandos:

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

Se estiver a utilizar o Windows e cmd.exe, execute estes comandos:

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 para casos de amostra, incluindo informações sobre casos em Washington.

O ficheiro main.py

Cria as extensões necessárias, configura as configurações da API OpenAI e gerencia tabelas de banco de dados descartando as existentes e criando novas para armazenar dados de caso.
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.
Adiciona uma nova coluna para incorporações na tabela de casos e gera incorporações para opiniões de casos usando a API do OpenAI. Ele armazena as incorporações na nova coluna. O processo de incorporação leva cerca de 3 a 5 minutos.

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

python main.py

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

Etapa 2: Criar uma ferramenta Postgres para o agente

Em seguida, configure as ferramentas do agente de IA para recuperar dados do Postgres. Em seguida, use o SDK do Azure AI Foundry Agent Service para conectar seu agente de IA ao banco de dados Postgres.

Definir uma função para o seu agente chamar

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

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

Agora, configure o agente de IA e integre-o com a ferramenta Postgres. O arquivo Python src/simple_postgres_and_ai_agent.py serve como o ponto de entrada central para criar e usar seu agente.

O ficheiro simple_postgres_and_ai_agent.py

Inicializa o agente em seu projeto do Azure AI Foundry com um modelo específico.
Adiciona a ferramenta Postgres para pesquisa vetorial em seu banco de dados, durante a inicialização do agente.
Configura um thread de comunicação. Esse thread é usado para enviar mensagens ao agente para processamento.
Processa a consulta do usuário usando o agente e as ferramentas. O agente pode planejar com ferramentas para obter a resposta correta. Neste caso de uso, o agente chama a ferramenta Postgres com base na assinatura da função e docstring para fazer uma pesquisa vetorial e recuperar os dados relevantes para responder à pergunta.
Exibe 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 sua cadeia de conexão de projeto na página de visão geral do projeto. Use essa cadeia de caracteres para conectar o projeto ao SDK do Azure AI Foundry Agent Service. Adicione esta cadeia de caracteres ao .env arquivo.

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

Configurar a ligação

Adicione estas variáveis ao seu .env arquivo 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 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/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
)

Criar um thread de comunicação

Este trecho de código mostra como criar um thread e uma mensagem do agente, que o agente processa em uma execução:

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

Processar o pedido

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

Usando as ferramentas, o agente pode chamar o Postgres e a pesquisa vetorial na consulta "Água vazando para o apartamento do andar de cima" para recuperar os dados de que precisa para melhor responder à pergunta.

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

Execute o agente

Para executar o agente, execute o seguinte comando a partir do 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.

Aqui está um trecho da 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" do agente.

Depois de executar o agente usando o SDK do Azure AI Foundry Agent Service, o agente é armazenado em seu projeto. Você pode experimentar com o agente no playground do agente:

No Azure AI Foundry, vá para a seção Agentes .
Encontre seu agente na lista e selecione-o para abri-lo.
Utilize a interface do playground para testar várias consultas jurídicas.
Teste a consulta "Água vazando para o apartamento do andar acima, Quais são os precedentes legais proeminentes em Washington?" O agente escolhe a ferramenta certa para usar e solicita a saída esperada para essa consulta. Use sample_vector_search_cases_output.json como a saída de exemplo.

Etapa 5: Depurar com o rastreamento do Azure AI Foundry

Ao desenvolver o agente usando o SDK do Azure AI Foundry Agent Service, você pode depurar o agente com rastreamento. O rastreamento permite depurar as chamadas para ferramentas como o Postgres e ver como o agente orquestra cada tarefa.

No Azure AI Foundry, vá para Monitorização.
Para criar um novo recurso do Application Insights, selecione Criar novo. Para conectar um recurso existente, selecione um na caixa Nome do recurso do Application Insights e selecione Conectar.
Veja traços detalhados das operações do seu 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.

Partilhar via