Ansluta en Foundry IQ-kunskapsbas till Foundry Agent Service

Observera

Vissa funktioner för agentisk hämtning är allmänt tillgängliga i REST-API:et 2026-04-01. Den här artikeln använder dock förhandsversionen 2026-08-01 för att demonstrera den fullständiga funktionsuppsättningen, inklusive funktioner som finns kvar i förhandsversionen. Förhandsversionsfunktioner tillhandahålls utan serviceavtal och rekommenderas inte för produktionsarbetsbelastningar. Mer information finns i Supplemental Terms of Use for Microsoft Azure Previews.

Viktigt

Dessa funktioner och denna funktionalitet är en del av REST API-versionen 2026-08-01-preview. Förhandsversionen av 2026-08-01 är licensierad till dig som en del av din Azure-prenumeration och omfattas av de villkor som gäller för "förhandsversioner" i Microsoft Produktvillkor, Microsoft Products and Services Data Protection Addendum ("DPA") och tilläggsvillkoren för användning för Microsoft Azure förhandsversioner.

Förhandsversionen av 2026-08-01 stöder anslutningar till andra Microsoft-tjänster- och tredjepartstjänster. Användningen av dessa tjänster omfattas av deras respektive villkor och kan resultera i databearbetning eller lagring utanför Azure efterlevnadsgräns, samt data som flödar till Azure efterlevnadsgräns.

Det är ditt ansvar att hantera om dina data kommer att flöda utanför organisationens efterlevnad och geografiska gränser och eventuella relaterade konsekvenser, och att lämpliga behörigheter, gränser och godkännanden etableras.

MCP-implementeringar är mottagliga för risker, till exempel attacker, sammanhängande fel och förlust av mänsklig tillsyn. Du kan minska dessa risker genom att granska MCP-servrar för säkerhet och tillförlitlighet, enligt bästa praxis för Microsoft och industry och implementera godkännandemekanismer och övervakning av sammanhängande beteenden.

Du ansvarar för att noggrant granska och testa program som du skapar i samband med dina specifika användningsfall och fatta alla lämpliga beslut och anpassningar. Detta omfattar implementering av dina egna ansvarsfulla AI-åtgärder, till exempel metaprompter, innehållsfilter eller andra säkerhetssystem, och att se till att dina program uppfyller lämpliga kvalitets-, tillförlitlighets-, säkerhets- och tillförlitlighetsstandarder. Mer information finns i Azure AI-sökning Transparency Note.

I den här artikeln får du lära dig hur du ansluter en kunskapsbas i Foundry IQ till en agent i Foundry Agent Service. Anslutningen använder MCP (Model Context Protocol) för att underlätta verktygsanrop. När agenten anropar orkestrerar kunskapsbasen följande åtgärder:

  • Planerar och delar upp en användarfråga i underfrågor.
  • Bearbetar underfrågorna samtidigt med hjälp av nyckelords-, vektor- eller hybridtekniker.
  • Tillämpar semantisk reranking för att identifiera de mest relevanta resultaten.
  • Syntetiserar resultatet till ett enhetligt svar med källreferenser.

Agenten använder svaret för att grunda sina svar i företagsdata eller webbkällor, vilket säkerställer faktisk noggrannhet och transparens genom källtillskrivning.

För ett heltäckande exempel på integrering av Azure AI-sökning och Foundry Agent Service för att hämta kunskap, se Python-exemplet agentic-retrieval-pipeline-example på GitHub.

Användningsstöd

stöd för Microsoft Foundry Python SDK C#-SDK SDK för JavaScript Java SDK REST API Grundläggande agentkonfiguration Standardagentkonfiguration
✔️ ✔️ - - - ✔️ ✔️ ✔️

Förutsättningar

Autentisering och behörigheter

