Azure Database for PostgreSQL の AI エージェント

AI エージェントは、大規模な言語モデル (LLM) と外部ツールとデータベースを組み合わせることによって、アプリケーションがデータと対話する方法を変換しています。 エージェントを使用すると、複雑なワークフローの自動化、情報取得の精度の向上、データベースへの自然言語インターフェイスの容易化が可能になります。

この記事では、Azure Database for PostgreSQL でデータを検索および分析できるインテリジェントな AI エージェントを作成する方法について説明します。 法律研究アシスタントを例として使用して、セットアップ、実装、テストについて説明します。

AI エージェントとは

AI エージェントは、LLM と外部ツールとデータベースを組み合わせることによって、単純なチャットボットを超えています。 スタンドアロンの LLM または標準の取得拡張生成 (RAG) システムとは異なり、AI エージェントは次のことができます。

• 計画: 複雑なタスクを、より小さい順番な手順に分割します。
• ツールの使用: API、コード実行、検索システムを使用して情報を収集したり、アクションを実行したりします。
• 認識: さまざまなデータ ソースからの入力を理解して処理します。
• 注意: 以前の操作を保存して思い出して、より適切な意思決定を行います。

AI エージェントを Azure Database for PostgreSQL などのデータベースに接続することで、エージェントはデータに基づいて、より正確でコンテキストに対応した応答を提供できます。 AI エージェントは、基本的な人間の会話を超えて、自然言語に基づいてタスクを実行します。 これらのタスクには、従来、コード化されたロジックが必要でした。 ただし、エージェントは、ユーザーが指定したコンテキストに基づいて実行に必要なタスクを計画できます。

AI エージェントの実装

Azure Database for PostgreSQL を使用して AI エージェントを実装するには、高度な AI 機能と堅牢なデータベース機能を統合して、インテリジェントなコンテキスト対応システムを作成する必要があります。 開発者は、ベクター検索、埋め込み、Azure AI Foundry Agent Service などのツールを使用して、自然言語クエリを理解し、関連するデータを取得し、実用的な分析情報を提供するエージェントを構築できます。

次のセクションでは、AI エージェントを設定、構成、デプロイする手順について説明します。 このプロセスにより、AI モデルと PostgreSQL データベース間のシームレスな対話が可能になります。

フレームワーク

各種のフレームワークとツールを使用することで、AI エージェントの開発とデプロイが容易になります。 これらのフレームワークはすべて、ツールとしての Azure Database for PostgreSQL の使用をサポートしています。

• Azure AI Foundry Agent Service
• LangChain/LangGraph
• LlamaIndex
• セマンティック カーネル
• AutoGen
• OpenAI Assistants API

実装例

この記事の例では、エージェントの計画、ツールの使用、および認識に Azure AI Foundry Agent Service を使用します。 ベクター データベースとセマンティック検索機能のツールとして Azure Database for PostgreSQL を使用します。

次のセクションでは、法務チームがワシントン州のクライアントをサポートするために関連するケースを調査するのに役立つ AI エージェントの構築について説明します。 エージェント:

1. 法的状況に関する自然言語クエリを受け入れます。
2. Azure Database for PostgreSQL のベクター検索を使用して、関連するケースの優先順位を見つけます。
3. 法的専門家にとって役立つ形式で調査結果を分析し、要約します。

[前提条件]

1. azure_aiとpg_vector拡張機能を有効にして構成します。

2. Azure AI Foundry プロジェクトを作成します。

3. モデルをデプロイしますgpt-4o-mini と text-embedding-small。

4. Visual Studio Code をインストールします。

5. Python 拡張機能をインストールします。

6. Python 3.11.x をインストールします。

7. Azure CLI (最新バージョン) をインストールします。

   注

   エージェント用に作成したデプロイ済みモデルのキーとエンドポイントが必要です。

作業の開始

すべてのコードとサンプル データセットは、 この GitHub リポジトリで入手できます。

手順 1: Azure Database for PostgreSQL でベクター検索を設定する

最初に、ベクター埋め込みを使用して訴訟ケースデータを格納および検索するようにデータベースを準備します。

環境をセットアップする

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

環境変数を構成する

資格情報を使用して .env ファイルを作成します。

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

ドキュメントとベクトルを読み込む

Python ファイル load_data/main.py は、Azure Database for PostgreSQL にデータを読み込むための中心的なエントリ ポイントとして機能します。 このコードは、ワシントンのケースに関する情報を含む サンプル ケースのデータを処理します。

main.py ファイル:

1. 必要な拡張機能を作成し、OpenAI API 設定を設定し、既存の拡張機能を削除し、ケース データを格納するための新しい拡張機能を作成してデータベース テーブルを管理します。
2. CSV ファイルからデータを読み取り、一時テーブルに挿入し、それを処理してメイン ケース テーブルに転送します。
3. ケース テーブルに埋め込み用の新しい列を追加し、OpenAI の API を使用してケースの意見の埋め込みを生成します。 埋め込みを新しい列に格納します。 埋め込みプロセスには約 3 ~ 5 分かかります。

