Azure AI Search のエージェント検索を試してみた

今回は、Azure AI Search のエージェント検索を試してみます。
※2025/08時点のプレビュー機能の情報をもとに記載しています。

エージェント検索とは

Azure AI Searchの中で、エージェント的な動きをした検索ができる機能です。公式サイト には、複雑な質問に対応するように設計されたマルチクエリパイプラインとの説明があります。
具体的には、以下のような仕組みになっているとのことです。

・複雑なクエリをより小さい、焦点を絞ったサブクエリに分割
・複数のサブクエリを並列で実行
・LLMが独自回答できる応答の生成

エージェントに渡すクエリには、チャットの履歴を含めることができるため、会話の流れを意識した検索ができます。

早速試してみます。

前提条件

本記事は、以下の前提で記載しています。
・Azure AI Search の Basicプラン以上であり、セマンティックランク付け機能を有効化されている。
・Azure OpenAI リソースが用意されている。
・対象の検索インデックスが用意されている。

ナレッジエージェントを作成する

エージェント検索をする場合は、ナレッジエージェントを作成し、Azure AI Searchに登録する必要があります。ナレッジエージェントの作成には、対象となるインデックス情報やAzure OpenAIの接続情報が必要となります。
以下の例では、エージェント名を [agent-test]、対象インデックスを [index-document] としています。

agent = KnowledgeAgent(
    name="agent-test",
    models=[
        KnowledgeAgentAzureOpenAIModel(
            azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                resource_url=[Azure OpenAIエンドポイント],
                deployment_name=[Azure OpenAI デプロイ名],
                model_name=[GPTモデル名]
            )
        )
    ],
    target_indexes=[
        KnowledgeAgentTargetIndex(
            index_name="index-document",
            default_reranker_threshold=2.5
        )
    ],
)

search_credential = AzureKeyCredential([Azure AI Search APIキー])
index_client = SearchIndexClient(endpoint=endpoint, credential=search_credential)
index_client.create_or_update_agent(agent)

登録したエージェント情報は、エージェント一覧取得APIで確認できます。[search-name] や [api-key] は、環境に合わせて読み替えてください。

GET https://[search-name].search.windows.net/agents?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [api-key]

応答は以下のようになります。エージェントが Azure AI Search側に登録されていることが分かります。

{
  "@odata.context": "https://********.search.windows.net/$metadata#agents",
  "value": [
    {
      "@odata.etag": "\"0x8DDDEEA1FE15C20\"",
      "name": "agent-test",
      "description": null,
      "targetIndexes": [
        {
          "indexName": "index-document",
          "defaultRerankerThreshold": 2.5,
          "defaultIncludeReferenceSourceData": null,
          "defaultMaxDocsForReranker": null
        }
      ],
      "models": [
        {
          "kind": "azureOpenAI",
          "azureOpenAIParameters": {
            "resourceUri": "https://********.openai.azure.com",
            "deploymentId": "gpt-4.1-mini",
            "apiKey": null,
            "modelName": "gpt-4.1-mini",
            "authIdentity": null
          }
        }
      ],
      "requestLimits": null,
      "encryptionKey": null
    }
  ]
}

前の手順では、応答全体を確認するために API を直接コールしてみましたが、Pythonコードでもエージェント一覧を取得できます。

agents = index_client.list_agents()

登録済の特定のエージェントを取得する場合は、以下のようなコードで取得できます。

agent = index_client.get_agent([エージェント名])

取得パイプラインを実行する

ナレッジエージェントが作成できたら、取得パイプラインを実行します。この処理ので、[クエリの計画]、[クエリの事項]、[結果の合成]が行われます。

以下の検索文で試してみます。

Azureの概要と契約の種類を調べて

※ インデックスには、マイクロソフト社の「Azure 利用ガイド」を登録しています。

from azure.search.documents.agent import KnowledgeAgentRetrievalClient
from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, KnowledgeAgentIndexParams

