次の方法で共有

Foundry IQ ナレッジ ベースを Foundry Agent Service に接続する

Important

この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

この記事では、Microsoft Foundry のエージェントを、Azure AI Search を利用したエージェント検索ワークロードである Foundry IQ のナレッジ ベースに接続する方法について説明します。 接続では、モデル コンテキスト プロトコル (MCP) を使用して、ツールの呼び出しを容易にします。 エージェントによって呼び出されると、ナレッジ ベースは次の操作を調整します。

  • ユーザー クエリを計画し、サブクエリに分解します。
  • キーワード、ベクター、またはハイブリッド手法を使用して、サブクエリを同時に処理します。
  • セマンティック再ランク付けを適用して、最も関連性の高い結果を識別します。
  • ソース参照を使用して結果を統合された応答に合成します。

エージェントは、応答を使用してエンタープライズ データまたは Web ソースで回答を作成し、ソースの属性を通じて事実の正確さと透明性を確保します。

知識を取得するために Azure AI Search と Foundry Agent Service を統合するエンド ツー エンドの例については、GitHub の agentic-retrieval-pipeline-example Python サンプルを参照してください。

利用サポート

Microsoft Foundry のサポート Python SDK C# SDK JavaScript SDK Java SDK REST API 基本エージェントのセットアップ 標準エージェントのセットアップ
✔️ ✔️ - - - ✔️ ✔️ ✔️

[前提条件]

認証とアクセス許可

運用環境のデプロイでは、ロールベースのアクセス制御をお勧めします。 ロールが実現できない場合は、このセクションをスキップし、代わりにキーベースの認証を使用してください。

  • プロジェクトの親リソースで、モデルのデプロイにアクセスしてエージェントを作成するには 、Azure AI ユーザー ロールが必要です。 所有者は 、リソースの作成時に自動的にこのロールを取得します。 他のユーザーには、特定のロールの割り当てが必要です。 詳細については、 Foundry ポータルでのロールベースのアクセス制御に関するページを参照してください。
  • プロジェクトの親リソースでは、MCP 認証用のプロジェクト接続を作成するための Azure AI Project Manager ロールと、エージェントで MCP ツールを使用するための Azure AI ユーザー または Azure AI Project Manager が必要です。
  • プロジェクトで、Azure AI Search と対話するためのシステム割り当てマネージド ID を作成します。

Foundry IQ について

Foundry IQ は、ドメイン知識とエージェント ロジックの間で懸念事項を分離し、取得拡張生成 (RAG) と大規模な接地を可能にします。 取得の複雑さを各エージェントにバンドルする代わりに、人事や販売などの知識の完全なドメインを表すナレッジ ベースを作成します。 その後、エージェントはナレッジ ベースを呼び出して、関連する up-to-date 情報で応答を作成します。

この分離には、次の 2 つの主な利点があります。

  • エージェントを変更することなく、ナレッジ ベースを個別に更新できます。
  • 複数のエージェントが同じナレッジ ベースを共有できるため、構成の重複を回避できます。

Foundry IQ のしくみ

Azure AI Search を利用した Foundry IQ は、ナレッジ ソース (取得するもの) とナレッジ ベース (取得方法) で構成されます。 ナレッジ ベースは、サブクエリを計画して実行し、引用文献を使用して書式設定された結果を出力します。

ナレッジ ベースでは 回答合成がサポートされていますが、Foundry Agent Service との統合には抽出データ出力モードをお勧めします。 このモードにより、エージェントは事前に生成された回答ではなく逐語的なコンテンツを受け取り、応答形式と品質を完全に制御できます。

Foundry Agent Service でナレッジ ベースを使用する方法

Foundry Agent Service は、MCP ツールを使用してナレッジ ベースへの呼び出しを調整し、最終的な回答を合成します。 実行時に、エージェントはナレッジ ソースの基になるデータ プラットフォーム (Azure Blob Storage や Microsoft OneLake など) ではなく、ナレッジ ベースのみを呼び出します。 ナレッジ ベースは、すべての取得操作を処理します。

プロジェクト接続を作成する

Microsoft Foundry プロジェクトで RemoteTool 接続を作成します。 この接続では、プロジェクトのマネージド ID を使用してナレッジ ベースの MCP エンドポイントをターゲットにし、エージェントが取得操作のために Azure AI Search と安全に通信できるようにします。