Vi rekommenderar rollbaserad åtkomstkontroll för produktionsdistributioner. Om du vill tilldela rollerna i det här avsnittet behöver du rollen Ägare eller Administratör för användaråtkomst för båda resurserna eller en annan roll som ger Microsoft.Authorization/roleAssignments/write. Om roller inte är möjliga hoppar du över det här avsnittet och använder nyckelbaserad autentisering i stället.

  • På den överordnade resursen i projektet behöver du rollen Foundry-användare för att få åtkomst till modelldistributioner och skapa agenter. Ägare får automatiskt den här rollen när de skapar resursen. Andra användare behöver en specifik rolltilldelning. Mer information finns i Rollbaserad åtkomstkontroll i Foundry-portalen.

    Viktigt

    Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

  • På den överordnade resursen för ditt projekt behöver du rollen Foundry Project Manager för att skapa en projektanslutning för MCP-autentisering och antingen Foundry User eller Foundry Project Manager för att använda MCP-verktyget i agenter.

  • (Villkorligt) På den överordnade resursen för ditt projekt tilldelar du rollen Cognitive Services User till din söktjänsts systemtilldelade hanterade identitet. Det här steget krävs endast om kunskapsbasen anger en LLM. Beroende på konfigurationen använder kunskapsbasen den här identiteten för att anropa LLM för frågeplanering, svarssyntes eller både och. Mer information finns i Ansluta till Azure AI-sökning med hjälp av en hanterad identitet.

  • I projektet skapar du en systemtilldelad hanterad identitet för interaktioner med Azure AI-sökning.

Obligatoriska värden

Använd följande värden i kodexemplen.

Värde Var du kan hämta den Exempel
Projekt slutpunkt (project_endpoint) Hitta den i projektinformationen i Microsoft Foundry-portalen. https://your-resource.services.ai.azure.com/api/projects/your-project
Project resurs-ID (project_resource_id) Kopiera projektets ARM-resurs-ID från Azure portalen eller använd Azure CLI för att köra frågor mot resurs-ID:t. Ditt Microsoft Foundry-projekt måste ha Microsoft.CognitiveServices/accounts namnområdet. /subscriptions/.../resourceGroups/.../providers/Microsoft.CognitiveServices/accounts/.../projects/...
Azure AI-sökning endpunkt (search_service_endpoint) Hitta den på sidan Azure AI-sökning tjänst Overview (tjänstens URL) i Azure-portalen. https://your-search-service.search.windows.net
Kunskapsbasnamn (knowledge_base_name) Använd kunskapsbasnamnet som du skapade i Azure AI-sökning. hr-policy-kb
Projektanslutningsnamn (project_connection_name) Välj ett namn för den projektanslutning som du skapar. my-kb-mcp-connection
Agentnamn (agent_name) Välj ett namn för den agentversion som du skapar. hr-assistant
Namn på modellimplementering (deployed_LLM) Hitta den i distributioner av Microsoft Foundry-projektmodell. gpt-4.1-mini

Tips

Vi rekommenderar att du lagrar projektets slutpunkt, sökslutpunkt och kunskapsbasnamn i en .env fil för lokal utveckling.

Skapa en projektanslutning

Skapa en RemoteTool-anslutning i ditt Microsoft Foundry-projekt. Den här anslutningen använder projektets hanterade identitet för att rikta in sig på MCP-slutpunkten för kunskapsbasen, så att agenten kan kommunicera säkert med Azure AI-sökning för hämtningsåtgärder.

Observera

Kategorin RemoteTool och ProjectManagedIdentity autentiseringstyp är specifika för Microsoft Foundry-projektanslutningar.

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.CognitiveServices/accounts/{account_name}/projects/{project_name}
project_connection_name = "{project_connection_name}"
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-08-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.")

Optimera agentinstruktioner för kunskapshämtning

Om du vill förbättra kunskapsbasanrop och skapa källhänvisningsbaserade svar börjar du med instruktioner som följande:

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.