instructions = """
質問に回答できるQ&Aエージェント。
ソースはJSON形式で、回答内に引用する必要があるref_idが含まれています。
ref_idは、そのまま表示すると意味が分からないため、対応するドキュメント名を示し、ref_idの表示は不要です。
回答が分からない場合は「分かりません」と回答してください。
"""

messages = [
    {
        "role": "system",
        "content": instructions
    }
]

agent_client = KnowledgeAgentRetrievalClient(endpoint=endpoint, agent_name=agent_name, credential=search_credential)

question = "Azureの概要と契約の種類を調べて"

messages.append({
    "role": "user",
    "content": question
})

retrieval_result = agent_client.retrieve(
    retrieval_request=KnowledgeAgentRetrievalRequest(
        messages=[KnowledgeAgentMessage(role=msg["role"], content=[KnowledgeAgentMessageTextContent(text=msg["content"])]) for msg in messages if msg["role"] != "system"],
        target_index_params=[KnowledgeAgentIndexParams(index_name=index_name, reranker_threshold=2.5)]
    )
)

# エージェントからの応答は、回答生成のためにチャット履歴に格納しておく
messages.append({
    "role": "assistant",
    "content": retrieval_result.response[0].content[0].text
})

どのような動きをしたか、以下のコードでアクティビティを確認できます。

import json

print("Activity")
print(json.dumps([a.as_dict() for a in retrieval_result.activity], indent=2, ensure_ascii=False))

今回のアクティビティは、以下のように出力されました。

Activity
[
  {
    "id": 0,
    "type": "ModelQueryPlanning",
    "input_tokens": 1342,
    "output_tokens": 198
  },
  {
    "id": 1,
    "type": "AzureSearchQuery",
    "target_index": "index-document",
    "query": {
      "search": "Azureの概要"
    },
    "query_time": "2025-08-19T12:49:02.979Z",
    "count": 3,
    "elapsed_ms": 463
  },
  {
    "id": 2,
    "type": "AzureSearchQuery",
    "target_index": "index-document",
    "query": {
      "search": "Azureの契約の種類"
    },
    "query_time": "2025-08-19T12:49:03.477Z",
    "count": 8,
    "elapsed_ms": 498
  },
  {
    "id": 3,
    "type": "AzureSearchSemanticRanker",
    "input_tokens": 108862
  }
]

「複雑なクエリをより小さい、焦点を絞ったサブクエリに分割」とありましたが、アクティビティを見るとその動きが確認できます。 [AzureSearchQuery] に「Azureの概要」と「Azureの契約の種類」を分けた形でクエリを生成していることが分かります。もとの質問文にある「調べて」という余計なキーワードも除外されており、Azure AI Searchに対しては、よりノイズの少ないクエリになっていると言えます。
また、Azure OpenAI で使用したトークン数も確認できます。

検索の応答データを確認してみると、以下のようになっていました。

