Łączenie bazy wiedzy Foundry IQ z usługą agenta Foundry

Ważne

Elementy oznaczone (wersja zapoznawcza) w tym artykule są obecnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.

W tym artykule dowiesz się, jak połączyć bazę wiedzy w Foundry IQ do agenta w Foundry Agent Service. Połączenie używa protokołu MCP (Model Context Protocol), aby ułatwić wywołania narzędzi. Po wywołaniu przez agenta baza wiedzy organizuje następujące operacje:

  • Planuje i rozkłada zapytanie użytkownika na podzapytania.
  • Przetwarza podzapytania jednocześnie przy użyciu słów kluczowych, wektorów lub technik hybrydowych.
  • Stosuje semantyczne rerankingowanie w celu zidentyfikowania najbardziej istotnych wyników.
  • Syntetyzuje wyniki w ujednoliconą odpowiedź z odwołaniami źródłowymi.

Agent używa odpowiedzi, aby oprzeć je w danych przedsiębiorstwa lub źródłach internetowych, zapewniając zgodność z faktami i przejrzystość poprzez podanie źródła.

Aby zapoznać się z kompleksowym przykładem integrowania usługi Wyszukiwanie AI platformy Azure i usługi Foundry Agent do wyszukiwania wiedzy, zobacz przykład agentic-retrieval-pipeline-example Python na GitHubie.

Wsparcie użytkowania

Obsługa Microsoft Foundry zestaw SDK Python C# SDK JavaScript SDK zestaw SDK Java interfejs API REST Konfiguracja agenta podstawowego Konfiguracja agenta standardowego
✔️ ✔️ - - - ✔️ ✔️ ✔️

Wymagania wstępne

Uwierzytelnianie i uprawnienia

Zalecamy kontrolę dostępu opartą na rolach dla wdrożeń produkcyjnych. Jeśli role nie są wykonalne, pomiń tę sekcję i zamiast tego użyj uwierzytelniania opartego na kluczach.

  • W zasobie nadrzędnym projektu potrzebna jest rola Azure AI User, aby uzyskać dostęp do wdrożeń modelu i tworzyć agentów. Właściciele automatycznie uzyskują tę rolę podczas tworzenia zasobu. Inni użytkownicy potrzebują określonego przypisania roli. Aby uzyskać więcej informacji, zobacz Kontrola dostępu oparta na rolach w portalu Foundry.

  • Na zasobie nadrzędnym swojego projektu potrzebujesz roli Azure AI Project Manager, aby utworzyć połączenie projektu na potrzeby uwierzytelniania MCP, oraz roli Azure AI User lub Azure AI Project Manager, aby używać narzędzia MCP w agentach.

  • W projekcie utwórz tożsamość zarządzaną przypisaną przez system na potrzeby interakcji z Wyszukiwanie AI platformy Azure.

Wymagane wartości

Użyj poniższych wartości w przykładach kodu.

Wartość Gdzie to zrobić Przykład
punkt końcowy Projektu (project_endpoint) Znajdź go w szczegółach projektu w portalu Microsoft Foundry. https://your-resource.services.ai.azure.com/api/projects/your-project
identyfikator zasobu Project (project_resource_id) Skopiuj identyfikator zasobu usługi ARM projektu z portalu Azure lub użyj Azure CLI, aby wysłać zapytanie do identyfikatora zasobu. /subscriptions/.../resourceGroups/.../providers/Microsoft.MachineLearningServices/workspaces/.../projects/...
punkt końcowy Wyszukiwanie AI platformy Azure (search_service_endpoint) Znajdź ją na stronie usługi Wyszukiwanie AI platformy Azure Overview (adres URL usługi) w portalu Azure. https://your-search-service.search.windows.net
Nazwa bazy wiedzy (knowledge_base_name) Użyj nazwy bazy wiedzy utworzonej w Wyszukiwanie AI platformy Azure. hr-policy-kb
Nazwa połączenia projektu (project_connection_name) Wybierz nazwę utworzonego połączenia projektu. my-kb-mcp-connection
Nazwa agenta (agent_name) Wybierz nazwę utworzonej wersji agenta. hr-assistant
Nazwa wdrożenia modelu (deployed_LLM) Znajdź go we wdrożeniach modelu projektu Microsoft Foundry. gpt-4.1-mini

