Freigeben über

Verbinden einer Foundry IQ Knowledge Base mit dem Foundry Agent Service

Von Bedeutung

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

In diesem Artikel erfahren Sie, wie Sie einen Agent in Microsoft Foundry mit einer Wissensbasis in Foundry IQ verbinden, einer agentischen Abrufauslastung, die von Azure AI Search unterstützt wird. Die Verbindung verwendet das Model Context Protocol (MCP), um Toolaufrufe zu erleichtern. Wenn der Agent aufgerufen wird, koordiniert die Knowledge Base die folgenden Vorgänge:

  • Plant und zerlegt eine Benutzerabfrage in Unterabfragen.
  • Verarbeitet die Unterabfragen gleichzeitig mithilfe von Schlüsselwort-, Vektor- oder Hybridtechniken.
  • Wendet die semantische Umrankung an, um die relevantesten Ergebnisse zu identifizieren.
  • Synthetisiert die Ergebnisse in eine einheitliche Antwort mit Quellverweise.

Der Agent verwendet die Antwort, um seine Antworten in Unternehmensdaten oder Webquellen zu finden, um durch die Quellenzuordnung faktenbezogene Genauigkeit und Transparenz sicherzustellen.

Ein End-to-End-Beispiel für die Integration von Azure AI Search und Foundry Agent Service zum Abrufen von Wissen finden Sie im Beispiel für agentic-retrieval-pipeline-example Python auf GitHub.

Nutzungssupport

Microsoft Foundry-Support Python SDK C# SDK JavaScript SDK Java-SDK REST API Basic-Agent-Setup Standard-Agent-Setup
✔️ ✔️ - - - ✔️ ✔️ ✔️

Voraussetzungen

Authentifizierung und Berechtigungen

Wir empfehlen rollenbasierte Zugriffskontrolle für Produktionsumgebungen. Wenn Rollen nicht machbar sind, überspringen Sie diesen Abschnitt, und verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

  • Auf der übergeordneten Ressource Ihres Projekts benötigen Sie die Azure AI-Benutzerrolle , um auf Modellbereitstellungen zuzugreifen und Agents zu erstellen. Besitzer erhalten diese Rolle automatisch, wenn sie die Ressource erstellen. Andere Benutzer benötigen eine bestimmte Rollenzuweisung. Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung im Foundry-Portal.
  • In der übergeordneten Ressource Ihres Projekts benötigen Sie die Azure AI-Projektmanagerrolle , um eine Projektverbindung für die MCP-Authentifizierung zu erstellen, und entweder Azure AI-Benutzer oder Azure AI-Projektmanager , um das MCP-Tool in Agents zu verwenden.
  • Erstellen Sie in Ihrem Projekt eine vom System zugewiesene verwaltete Identität für Interaktionen mit Azure AI Search.

Verstehen von Foundry IQ

Foundry IQ trennt Anliegen zwischen Domänenwissen und Agentenlogik, was die abrufgestützte Generierung (retrieval-augmented generation, RAG) und Grounding im großen Stil ermöglicht. Anstatt die Komplexität des Abrufs in jeden Agenten zu bündeln, erstellen Sie eine Wissensbasis, die eine vollständige Wissensdomäne darstellt, z. B. Personal oder Vertrieb. Ihre Agenten rufen dann die Wissensbasis auf, um ihre Antworten auf relevante, aktuelle Informationen zu stützen.

Diese Trennung hat zwei wichtige Vorteile:

  • Sie können eine Wissensbasis unabhängig aktualisieren, ohne Agents zu ändern.
  • Mehrere Agents können dieselbe Wissensbasis gemeinsam nutzen und doppelte Konfigurationen vermeiden.

Funktionsweise von Foundry IQ

Unterstützt von Azure AI Search besteht Foundry IQ aus Wissensquellen (was abgerufen werden soll) und Wissensbasen (wie abgerufen werden soll). Die Wissensdatenbank plant und führt Unterabfragen aus und gibt formatierte Ergebnisse mit Zitaten aus.

Obwohl Wissensdatenbanken die Antwortsynthese unterstützen, empfehlen wir den extraktiven Datenausgabemodus für die Integration in foundry Agent Service. Dieser Modus stellt sicher, dass der Agent verbatim Inhalte empfängt, anstatt vorab generierte Antworten zu erhalten und die volle Kontrolle über das Antwortformat und die Qualität zu bieten.

Wie der Foundry Agent Service Wissensdatenbanken verwendet

