🔎

Microsoft Foundryで利用できるWeb Searchをみてみる

に公開

LLMの「知識の鮮度問題」を埋める手段として、Microsoft Foundry(Azure AI Foundry)まわりでも Web検索系のツールがいくつか用意されています。今回は次の3つを、「何が違うのか」「どこをチューニングできるのか」などを整理します。

対象:

  1. Azure OpenAI Service の Responses API の Web Search Tool(web_search_preview)
  2. Microsoft Foundry Agent Service での Web Search Tool
    (web_search_preview をエージェントに付与)
  3. Microsoft Foundry Agent Service での Grounding with Bing Search
    (+ Bing Custom Search)

まず結論:どう使い分ける?

  • 「まずは簡単に最新情報で回答したい」
    → web_search_preview が最短。ツール追加して呼ぶだけ。エージェント管理が要らないなら Responses API直叩きがシンプル。

  • 「プロダクトとして構築したい(プロンプト、ツール、バージョン管理、運用)」
    → Agent Service + Web Search。エージェント定義をサーバ側で持てるのが強い。

  • 「検索結果の出し方を明示的に制御したい(件数、market、freshness、言語)」
    → Grounding with Bing Search(bing_grounding)。パラメータ粒度が高い。

差分観点 1) Responses API + web_search_preview 2) Foundry Agent Service + web_search_preview 3) Foundry Agent Service + bing_grounding(+ bing_custom_search_preview)
設定場所 呼び出し側(クライアント)で tools=[...] を都度渡す(必要なら tool_choice なども都度) サーバ側(Agent 定義)に tools=[WebSearchPreviewTool()] を固定し、呼び出し側は agent 参照で使う サーバ側(Agent 定義)に bing_grounding / bing_custom_search_preview を固定。加えて Foundry 側で Connection(Bing Grounding / Custom Search) を作ってそれを参照
ガバナンス シンプル。主に サブスクリプション単位の on/off(CLI feature flag)+クライアント側コードレビューで統制 Agent 定義の集中管理(instructions/tools/model)+Agent Versionで安全な更新/ロールバック。サブスク on/off も併用可 2) に加えて Connection 管理(利用可否・環境別・用途別の分離)までできる。検索条件(market/freshness/count/言語など)をコードで固定化しやすい
コンプラ影響 いずれも Bing Grounding 系の利用条件の影響を受ける(DPA 非適用・データ境界外へ流れ得る等)。PoC でも先に法務/セキュリティ確認が必要になりがち 1) と同じ(裏側は同系統)。「サーバ側で定義を固定できる」分、運用での逸脱は減らしやすい 1)/2) と同じ前提。加えて Connection を明示的に使うため、接続(どの Bing/Custom を使うか)単位で統制しやすい
パラメータ粒度 低い(location などの限定的な指定+「いつ検索するか」はモデルに委ねがち) 低い(ツール自体は 1) と同等)。ただし “運用面(定義固定・バージョン)” で差が出る 高い(count / market / freshness / set_lang などを明示制御)。Custom Search なら 許可ドメイン寄せも可能
UI表示要件 生成結果に含まれる 引用(citation) を UI に出せるようにするのが基本。特に外部向けプロダクトでは「参照元を隠さない」設計が必須 1) と同じ。ただし UI 実装を標準化しやすい(「この Agent は常に引用を返す」等の契約が作れる) 最も要注意:Bing Grounding / Custom Search の利用条件として、参照URL(サイト)だけでなく Bing の検索クエリ URL など “表示・保持が要求される情報” があるため、UI/ログ設計に最初から組み込むのが安全

前提:Web Searchは“Bing Grounding”を裏で使う(=データ境界に注意)

Web Search (preview) は内部的に Grounding with Bing Search / Bing Custom Search を使う、と明記されています。

検証・PoCでも、社内規約や顧客データの扱い的にここが最初の関門になりがちです。

実際の実装3パターン

1. Azure OpenAI Responses API の Web Search Tool(web_search_preview)

何ができる?

Responses API は Azure OpenAI の “stateful API” として紹介されていて、従来のChat Completions/Assistantsの良い所を統合している位置づけです。

この Responses API に tools を渡して web_search_preview を使うのが「Web Search Tool」です。

Sample code
from openai import OpenAI
import os

client = OpenAI(
  api_key=os.getenv("AZURE_OPENAI_API_KEY"),
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

resp = client.responses.create(
  model="gpt-4.1",  # デプロイ名
  tools=[{
    "type": "web_search_preview",
    "user_location": {"type": "approximate", "country": "JP"}
  }],
  input="Give me a positive news story from the web today"
)

print(resp.output_text)

調整できるパラメータ(Responses API + Web Search)

A) ツール側(web_search_preview)

現状、Microsoft Learn(公式ドキュメント)上で明示されているパラメータは限定的です。

  • user_location.type
    • 値:approximate
    • 意味:ユーザーの位置情報が「概算」であることを示す
  • user_location.country
    • 値:国コード(例:JP)
    • 意味:検索時に利用されるユーザーの国情報