[
  {
    "ref_id":0,
    "title":"Microsoft Azure 利用ガイド.pdf",
    "content":"https://learn.microsoft.com/ja-jp/entra/external-
id/b2b-fundamentals\nhttps://jpazasms.github.io/blog/AzureSubscriptionManagement/20180627a/\n\n\n©Microsoft
Corporation\n\nAzure \n\n主な関連サイト\nTitle : Microsoft Cost Management and Billing とは\n\nURL :
https://learn.microsoft.com/ja-jp/azure/cost-management-billing/cost-management-billing-\n\noverview\n\nTitle :
Microsoft Entra Connect とは\n\nURL : https://learn.microsoft.com/ja-jp/entra/fundamentals/whatis\n\nTitle : Azure
Lighthouse とは\n\nURL : https://learn.microsoft.com/ja-jp/azure/lighthouse/overview\n\nTitle : Microsoft
顧客契約の課金アカウントの概要\n\nURL : https://learn.microsoft.com/ja-jp/azure/cost-management-billing/understand/mca-
overview ～（中略）"
  },
  {
    "ref_id":1,
    "title":"Microsoft Azure 利用ガイド.pdf",
    "content":"Directory)\n\nネットワーク\n\n•
インターネット経由\n\n• Microsoft Entra ID 上で管理されているユー\n\nザーを利用してクラウド サービスへサインインを行う\n\n• 社内ネットワーク経由\n\n• オンプレミス AD     
上で管理されているユーザーを利\n\n用してアプリケーション サーバーにサインインを行う\n\n認証方法\n\n• クラウド サービスでの認証のために複数の認証プ\n\nロトコルに対応\n\n• 認証連携を行うクラウド サービスと
Microsoft \n\nEntra の間で、フェデレーションの設定が必要\n\n• ドメイン認証のために Kerberos、NTLM などの\n\n認証プロトコルを利用\n\nしくみ\n\nAzure
サブスクリプション\n\nMicrosoft 365\n\nユーザー ME-ID\n\nインターネット上\n\nSAML 認証等 AP サーバーユーザー オンプレミス
AD\n\n社内ネットワーク\n ～ (中略) "
  },
  {
    "ref_id":2,
    "title":"Microsoft Azure 利用ガイド.pdf",
    "content":"Microsoft Azure
利用ガイド\n\n日本マイクロソフト\n\n*本ドキュメントの情報は 2024 年 1 月時点のものです。\n\n\n\n©Microsoft Corporation\n\nAzure \n\n目次
0.\n\n1.\n\n2.\n\n3.\n\n4.\n\n5.\n\n6.\n\n7.\n\n8.\n\nはじめに\n\n基本情報\n\nライセンス契約形態について\n\n契約 /
利用開始に伴う留意点\n\n利用開始までの流れ\n\nサブスクリプション・コスト管理の手法\n\nAzure サポート一覧\n\nAppendix\n\n免責事項\n\n\n\n©Microsoft Corporation\n\nAzure   
\n\nはじめに\n\nこの利用ガイドには、Microsoft Azure の利用を開始するにあたり、\n\n確認していただくことが推奨される情報、および利用開始までの流れが記載されております。\n\nこのガイドの対象読者\n\n•
Azure のご利用を開始されるお客様\n\n• Azure のライセンスを購入したばかりで、Azure 利用開始までの流れを知りたいとお考えのお客様\n\n\n\n1. 基本情報\n\n\n\n©Microsoft       
Corporation\n\nAzure \n\nAzure を利用するにあたって知っておくべき用語\n ～(中略)"},
  {
    "ref_id":3,
    "title":"Microsoft Azure 利用ガイド.pdf",
    "content":"スイートなどのエンドユーザー向けのマイクロソフト製品を、ユー\n\nザー単位 / デバイス単位、またはその組み合わせのハイブリッドなライセンス オプションで利用できます。\n\n• ESA
(エンタープライズサブスクリプション加入契約)\n非永続ライセンスを利用できる加入契約で、契約期間中のみエンドユーザー向けのマイクロソフト製品を利用したいお客様向けのプログラムです。\n\nライセンス料金は、使用するライセンス数を 1
年ごとに計算するため、初期費用の削減だけでなく、年単位でライセンス数が増減する場合にも柔\n\n軟に対応できます。\n\n• SCE (サーバーおよびクラウド加入契約)\nWindows Server、System Center、SQL
Server、Visual Studio などのサーバー向けのマイクロソフト製品をクラウドに最適化されたライセンス\n\nオプションで利用できます。また、Microsoft Azure
のライセンスも提供しています。\n\n\n\n©Microsoft Corporation\n\nAzure \n\nEA 契約の構成\n\nマイクロソフトビジネスアグリーメント (MBA)\n\nマイクロソフトビジネス / サービス契約
 ～ (中略)"
 }
]

応答データに採用するセマンティックランク付けのリランカ―スコアには閾値を設定できます。エージェント作成時に [default_reranker_threshold] として登録しておくか、パイプライン実行時の [reranker_threshold] に値を設定することで、指定した値より低い回答は採用されなくなります。

回答を生成する

最後にエージェントの応答をもとに回答を Azure OpenAI で生成します。messages は、前までのコードにある、システムメッセージ、質問文、エージェントからの回答が含まれています。

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint=[Azure OpenAI エンドポイント],
    api_version=[Azure OpenAI APIバージョン],
    api_key=[Azure OpenAI APIキー]
)