import requests
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Provide connection details
credential = DefaultAzureCredential()
project_resource_id = "{project_resource_id}" # e.g. /subscriptions/{subscription}/resourceGroups/{resource_group}/providers/Microsoft.MachineLearningServices/workspaces/{account_name}/projects/{project_name}
project_connection_name = "{project_connection_name}"
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2025-11-01-preview" # This endpoint enables the MCP connection between the agent and knowledge base

# Get bearer token for authentication
bearer_token_provider = get_bearer_token_provider(credential, "https://management.azure.com/.default")
headers = {
  "Authorization": f"Bearer {bearer_token_provider()}",
}

# Create project connection
response = requests.put(
  f"https://management.azure.com{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview",
  headers = headers,
  json = {
    "name": "project_connection_name",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "ProjectManagedIdentity",
      "category": "RemoteTool",
      "target": mcp_endpoint,
      "isSharedToAll": True,
      "audience": "https://search.azure.com/",
      "metadata": { "ApiType": "Azure" }
    }
  }
)

response.raise_for_status()
print(f"Connection '{project_connection_name}' created or updated successfully.")

ナレッジを取得するためのエージェント命令を最適化する

ナレッジ ベース呼び出しの精度を最大限に高め、適切な引用書式を確保するには、最適化されたエージェント命令を使用します。 実験に基づいて、開始点として次の命令テンプレートを使用することをお勧めします。