⚠️ 注意
「検索の市場(market)」「言語(language)」「freshness」「件数(count)」といった **細かい検索制御をしたい際は、後述の bing_grounding(Grounding with Bing Search) を使うのが現実的な選択肢になります。

B) リクエスト側(Responses API 全般:検索の使われ方に効く)

Web Search 専用というより、**「モデルがいつ・どのようにツールを呼ぶか」**に影響するパラメータ群が重要です。

  • tool_choice
    • 値:none / auto / required
    • 意味:ツール呼び出しの制御方法
  • tools
    • 意味:モデルに渡すツール定義の配列
  • parallel_tool_calls
    • 意味:複数ツールの並列呼び出しを許可するかどうか
  • reasoning.effort
    • 値:low / medium / high
    • 意味:推論モデルに割り当てる思考量の目安
  • max_output_tokens
    • 意味:出力トークン数の上限(思考トークンを含む)
  • stream
    • 意味:SSE(Server-Sent Events)によるストリーミング出力を行うか
  • store
    • 意味:レスポンスを保存し、後から retrieve 可能にするか
  • include
    • 意味:追加の出力メタデータ(ツール出力の一部など)を含めるか

追加検討事項

  • 「検索させたいのに検索しない」場合
    → tool_choice="required" を検討
    ※ただし乱用すると 無駄な検索が増え、コスト・レイテンシが悪化する

  • 「速さ優先」のユースケース
    → reasoning.effort を下げる、または非推論寄りのモデルを使う

  • 「調査レポート用途」
    → o3-deep-research + web_search +(必要に応じて)code_interpreter

管理(サブスクリプション単位で有効 / 無効)

  • web_search_preview は Azure CLI を使ってサブスクリプション単位で有効化・無効化が可能

運用上のポイント

  • 「セキュリティ審査が通ったサブスクリプションだけ Web Search を許可する」
  • といった ガバナンス設計がしやすい のが Azure 側の特徴

2. Foundry Agent Service での Web Search Tool

(エージェント + web_search_preview)
Microsoft Foundry (New) の Agent Service は、旧来の Assistants API ベースではなく、Responses API を土台にした"Modern API Primitive" として設計されています。
そのため、Responses API で提供されている Web Search Tool(web_search_preview)を、エージェントのツールとしてそのまま利用できる構造になっています。

何が嬉しい?

実態としては Responses API の web_search_preview と同じツールですが、
エージェント定義(model / instructions / tools)をサーバ側に保持できる点が大きなメリットです。

  • だれが使っても同じ 「検索できるアシスタント」 を再現できる
  • バージョニング(Agent Version) による安全な更新・ロールバックが可能
  • ツールの付け替え や プロンプトの運用 がやりやすい

作成方法

パータンA

New Foundry の UIを用いれば 数クリックで設定完了

New Foundry UI での設定画面

パータンB

  1. エージェント作成時に WebSearchPreviewTool() を付与
    • PromptAgentDefinition の tools に指定する
Sample code
"""
【概要】
このサンプルは、Microsoft Foundry Agent Service を使って
「Web検索ツールを利用できるエージェント」を作成し、
同期クライアントで質問を投げて結果を受け取る方法を示しています。

【実行方法】
    python sample_agent_web_search.py

【事前準備】
1. 必要なライブラリをインストール
    pip install "azure-ai-projects>=2.0.0b1" python-dotenv

2. 以下の環境変数を設定しておく
   - AZURE_AI_PROJECT_ENDPOINT
     → Microsoft Foundry ポータルの Overview にあるエンドポイント
   - AZURE_AI_MODEL_DEPLOYMENT_NAME
     → Foundry の「Models + endpoints」に表示されるモデルのデプロイ名
"""

import os
from dotenv import load_dotenv

# Azure AD 認証用(マネージド ID / ローカルログインなどを自動判別)
from azure.identity import DefaultAzureCredential

# Azure AI Projects のクライアント
from azure.ai.projects import AIProjectClient

# エージェント定義や Web 検索ツール関連のモデル
from azure.ai.projects.models import (
    PromptAgentDefinition,
    WebSearchPreviewTool,
    ApproximateLocation,
)

# .env ファイルから環境変数を読み込む
load_dotenv()