データ読み込みプロセスを開始するには、 load_data ディレクトリから次のコマンドを実行します。

python main.py

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!

手順 2: エージェントの Postgres ツールを作成する

次に、Postgres からデータを取得するように AI エージェント ツールを構成します。 次に、Azure AI Foundry Agent Service SDK を使用して、AI エージェントを Postgres データベースに接続します。

エージェントが呼び出す関数を定義する

まず、エージェントの構造と docstring 内の必要なパラメーターを記述して、呼び出す関数を定義します。 すべての関数定義を 1 つのファイル ( legal_agent_tools.py) に含めます。 その後、ファイルをメイン スクリプトにインポートできます。

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

手順 3: Postgres を使用して AI エージェントを作成して構成する

次に、AI エージェントを設定し、Postgres ツールと統合します。 Python ファイル src/simple_postgres_and_ai_agent.py は、エージェントを作成して使用するための中心的なエントリ ポイントとして機能します。

simple_postgres_and_ai_agent.py ファイル:

1. 特定のモデルを使用して、Azure AI Foundry プロジェクトのエージェントを初期化します。
2. エージェントの初期化中に、データベースでベクター検索用の Postgres ツールを追加します。
3. 通信スレッドを設定します。 このスレッドは、処理のためにエージェントにメッセージを送信するために使用されます。
4. エージェントとツールを使用してユーザーのクエリを処理します。 エージェントは、正しい回答を得るためのツールを計画できます。 このユース ケースでは、エージェントは関数シグネチャと docstring に基づいて Postgres ツールを呼び出してベクター検索を実行し、関連するデータを取得して質問に回答します。
5. ユーザーのクエリに対するエージェントの応答を表示します。

Azure AI Foundry でプロジェクト接続文字列を検索する

Azure AI Foundry プロジェクトでは、プロジェクトの概要ページからプロジェクト接続文字列を見つけます。 この文字列を使用して、プロジェクトを Azure AI Foundry Agent Service SDK に接続します。 この文字列を .env ファイルに追加します。

接続を設定する

ルート ディレクトリの .env ファイルに次の変数を追加します。

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
)

通信スレッドを作成する

このコード スニペットは、エージェントが実行中に処理するエージェント スレッドとメッセージを作成する方法を示しています。

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

要求を処理する

次のコード スニペットは、エージェントがメッセージを処理し、適切なツールを使用して最適な結果を得るための実行を作成します。

このツールを使用することで、エージェントは Postgres を呼び出し、クエリ 「上の階からアパートに漏れる水」のベクター検索を呼び出して、質問に最適に回答するために必要なデータを取得できます。

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

エージェントの実行

エージェントを実行するには、 src ディレクトリから次のコマンドを実行します。

python simple_postgres_and_ai_agent.py

エージェントは、Azure Database for PostgreSQL ツールを使用して Postgres データベースに保存されたケース データにアクセスすることで、同様の結果を生成します。

エージェントからの出力のスニペットを次に示します。

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.

手順 4: エージェントプレイグラウンドを使用してテストとデバッグを行う

Azure AI Foundry Agent Service SDK を使用してエージェントを実行すると、エージェントがプロジェクトに格納されます。 あなたはエージェントの体験スペースでエージェントを試すことができます。

1. Azure AI Foundry で、[ エージェント] セクションに移動します。

2. 一覧でエージェントを見つけて選択して開きます。

3. プレイグラウンド インターフェイスを使用して、さまざまな法的クエリをテストします。

   

4. 「上の階からアパートに水が漏れる、ワシントンの著名な法的判例は何ですか?」というクエリをテストします。エージェントは、使用する適切なツールを選択し、そのクエリに対して予想される出力を要求します。 サンプル出力として sample_vector_search_cases_output.json を使用します。

   

手順 5: Azure AI Foundry トレースを使用してデバッグする

Azure AI Foundry Agent Service SDK を使用してエージェントを開発する場合は、 トレースを使用してエージェントをデバッグできます。 トレースを使用すると、Postgres などのツールの呼び出しをデバッグし、エージェントが各タスクを調整する方法を確認できます。

1. Azure AI Foundry で、[トレース] に移動 します。

2. 新しい Application Insights リソースを作成するには、[ 新規作成] を選択します。 既存のリソースを接続するには、[ Application Insights リソース名 ] ボックスで 1 つを選択し、[ 接続] を選択します。

   

3. エージェントの操作の詳細なトレースを表示します。

   

AI エージェントと Postgres を使用してトレースを設定する方法の詳細については、 GitHub の advanced_postgres_and_ai_agent_with_tracing.py ファイルを参照してください。

関連コンテンツ

• AI アプリケーション用の Azure Database for PostgreSQL の統合
• Azure Database for PostgreSQL で LangChain を使用する
• Azure Database for PostgreSQL で Azure OpenAI を使用してベクター埋め込みを生成する
• Azure Database for PostgreSQL の Azure AI 拡張機能
• Azure Database for PostgreSQL と Azure OpenAI を使用してセマンティック検索を作成する
• Azure Database for PostgreSQL で pgvector を有効にして使用する