You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.
Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`
If you cannot find the answer in the provided knowledge base you must respond with "I don't know".

この命令テンプレートは、次の目的で最適化されます。

  • MCP ツールの呼び出し速度が高い: 明示的なディレクティブにより、エージェントはトレーニング データに依存するのではなく、ナレッジ ベース ツールを一貫して呼び出します。
  • 適切な注釈の書式設定: 指定された引用形式により、エージェントが応答に実績情報を確実に含め、どのナレッジ ソースが使用されたかが明確になります。

ヒント

このテンプレートは強力な基盤を提供しますが、特定のユース ケースと目的に基づいて命令を評価し、反復処理します。 さまざまなバリエーションをテストして、シナリオに最適なものを見つけます。

MCP ツールを使用してエージェントを作成する

ナレッジ ベースを MCP ツールとして統合するエージェントを作成します。 エージェントは、システム プロンプトを使用して、ナレッジ ベースを呼び出すタイミングと方法を指示します。 質問に回答する手順に従い、会話セッション間でツールの構成と設定を自動的に維持します。

前に作成したプロジェクト接続を使用して、ナレッジ ベースの MCP ツールを追加します。 このツールは、構成されたナレッジ ソース全体でクエリの計画、分解、および取得を調整します。 エージェントはこのツールを使用してクエリに応答します。

注

Azure AI Search ナレッジ ベースは、エージェント統合用の knowledge_base_retrieve MCP ツールを公開します。 これは、Foundry Agent Service での使用が現在サポートされている唯一のツールです。

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool
from azure.identity import DefaultAzureCredential

# Provide agent configuration details
credential = DefaultAzureCredential()
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2025-11-01-preview"
project_endpoint = "{project_endpoint}" # e.g. https://your-foundry-resource.services.ai.azure.com/api/projects/your-foundry-project
project_connection_name = "{project_connection_name}"
agent_name = "{agent_name}"
agent_model = "{deployed_LLM}" # e.g. gpt-4.1-mini

# Create project client
project_client = AIProjectClient(endpoint = project_endpoint, credential = credential)

# Define agent instructions (see "Optimize agent instructions" section for guidance)
instructions = """
You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.
Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`
If you cannot find the answer in the provided knowledge base you must respond with "I don't know".
"""

# Create MCP tool with knowledge base connection
mcp_kb_tool = MCPTool(
    server_label = "knowledge-base",
    server_url = mcp_endpoint,
    require_approval = "never",
    allowed_tools = ["knowledge_base_retrieve"],
    project_connection_id = project_connection_name
)

# Create agent with MCP tool
agent = project_client.agents.create_version(
    agent_name = agent_name,
    definition = PromptAgentDefinition(
        model = agent_model,
        instructions = instructions,
        tools = [mcp_kb_tool]
    )
)

print(f"Agent '{agent_name}' created or updated successfully.")

リモート SharePoint ナレッジ ソースに接続する

必要に応じて、ナレッジ ベースに リモート SharePoint ナレッジ ソースが含まれている場合は、MCP ツール接続に x-ms-query-source-authorization ヘッダーも含める必要があります。

from azure.identity import get_bearer_token_provider

# Create MCP tool with SharePoint authorization header
mcp_kb_tool = MCPTool(
    server_label = "knowledge-base",
    server_url = mcp_endpoint,
    require_approval = "never",
    allowed_tools = ["knowledge_base_retrieve"],
    project_connection_id = project_connection_name,
    headers = {
        "x-ms-query-source-authorization": get_bearer_token_provider(credential, "https://search.azure.com/.default")()
    }
)

クエリを使用してエージェントを呼び出す

会話セッションを作成し、エージェントにユーザー クエリを送信します。 必要に応じて、エージェントは MCP ツールの呼び出しを調整して、ナレッジ ベースから関連するコンテンツを取得します。 次に、エージェントはこのコンテンツを、ソース ドキュメントを引用する自然言語の応答に合成します。

# Get the OpenAI client for responses and conversations
openai_client = project_client.get_openai_client()

# Create conversation
conversation = openai_client.conversations.create()

# Send request to trigger the MCP tool
response = openai_client.responses.create(
    conversation = conversation.id,
    input = """
        Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
        Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
    """,
    extra_body = {"agent": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

出力は次のようになります。

Response: Suburban belts display larger December brightening than urban cores, even though absolute light levels are higher downtown, primarily because holiday lights increase most dramatically in the suburbs and outskirts of major cities. This is due to more yard space and a prevalence of single-family homes in suburban areas, which results in greater use of decorative holiday lighting. By contrast, central urban areas experience a smaller increase in lighting during the holidays, typically 20 to 30 percent brightening, because of their different building structures and possibly less outdoor space for such decorations. This pattern holds true across the United States as part of the nationally shared tradition of increased holiday lighting in December (Sources: earth_at_night_508_page_174, earth_at_night_508_page_176, earth_at_night_508_page_175).

The Phoenix nighttime street grid is sharply visible from space due to the city's layout along a regular grid of city blocks and streets with extensive street lighting. The major street grid is oriented mostly north-south, with notable diagonal thoroughfares like Grand Avenue that are also brightly lit. The illuminated grid reflects the widespread suburban and residential development fueled by automobile use in the 20th century, which led to optimal access routes to new real estate on the city's borders. Large shopping centers, strip malls, gas stations, and other commercial properties at major intersections also contribute to the brightness. Additionally, parts of the Phoenix metropolitan area remain dark where there are parks, recreational land, and agricultural fields, providing contrast that highlights the lit urban grid (Sources: earth_at_night_508_page_104, earth_at_night_508_page_105).

In contrast, large stretches of the interstate between Midwestern cities remain comparatively dim because although the transportation corridors are well-established, many rural and agricultural areas lack widespread nighttime lighting. The interstate highways are visible but do not have the same continuous bright lighting found in the dense urban grids and commercial suburban zones. The transportation network is extensive, but many roadways running through less populated regions have limited illumination, which renders them less visible in nighttime satellite imagery (Sources: earth_at_night_508_page_124, earth_at_night_508_page_125).

References:
- earth_at_night_508_page_174, earth_at_night_508_page_176, earth_at_night_508_page_175 (Holiday lighting and suburban December brightening)
- earth_at_night_508_page_104, earth_at_night_508_page_105 (Phoenix urban grid visibility)
- earth_at_night_508_page_124, earth_at_night_508_page_125 (Interstate lighting and Midwestern dim stretches)

エージェントとプロジェクトの接続を削除する

# Delete the agent
project_client.agents.delete_version(agent.name, agent.version)
print(f"Agent '{agent.name}' version '{agent.version}' deleted successfully.")

# Delete the project connection
mgmt_client.project_connections.delete(
    resource_group_name = resource_group,
    account_name = account_name,
    project_name = project_name,
    connection_name = project_connection_name
)
print(f"Project connection '{project_connection_name}' deleted successfully.")

注

エージェントとプロジェクト接続を削除しても、ナレッジ ベースまたはそのナレッジ ソースは削除されません。 これらのオブジェクトは、Azure AI Search サービスで個別に削除する必要があります。 詳細については、「 ナレッジ ベースの削除 」および「 ナレッジ ソースの削除」を参照してください。

関連コンテンツ

  • Last updated on