response = client.chat.completions.create(
    model=[回答生成用モデル名],
    messages=messages
)

print(response.choices[0].message.content)

生成された回答は、以下の通りです。

Azureの概要と契約の種類について以下の通りです。

■ Azureの概要
AzureはMicrosoftが提供するクラウドコンピューティングサービスで、ID管理やアクセス制御にはMicrosoft Entra ID（旧Azure Active Directory）を利用します。Azure環境の管理単位と して「テナント」「サブスクリプション」「リソースグループ」「リソースオブジェクト」があり、利用料金の管理単位はサブスクリプションです。複数のサブスクリプションが同じMicrosoft Entraテナントに信頼される関係にありますが、サブスクリプションが複数のテナントを信頼することはできません。また、ユーザーは複数のサブスクリプションの管理者になることが 可能です。
（詳細は「Microsoft Azure 利用ガイド.pdf」の基本情報セクション参照）

■ Azureの契約の種類
Azureの基本的な契約形態は主に以下の3つに分けられます。

1. 従量課金プラン
- 個人または法人が利用可能
- MicrosoftのWebサイトから直接契約し、クレジットカードで支払うことが基本（請求書払いも条件次第で可能）
- いつでも解約可能
- 使用した分のみ支払う形態

2. CSP契約（Cloud Solution Provider契約）
- 法人向け
- CSPパートナー（販売代理店）を通じて契約
- 支払や価格、サポートはパートナーが担当し、パートナーから請求が行われる
- パートナーと直接連携してソリューションを設計・実装可能

3. EA契約（Enterprise Agreement）
- 法人向けで、通常3年契約
- LSP（ライセンスソリューションパートナー）を介して契約し、前払い（Prepayment）で年間一括支払いが一般的
- 複数のサブスクリプションを包括的に管理可能
- EA契約の内訳として、EA（Enterprise Agreement）、ESA（Enterprise Subscription Agreement）、SCE（Server and Cloud Enrollment）があり、SCEはサーバー・クラウド製品向けでAzure単独契約も可能
- 大規模導入向けで管理やコスト管理に適した契約形態

契約形態ごとに購入先、支払方法、請求通貨、契約期間、管理方法などが異なり、それぞれメリットがあります。
（詳細は「Microsoft Azure 利用ガイド.pdf」のライセンス契約形態についての章参照）

ご不明点があればお知らせください。

おわりに

今回は、Azure AI Search のエージェント検索の動きを試してみました。
独自に細かい実装をする必要が無ければ、Azure AI Search を使用したRAG構成がシンプルに実装できそうです。

QUICK E-Solutions では、Azure AI Searchを含む各 Azure AIサービスを利用したシステム導入のお手伝いをしております。それ以外でも様々なアプリケーションの開発・導入を行っております。提供するサービス・ソリューションにつきましては こちら に掲載しております。
システム開発・構築でお困りの問題や弊社が提供するサービス・ソリューションにご興味を抱かれましたら、是非一度 お問い合わせ ください。

※このブログで参照されている、Microsoft、Azure AI Search、その他のマイクロソフト製品およびサービスは、米国およびその他の国におけるマイクロソフトの商標または登録商標です。
※その他の会社名、製品名は各社の登録商標または商標です。