Wskazówka

Zalecamy przechowywanie punktu końcowego projektu, punktu końcowego wyszukiwania i nazwy bazy wiedzy w pliku na potrzeby programowania lokalnego .env .

Utwórz połączenie projektu

Utwórz połączenie RemoteTool w projekcie Microsoft Foundry. To połączenie używa tożsamości zarządzanej projektu do określania docelowego punktu końcowego MCP bazy wiedzy, dzięki czemu agent może bezpiecznie komunikować się z Wyszukiwanie AI platformy Azure na potrzeby operacji pobierania.

Uwaga

Kategoria RemoteTool i typ uwierzytelniania ProjectManagedIdentity są specyficzne dla połączeń projektu Microsoft Foundry.

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

Optymalizowanie instrukcji agenta na potrzeby pobierania wiedzy

Aby poprawić wywołania bazy wiedzy i utworzyć odpowiedzi oparte na cytatach, zacznij od instrukcji, takich jak:

You are a helpful assistant.

Use the knowledge base tool to answer user questions.
If the knowledge base doesn't contain the answer, respond with "I don't know".

When you use information from the knowledge base, include citations to the retrieved sources.

Ten szablon instrukcji jest zoptymalizowany pod kątem:

  • Wyższe wskaźniki wywołań narzędzi MCP: Dyrektywy jawne zapewniają, że agent konsekwentnie wywołuje narzędzie bazy wiedzy, a nie polega na danych treningowych.
  • Wyczyść przypisanie źródła: cytaty ułatwiają weryfikowanie miejsca, z którego pochodzą informacje.

Wskazówka

Chociaż ten szablon stanowi silną podstawę, oceń i iteruj instrukcje na podstawie konkretnego przypadku użycia i celów. Przetestuj różne odmiany, aby dowiedzieć się, co jest najlepsze dla danego scenariusza.

Tworzenie agenta za pomocą narzędzia MCP

Utwórz agenta, który integruje bazę wiedzy jako narzędzie MCP. Agent używa monitu systemowego, aby poinstruować, kiedy i jak wywołać bazę wiedzy. Postępuje zgodnie z instrukcjami dotyczącymi odpowiadania na pytania i automatycznego utrzymywania konfiguracji i ustawień narzędzi między sesjami konwersacji.

Dodaj narzędzie MCP z bazy wiedzy za pomocą połączenia projektu, które utworzyłeś wcześniej. To narzędzie organizuje planowanie zapytań, dekompozycję i pobieranie w skonfigurowanych źródłach wiedzy. Agent używa tego narzędzia do odpowiadania na zapytania.

Uwaga

Wyszukiwanie AI platformy Azure bazy wiedzy uwidaczniają narzędzie knowledge_base_retrieve MCP na potrzeby integracji agenta. Jest to jedyne narzędzie, które jest obecnie obsługiwane do współpracy z 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.")

Nawiązywanie połączenia ze zdalnym źródłem wiedzy SharePoint

Ważne

W tej wersji zapoznawczej usługa Foundry Agent Service nie obsługuje nagłówków przypisanych do poszczególnych żądań dla narzędzi MCP. Nagłówki ustawione w definicjach agenta mają zastosowanie do wszystkich wywołań i nie mogą się różnić w zależności od użytkownika ani żądania.

W przypadku autoryzacji dla poszczególnych użytkowników użyj zamiast tego interfejsu API Azure OpenAI Responses API.

Opcjonalnie, jeśli twoja baza wiedzy zawiera zdalne źródło wiedzy SharePoint, należy również dołączyć nagłówek x-ms-query-source-authorization w połączeniu narzędzia MCP. Aby uzyskać więcej informacji, zobacz Wymuszanie uprawnień w czasie wykonywania zapytania.

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