Der Foundry Agent Service koordiniert Aufrufe an die Wissensbasis über das MCP-Tool und synthetisiert die endgültige Antwort. Zur Laufzeit ruft der Agent nur die Knowledge Base auf, nicht die Datenplattform (z. B. Azure Blob Storage oder Microsoft OneLake), die der Wissensquelle zugrunde unterliegt. Die Wissensdatenbank verarbeitet alle Abrufvorgänge.

Erstellen einer Projektverbindung

Erstellen Sie eine RemoteTool Verbindung mit Ihrem Microsoft Foundry-Projekt. Diese Verbindung verwendet die verwaltete Identität des Projekts, um den MCP-Endpunkt der Knowledge Base als Ziel zu verwenden, sodass der Agent sicher mit Azure AI Search für Abrufvorgänge kommunizieren kann.

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.")

Optimieren von Agent-Anweisungen für den Wissensabruf

Verwenden Sie optimierte Agent-Anweisungen, um die Genauigkeit von Wissensbasisaufrufen zu maximieren und eine korrekte Zitatformatierung sicherzustellen. Basierend auf unseren Experimenten empfehlen wir die folgende Anweisungsvorlage als Ausgangspunkt:

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".

Diese Anweisungsvorlage ist optimiert für:

  • Höhere MCP-Toolaufrufraten: Explizite Direktiven stellen sicher, dass der Agent das Knowledge Base-Tool konsistent aufruft, anstatt sich auf seine Schulungsdaten zu verlassen.
  • Richtige Anmerkungsformatierung: Das angegebene Zitatformat stellt sicher, dass der Agent Provenienzinformationen in Antworten enthält, wodurch klar wird, welche Wissensquellen verwendet wurden.

Tipp

Während diese Vorlage eine starke Grundlage bietet, bewerten und verfeinern Sie die Anweisungen basierend auf Ihrem spezifischen Anwendungsfall und Ihren Zielen. Testen Sie verschiedene Variationen, um zu ermitteln, was für Ihr Szenario am besten geeignet ist.

Erstellen eines Agents mit dem MCP-Tool

Erstellen Sie einen Agent, der die Wissensbasis als MCP-Tool integriert. Der Agent verwendet eine Systemaufforderung, um anzugeben, wann und wie die Wissensbasis aufgerufen wird. Es folgt Anweisungen zum Beantworten von Fragen und verwaltet automatisch seine Toolkonfiguration und -einstellungen in Unterhaltungssitzungen.

Fügen Sie das Knowledge Base MCP-Tool mit der Projektverbindung hinzu, die Sie zuvor erstellt haben. Dieses Tool koordiniert die Abfrageplanung, -analyse und -abruf über konfigurierte Wissensquellen hinweg. Der Agent verwendet dieses Tool, um Abfragen zu beantworten.

Hinweis

Azure AI Search Knowledge-Basen stellen das MCP-Tool für die knowledge_base_retrieve Agentintegration zur Verfügung. Dies ist das einzige Tool, das derzeit für die Verwendung mit dem Foundry Agent Service unterstützt wird.

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.")

Herstellen einer Verbindung mit einer SharePoint-Remote-Wissensquelle

Wenn Ihre Knowledge Base optional eine SharePoint-Remote-Wissensquelle enthält, müssen Sie auch den x-ms-query-source-authorization Header in die MCP-Toolverbindung einschließen.

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")()
    }
)

Aufrufen des Agents mit einer Abfrage

Erstellen Sie eine Unterhaltungssitzung, und senden Sie eine Benutzerabfrage an den Agent. Der Agent koordiniert gegebenenfalls Anrufe an das MCP-Tool, um relevante Inhalte aus der Wissensdatenbank abzurufen. Der Agent synthetisiert diesen Inhalt dann in einer natürlichen Sprachantwort, die die Quelldokumente angibt.

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

Die Ausgabe sollte ähnlich der Folgenden aussehen:

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)

Löschen des Agents und der Projektverbindung

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

Hinweis

Wenn Sie Ihren Agent und Ihre Projektverbindung löschen, werden Ihre Wissensbasis oder ihre Wissensquellen nicht gelöscht. Sie müssen diese Objekte separat in Ihrem Azure AI Search-Dienst löschen. Weitere Informationen finden Sie unter "Löschen einer Wissensbasis " und "Löschen einer Wissensquelle".

Verwandte Inhalte

  • Last updated on