Den här instruktionsmallen optimerar för:

  • Högre anropsfrekvens för MCP-verktyg: Explicita direktiv säkerställer att agenten konsekvent anropar kunskapsbasverktyget i stället för att förlita sig på sina träningsdata.
  • Tydlig käll-attribution: Citat gör det enklare att verifiera var informationen kommer ifrån.

Tips

Den här mallen ger en stark grund, men utvärderar och itererar instruktionerna baserat på ditt specifika användningsfall och mål. Testa olika varianter för att hitta det som fungerar bäst för ditt scenario.

Skapa en agent med MCP-verktyget

Skapa en agent som integrerar kunskapsbasen som ett MCP-verktyg. Agenten använder en systemprompt för att instruera när och hur kunskapsbasen ska anropas. Den följer instruktioner om hur du besvarar frågor och automatiskt underhåller dess verktygskonfiguration och inställningar mellan konversationssessioner.

Lägg till mcp-verktyget för kunskapsbasen med projektanslutningen som du skapade tidigare. Det här verktyget samordnar frågeplanering, nedbrytning och hämtning mellan konfigurerade kunskapskällor. Agenten använder det här verktyget för att besvara frågor.

Observera

Azure AI-sökning kunskapsbaser exponerar mcp-verktyget knowledge_base_retrieve för agentintegrering. Det här är det enda verktyg som för närvarande stöds för användning med 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=2026-08-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.")

Skapa agenten med .NET SDK

Installera förhandsversionspaketen med dotnet add package Azure.AI.Projects --prerelease och dotnet add package Azure.Identity.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var mcpEndpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-05-01-preview";
var projectEndpoint = "{project_endpoint}"; // e.g. https://your-foundry-resource.services.ai.azure.com/api/projects/your-foundry-project
var projectConnectionName = "{project_connection_name}";
var agentName = "{agent_name}";
var agentModel = "gpt-4.1-mini";

AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

// Define agent instructions (see "Optimize agent instructions" section for guidance).
var 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 an MCP tool that points at the knowledge base connection.
McpTool mcpKbTool = ResponseTool.CreateMcpTool(
    serverLabel: "knowledge-base",
    serverUri: new Uri(mcpEndpoint),
    allowedTools: new McpToolFilter { ToolNames = { "knowledge_base_retrieve" } },
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
mcpKbTool.ProjectConnectionId = projectConnectionName;

// Create the agent with the MCP tool.
DeclarativeAgentDefinition definition = new(model: agentModel)
{
    Instructions = instructions,
    Tools = { mcpKbTool },
};
ProjectsAgentVersion agent = agentsClient.CreateAgentVersion(
    agentName: agentName,
    options: new ProjectsAgentVersionCreationOptions(definition));
Console.WriteLine($"Agent '{agentName}' created or updated successfully.");

(Valfritt) Framtvinga behörigheter med sidhuvuden per begäran

Om någon av dina kunskapskällor innehåller behörighetsskyddat innehåll kan hämtningsmotorn filtrera resultat så att varje användare bara ser de dokument som de har behörighet att komma åt. Om du vill aktivera den här filtreringen vidarebefordrar du den inloggade användarens identitetstoken i x-ms-query-source-authorization huvudet på MCP-verktygsanslutningen. Utan token returnerar behörighetsaktiverade källor resultat som inte har filtrerats. Mer information finns i Framtvinga behörigheter vid frågetid (förhandsversion).

Om du vill variera MCP-huvuden per begäran, till exempel skicka en annan användares token vid varje anrop, deklarerar du en strukturerad indata i agentdefinitionen och refererar till den som en {{placeholder}} i verktygets headers. Anroparen tillhandahåller värdet för varje anrop. Den här metoden fungerar för MCP-verktyg som är bundna till en projektanslutning.

För auktorisering per användare mot en MCP-server kan du också använda OAuth-identitetsgenomströmning.

Uppdatera agenten från föregående steg så att MCP-verktyget läser dess auktoriseringshuvud från en strukturerad indata:

from azure.ai.projects.models import StructuredInputDefinition

# Reference the token as a placeholder in the 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": "{{search_auth_token}}"
    }
)