Wywoływanie agenta za pomocą zapytania

Utwórz sesję konwersacji i wyślij zapytanie użytkownika do agenta. W razie potrzeby agent organizuje wywołania narzędzia MCP w celu pobrania odpowiedniej zawartości z bazy wiedzy. Następnie agent syntetyzuje tę zawartość w odpowiedzi języka naturalnego, która przytacza dokumenty źródłowe.

Adresy URL cytatów w odpowiedziach agenta różnią się w zależności od źródła wiedzy. Na przykład źródła wiedzy obiektów blob zwracają oryginalny adres URL dokumentu, podczas gdy źródła wiedzy indeksu wyszukiwania wracają do punktu końcowego MCP bazy wiedzy.

# 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_reference": {"name": agent.name, "type": "agent_reference"}},
)

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

Dane wyjściowe powinny być podobne do następujących (obcięte w celu zwięzłości):

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

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

References:
- earth_at_night_508_page_174, earth_at_night_508_page_176 (Holiday lighting)
- earth_at_night_508_page_104, earth_at_night_508_page_105 (Phoenix grid visibility)

Usuń agenta i połączenie projektu

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

# Delete the project connection (Azure Resource Manager)
import requests
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

credential = DefaultAzureCredential()
project_resource_id = "{project_resource_id}"
project_connection_name = "{project_connection_name}"

bearer_token_provider = get_bearer_token_provider(credential, "https://management.azure.com/.default")
headers = {"Authorization": f"Bearer {bearer_token_provider()}"}

response = requests.delete(
  f"https://management.azure.com{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview",
  headers=headers,
)
response.raise_for_status()
print(f"Project connection '{project_connection_name}' deleted successfully.")

Uwaga

Usunięcie agenta i połączenia projektu nie powoduje usunięcia bazy wiedzy ani jej źródeł wiedzy. Te obiekty należy usunąć oddzielnie w usłudze Wyszukiwanie AI platformy Azure. Aby uzyskać więcej informacji, zobacz Usuwanie bazy wiedzy i Usuwanie źródła wiedzy.

Rozwiązywanie problemów

Ta sekcja ułatwia rozwiązywanie typowych problemów podczas łączenia usługi agenta Foundry z bazą wiedzy Foundry IQ.

Błędy autoryzacji (401/403)

  • Jeśli otrzymasz kod błędu 403 z Wyszukiwanie AI platformy Azure, upewnij się, że zarządzana tożsamość projektu ma przypisaną rolę Search Index Data Reader w usłudze wyszukiwania (oraz Search Index Data Contributor jeśli zapisujesz do indeksów).
  • Jeśli otrzymasz wartość 403 z Azure Resource Manager podczas tworzenia lub usuwania połączenia projektu, upewnij się, że użytkownik lub jednostka usługi ma uprawnienia do zasobu i projektu Microsoft Foundry.
  • Jeśli używasz uwierzytelniania bez klucza, upewnij się, że środowisko jest połączone z odpowiednią dzierżawą i subskrypcją.

Błędy punktu końcowego MCP (400/404)

  • Upewnij się, że search_service_endpoint jest adresem URL usługi Wyszukiwanie AI platformy Azure, takim jak https://<name>.search.windows.net.
  • Upewnij się, że knowledge_base_name pasuje do bazy wiedzy utworzonej w Wyszukiwanie AI platformy Azure.
  • Upewnij się, że używasz wersji interfejsu API 2025-11-01-preview dla punktu końcowego bazy wiedzy MCP.

Agent nie opiera odpowiedzi

  • Upewnij się, że agent ma skonfigurowane narzędzie MCP i allowed_tools zawiera knowledge_base_retrieve element.
  • Zaktualizuj instrukcje agenta, aby jawnie wymagać użycia bazy wiedzy i zwrócić "Nie wiem", gdy pobieranie nie zawiera odpowiedzi.

Powiązana zawartość

  • Last updated on