# Azure AI Project のエンドポイントを環境変数から取得
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# with 文で各クライアントをまとめて管理
# → 処理終了時に自動でクローズされる
with (
    # Azure 認証情報を取得
    DefaultAzureCredential() as credential,

    # AI Project クライアントを作成
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,

    # OpenAI 互換 API クライアントを取得
    project_client.get_openai_client() as openai_client,
):
    # ================================
    # Web 検索ツールの定義
    # ================================

    # WebSearchPreviewTool を作成
    # user_location を指定すると、検索結果がその地域向けに最適化される
    # (ここでは日本・東京)
    tool = WebSearchPreviewTool(
        user_location=ApproximateLocation(
            country="JP",
            city="Tokyo",
            region="Tokyo"
        )
    )

    # ================================
    # エージェントの作成
    # ================================

    # Web検索ツールを使える Prompt Agent を作成
    agent = project_client.agents.create_version(
        agent_name="MyAgent",  # エージェント名
        definition=PromptAgentDefinition(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],  # 使用するモデル
            instructions="You are a helpful assistant that can search the web",
            tools=[tool],  # Web検索ツールを有効化
        ),
        description="Agent for web search.",  # エージェントの説明
    )

    # 作成されたエージェントの情報を表示
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    # ================================
    # 会話(Conversation)の作成
    # ================================

    # エージェントとのやり取り用に会話を作成
    conversation = openai_client.conversations.create()
    print(f"Created conversation (id: {conversation.id})")

    # ================================
    # エージェントに質問を送信
    # ================================

    # Web検索を使った質問を送信
    response = openai_client.responses.create(
        conversation=conversation.id,  # どの会話かを指定
        input="Show me the latest London Underground service updates",  # ユーザー入力
        extra_body={
            # 使用するエージェントを指定
            "agent": {
                "name": agent.name,
                "type": "agent_reference"
            }
        },
    )

    # エージェントからの最終的なテキスト回答を表示
    print(f"Agent response: {response.output_text}")

    # ================================
    # 後処理(クリーンアップ)
    # ================================

    print("\nCleaning up...")

    # 作成したエージェントのバージョンを削除
    project_client.agents.delete_version(
        agent_name=agent.name,
        agent_version=agent.version
    )

    print("Agent deleted")

“検索のモード”の考え方が明示されている

Agent Service の Web Search Tool ドキュメントでは、
用途別に以下の検索モードが整理されています。

  • Non reasoning web search

    • 高速
    • 単発検索向け
  • Reasoning web search

    • GPT-5などの推論モデルが検索を能動的に実行
    • 複数検索を組み合わせた回答向け
  • Deep Research

    • o3-deep-researchとともに実行する長時間実行
    • 複数ページ参照
    • 引用多めの包括的な調査向け

調整できるパラメータ(Agent Service + Web Search)

A) エージェント定義側

エージェント作成時に固定的に持たせる設定です。

  • model :このエージェントで使用するモデル

  • instructions :エージェントの振る舞いを定義する system / developer 指示

  • tools : tools=[WebSearchPreviewTool()]として持たせる


B) 呼び出し(Responses)側

ここは Responses API と同じパラメータ設計で、
「検索の使われ方」を動的に制御できます。

  • stream
  • tool_choice
  • parallel_tool_calls
  • reasoning.effort
  • max_output_tokens
  • など

※ パラメータ自体は Responses API の仕様に依存

管理(ここもサブスクリプション単位)

  • Agent Service 側でも Web Search Tool をサブスクリプション単位で有効 / 無効化 可能
  • Azure CLI で制御できる

3. Foundry Agent Service での Grounding with Bing Search(bing_grounding)

Web Search Tool と何が違う?

web_search_preview は 「検索 → 引用 → 回答生成」までを抽象化したツールで、
検索の細かい挙動はモデル側に委ねられています。

一方で bing_grounding は、検索設定を明示的に指定できるのが大きな特徴です。

  • 接続(Connection)
  • 市場(market)
  • 検索結果件数(count)
  • freshness(期間)
  • 言語(set_lang)

といった Bing Search API 相当の検索条件をコードで制御できます。


New Foundry UI での設定画面

まず接続(project_connection_id)が必要

bing_grounding を使う場合、
Foundry 側で作成した “Connections(Grounding with Bing Search)” を前提とします。

ツール定義の中で
project_connection_id(または connection_id)を指定する形が示されています。

調整できるパラメータ(Bing Search)

Microsoft Learn で明示されている、代表的なパラメータは以下です。

  • count

    • 意味:検索結果の件数
  • freshness

    • 意味:検索対象期間
    • 例:Day / Week / Month
  • market

    • 意味:検索市場(リージョン)
    • 例:en-US, ja-JP
  • set_lang

    • 意味:検索結果の言語
    • 例:en, ja
  • project_connection_id(または connection_id)

    • 意味:Foundry の Connection を参照するための ID
    • 必須項目 である

さらに:Bing Custom Search も扱える(ドメイン縛りなど)

Bing Custom Search を利用する例も紹介されています。
また、対象は公開され Bing に index されているものに限られます。

Custom Search では instance_name を指定でき、

  • 特定ドメインを中心に検索したい
  • 社内で許可したサイトだけを対象にしたい

といった ガバナンスや設計要件に寄せた検索が可能になります。


Bing Custom Search 任意のドメイン設定画面


New Foundry UI での設定画面

まとめ

  • 最短で最新情報の引用付き回答なら web_search_preview(Responses API直叩き)
  • エージェント運用(定義の管理・再利用・バージョン)をしたいなら Agent Service + Web Search
  • 検索の挙動をパラメータでちゃんとコントロールしたいなら bing_grounding(検索ドメインを絞りたいなら Custom Search も)

参考リンク

https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/web-search?view=foundry
https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/web-search?view=foundry&pivots=python
https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/bing-tools?view=foundry&tabs=grounding-with-bing&pivots=python
https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/migrate?view=foundry
https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects/samples/agents/tools

Microsoft (有志)

Discussion