# Declare the structured input so the caller can supply the token per request
agent = project_client.agents.create_version(
    agent_name = agent_name,
    definition = PromptAgentDefinition(
        model = agent_model,
        instructions = instructions,
        tools = [mcp_kb_tool],
        structured_inputs = {
            "search_auth_token": StructuredInputDefinition(
                description = "Per-user Azure AI Search bearer token",
                required = True,
                schema = {"type": "string"},
            )
        }
    )
)

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

När du anropar agenten anger du en Azure AI-sökning token i structured_inputs. Det här exemplet löser en token från den aktuella credential. För en app för flera användare skickar du token för varje inloggad användare i stället. Använd till exempel en åtkomsttoken som erhållits via ett on-behalf-of-flöde så att hämtningsmotorn kan filtrera resultaten för den användaren.

# Resolve an Azure AI Search token from the current credential (use a per-user token in production)
from azure.identity import get_bearer_token_provider

search_token = get_bearer_token_provider(credential, "https://search.azure.com/.default")()

openai_client = project_client.get_openai_client()
conversation = openai_client.conversations.create()

response = openai_client.responses.create(
    conversation = conversation.id,
    input = "{user_query}",
    extra_body = {
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"search_auth_token": search_token},
    },
)

Anropa agenten med en fråga

Skapa en konversationssession och skicka en användarfråga till agenten. När det är lämpligt dirigerar agenten anrop till MCP-verktyget för att hämta relevant innehåll från kunskapsbasen. Agenten syntetiserar sedan det här innehållet till ett naturligt språksvar som citerar källdokumenten.

URL:er för källhänvisning i agentsvar varierar beroende på kunskapskälla. Blob-kunskapskällor returnerar till exempel den ursprungliga dokument-URL:en, medan kunskapskällorna för sökindex återgår till MCP-slutpunkten för din kunskapsbas.

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

Utdata bör likna följande (avkortat för korthet):

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)

Ta bort agenten och projektanslutningen

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

Observera

Om du tar bort agenten och projektanslutningen tas inte kunskapsbasen eller dess kunskapskällor bort. Du måste ta bort dessa objekt separat på din Azure AI-sökning-tjänst. Mer information finns i Ta bort en kunskapsbas och Ta bort en kunskapskälla.

Felsökning

Det här avsnittet hjälper dig att felsöka vanliga problem när du ansluter Foundry Agent Service till en Foundry IQ-kunskapsbas.

Auktoriseringsfel (401/403)

  • Om du får en 403 från Azure AI-sökning kontrollerar du att projektets hanterade identitet har en Search Index Data Reader roll på söktjänsten (och en Search Index Data Contributor om du skriver till index).
  • Om du får en 403 från Azure Resource Manager när du skapar eller tar bort projektanslutningen kontrollerar du att användaren eller tjänstens huvudnamn har behörighet för Microsoft Foundry-resursen och projektet.
  • Om du använder nyckellös autentisering, kontrollera att din miljö är ansluten till rätt klientorganisation och prenumeration.

MCP-slutpunktsfel (400/404)

  • Bekräfta search_service_endpoint är url:en för Azure AI-sökning-tjänsten, till exempel https://<name>.search.windows.net.
  • Bekräfta att knowledge_base_name överensstämmer med den kunskapsbas som du skapade i Azure AI-sökning.
  • Bekräfta att du använder API-versionen 2026-08-01-preview för MCP-slutpunkten för kunskapsbasen.

Agenten underbygger inte svar

  • Bekräfta att agenten har MCP-verktyget konfigurerat och allowed_tools innehåller knowledge_base_retrieve.
  • Uppdatera agentinstruktionerna för att uttryckligen kräva att kunskapsbasen används och att returnera "Jag vet inte" när hämtningen inte innehåller svaret.

Relaterat innehåll

  • Last updated on