Konfigurieren von Knowledge Base-Tools

Important

Die Funktionalität der Tools der Wissensdatenbank befindet sich in der öffentlichen Vorschau und unterliegt den Ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.

Die für diese Funktion geltenden Vorschaubedingungen finden Sie unter Vorschaufunktionalität.

Mithilfe von Knowledge Base-Tools kann eine Wissensdatenbank mehrere aufgabenspezifische Abrufworkflows für Anwendungen und Agents unterstützen. Jedes Tool wählt Wissensquellen aus und legt wiederverwendbares Abrufverhalten fest, z. B. Denkaufwand und Ausgabegrenzwerte. Clients können ein Tool über REST aufrufen oder es über den MCP-Endpunkt ermitteln und aufrufen.

Verwenden Sie Knowledge Base-Tools, wenn Clients einen konsistenten Einstiegspunkt benötigen, ohne die gleichen Wissensquellen und Standardwerte für jede Anforderung neu zu erstellen. In diesem Artikel erstellen Sie ein Tool, testen, wie seine gespeicherten Einstellungen mit Steuerelementen zur Anforderungszeit interagieren, rufen es über MCP auf und aktualisieren oder entfernen es.

Nutzungssupport

Azure Portal Microsoft Foundry-Portal .NET SDK Python SDK Java SDK JavaScript SDK REST-API
❌ ❌ ✔️ ✔️ ✔️ ✔️ ✔️

Prerequisites

  • Berechtigung zum Erstellen und Abfragen der Beispielressourcen. Konfigurieren Sie die schlüssellose Authentifizierung mit den Rollen „Suchdienstmitwirkender“, „Indexdatenmitwirkender“ und „Indexdatenleser“, die Ihrem Benutzerkonto zugewiesen sind.
  • Die neueste Vorschauversion von azure-search-documents und das azure-identity-Paket. Siehe Python Clientbibliothek.
  • Ein Konsolenprojekt für .NET 8 oder höher mit der neuesten Vorschauversion von Azure.Search.Documents. Weitere Informationen finden Sie in der .NET Clientbibliothek.

Erstellen Sie eine Beispielwissensbasis

Erstellen Sie einen Index, eine Wissensquelle und eine Wissensbasis.

Melden Sie sich wie unter Connect to Foundry IQ (Azure KI-Suche) beschrieben an. Führen Sie die SDK-Codeausschnitte in der reihenfolge aus.

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient
from azure.search.documents.indexes import SearchIndexClient

search_endpoint = "<search-endpoint>"
index_name = "kb-tools-policy-index"
knowledge_source_name = "kb-tools-policy-source"
knowledge_base_name = "kb-tools-policy-kb"
credential = DefaultAzureCredential()
index_client = SearchIndexClient(search_endpoint, credential)
search_client = SearchClient(search_endpoint, index_name, credential)

Referenz:DefaultAzureCredential, SearchClient, SearchIndexClient.

Erstellen Sie den Index, und laden Sie drei synthetische Richtlinien hoch.

from azure.search.documents.indexes.models import (
    SearchFieldDataType,
    SearchIndex,
    SearchableField,
    SimpleField,
)

index = index_client.create_index(SearchIndex(
    name=index_name,
    fields=[
        SimpleField(
            name="id", type=SearchFieldDataType.STRING, key=True,
        ),
        SearchableField(name="title"),
        SearchableField(name="content"),
        SimpleField(
            name="jurisdiction",
            type=SearchFieldDataType.STRING,
            filterable=True,
        ),
    ],
))

documents = [
    {
        "id": "ca-leave",
        "title": "Canadian parental leave",
        "jurisdiction": "CA",
        "content": (
            "Canadian employees receive four weeks of paid parental leave."
        ),
    },
    {
        "id": "ca-request",
        "title": "Canadian leave requests",
        "jurisdiction": "CA",
        "content": (
            "Canadian employees submit parental leave requests through "
            "the HR portal at least 30 days before leave."
        ),
    },
    {
        "id": "us-leave",
        "title": "US parental leave",
        "jurisdiction": "US",
        "content": "US employees receive six weeks of paid parental leave.",
    },
]
search_client.upload_documents(documents=documents)

Referenz:SearchIndexClient, SearchIndex, SearchClient.upload_documents.

Melden Sie sich wie in Connect to Foundry IQ beschrieben an. Führen Sie die SDK-Codeausschnitte in der reihenfolge aus.

using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;

string searchEndpoint = "<search-endpoint>";
string indexName = "kb-tools-policy-index";
string knowledgeSourceName = "kb-tools-policy-source";
string knowledgeBaseName = "kb-tools-policy-kb";
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var searchClient = new SearchClient(
    new Uri(searchEndpoint), indexName, credential);

Reference:DefaultAzureCredential, SearchClient, SearchIndexClient.

Erstellen Sie den Index, und laden Sie drei synthetische Richtlinien hoch.

using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

var index = (await indexClient.CreateIndexAsync(
    new SearchIndex(indexName,
    [
        new SimpleField("id", SearchFieldDataType.String)
        {
            IsKey = true,
        },
        new SearchableField("title"),
        new SearchableField("content"),
        new SimpleField("jurisdiction", SearchFieldDataType.String)
        {
            IsFilterable = true,
        },
    ])).Value;

var documents = new SearchDocument[]
{
    new()
    {
        ["id"] = "ca-leave",
        ["title"] = "Canadian parental leave",
        ["jurisdiction"] = "CA",
        ["content"] =
            "Canadian employees receive four weeks of paid parental leave.",
    },
    new()
    {
        ["id"] = "ca-request",
        ["title"] = "Canadian leave requests",
        ["jurisdiction"] = "CA",
        ["content"] =
            "Canadian employees submit parental leave requests through " +
            "the HR portal at least 30 days before leave.",
    },
    new()
    {
        ["id"] = "us-leave",
        ["title"] = "US parental leave",
        ["jurisdiction"] = "US",
        ["content"] =
            "US employees receive six weeks of paid parental leave.",
    },
};
await searchClient.UploadDocumentsAsync(documents);

Referenz:SearchIndexClient, SearchIndex, SearchClient.UploadDocumentsAsync.

  1. Erstellen Sie die Wissensquelle.

    from azure.search.documents.indexes.models import (
        SearchIndexFieldReference,
        SearchIndexKnowledgeSource,
        SearchIndexKnowledgeSourceParameters,
    )
    
    source = index_client.create_knowledge_source(
        SearchIndexKnowledgeSource(
            name=knowledge_source_name,
            search_index_parameters=SearchIndexKnowledgeSourceParameters(
                search_index_name=index_name,
                source_data_fields=[
                    SearchIndexFieldReference(name="id"),
                    SearchIndexFieldReference(name="title"),
                    SearchIndexFieldReference(name="content"),
                    SearchIndexFieldReference(name="jurisdiction"),
                ],
            ),
        ),
    )
    

    Verweis:SearchIndexClient.

  2. Erstellen Sie eine modellfreie Wissensbasis mit minimalem Reasoning und extraktiver Ausgabe.

    from azure.search.documents.indexes.models import (
        KnowledgeBase,
        KnowledgeSourceReference,
    )
    from azure.search.documents.knowledgebases.models import (
        KnowledgeRetrievalMinimalReasoningEffort,
        KnowledgeRetrievalOutputMode,
    )
    
    knowledge_base = index_client.create_knowledge_base(KnowledgeBase(
        name=knowledge_base_name,
        knowledge_sources=[KnowledgeSourceReference(name=source.name)],
        retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
        output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
    ))
    

    Referenz:KnowledgeBase, SearchIndexClient.

  1. Erstellen Sie die Wissensquelle.

    using Azure.Search.Documents.Indexes.Models;
    
    var source = (await indexClient.CreateKnowledgeSourceAsync(
        new SearchIndexKnowledgeSource(knowledgeSourceName,
            new SearchIndexKnowledgeSourceParameters(indexName)
            {
                SourceDataFields =
                {
                    new SearchIndexFieldReference("id"),
                    new SearchIndexFieldReference("title"),
                    new SearchIndexFieldReference("content"),
                    new SearchIndexFieldReference("jurisdiction"),
                },
            }))).Value;
    

    Reference:SearchIndexClient.

  2. Erstellen Sie eine modellfreie Wissensbasis mit minimalem Reasoning und extraktiver Ausgabe.

    using Azure.Search.Documents.Indexes.Models;
    using Azure.Search.Documents.KnowledgeBases.Models;
    
    var knowledgeBase = (await indexClient.CreateKnowledgeBaseAsync(
        new KnowledgeBase(knowledgeBaseName,
            [new KnowledgeSourceReference(source.Name)])
        {
            RetrievalReasoningEffort =
                new KnowledgeRetrievalMinimalReasoningEffort(),
            OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData,
        })).Value;
    

    Reference:KnowledgeBase, SearchIndexClient.

  1. Legen Sie den Foundry IQ-Dienstendpunkt und das Zugriffstoken fest. Informationen zum Abrufen eines Zugriffstokens finden Sie unter Connect to Foundry IQ.

    @searchEndpoint = <search-endpoint>
    @searchAccessToken = <search-access-token>
    @indexName = kb-tools-policy-index
    @knowledgeSourceName = kb-tools-policy-source
    @knowledgeBaseName = kb-tools-policy-kb
    
  2. Erstellen Sie den Index mit durchsuchbarem Richtlinientext und einem filterbaren Gerichtsbarkeitsfeld.

    PUT {{searchEndpoint}}/indexes/{{indexName}}?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "name": "{{indexName}}",
      "fields": [
        { "name": "id", "type": "Edm.String", "key": true },
        { "name": "title", "type": "Edm.String", "searchable": true },
        { "name": "content", "type": "Edm.String", "searchable": true },
        { "name": "jurisdiction", "type": "Edm.String", "filterable": true }
      ]
    }
    

    Reference:Indexes – Erstellen oder Aktualisieren.

  3. Laden Sie drei synthetische Richtlinien hoch.

    POST {{searchEndpoint}}/indexes/{{indexName}}/docs/index?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "value": [
        {
          "@search.action": "upload", "id": "ca-leave",
          "title": "Canadian parental leave", "jurisdiction": "CA",
          "content": "Canadian employees receive four weeks of paid parental leave."
        },
        {
          "@search.action": "upload", "id": "ca-request",
          "title": "Canadian leave requests", "jurisdiction": "CA",
          "content": "Canadian employees submit parental leave requests through the HR portal at least 30 days before leave."
        },
        {
          "@search.action": "upload", "id": "us-leave",
          "title": "US parental leave", "jurisdiction": "US",
          "content": "US employees receive six weeks of paid parental leave."
        }
      ]
    }
    

    Reference:Documents - Index.

  4. Erstellen Sie die Wissensquelle.

    PUT {{searchEndpoint}}/knowledgesources/{{knowledgeSourceName}}?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "name": "{{knowledgeSourceName}}",
      "kind": "searchIndex",
      "searchIndexParameters": {
        "searchIndexName": "{{indexName}}",
        "sourceDataFields": [
          { "name": "id" }, { "name": "title" },
          { "name": "content" }, { "name": "jurisdiction" }
        ]
      }
    }
    

    Referenz:Wissensquellen – Erstellen oder Aktualisieren.

  5. Erstellen Sie die Wissensbasis mit minimaler Begründung und extraktiver Ausgabe.

    PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "name": "{{knowledgeBaseName}}",
      "knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
      "retrievalReasoningEffort": { "kind": "minimal" },
      "outputMode": "extractiveData"
    }
    

    Reference:Wissensdatenbanken – Erstellen oder Aktualisieren.

Hinzufügen eines benutzerdefinierten Tools zur Knowledge Base

Ein Tool verweist auf Wissensquellen, die bereits in der Wissensbasis definiert sind. In der Wissensdatenbank werden der Name, die Beschreibung und die Standardwerte des Tools gespeichert.

  1. Konfigurieren Sie den kanadischen Wissensquellenverweis.

    from azure.search.documents.indexes.models import (
        KnowledgeBaseToolKnowledgeSourceReference,
    )
    
    tool_source = KnowledgeBaseToolKnowledgeSourceReference(
        name=source.name,
        filter_add_on="jurisdiction eq 'CA'",
        reranker_threshold=0,
        max_output_documents=50,
        fail_on_error=True,
    )
    

    Referenz:Index-Modelle.

  2. Fügen Sie das Tool zur Wissensbasis hinzu.

    from azure.search.documents.indexes.models import (
        KnowledgeBaseRetrieveDefaults,
        KnowledgeBaseTool,
    )
    from azure.search.documents.knowledgebases.models import (
        KnowledgeRetrievalMinimalReasoningEffort,
    )
    
    tool = KnowledgeBaseTool(
        name="canada-hr-search",
        description="Find Canadian employee leave and benefits policies.",
        knowledge_sources=[tool_source],
        retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
        retrieve_defaults=KnowledgeBaseRetrieveDefaults(
            max_runtime_in_seconds=30,
            max_output_size_in_tokens=5000,
            max_output_documents=12,
        ),
    )
    knowledge_base.tools = [tool]
    knowledge_base = index_client.create_or_update_knowledge_base(
        knowledge_base,
    )
    

    Referenz:SearchIndexClient.

  1. Konfigurieren Sie den kanadischen Wissensquellenverweis.

    using Azure.Search.Documents.Indexes.Models;
    
    var toolSource = new KnowledgeBaseToolKnowledgeSourceReference(source.Name)
    {
        FilterAddOn = "jurisdiction eq 'CA'",
        RerankerThreshold = 0,
        MaxOutputDocuments = 50,
        FailOnError = true,
    };
    

    Reference:Index-Modelle.

  2. Fügen Sie das Tool zur Wissensbasis hinzu.

    using Azure.Search.Documents.Indexes.Models;
    using Azure.Search.Documents.KnowledgeBases.Models;
    
    var tool = new KnowledgeBaseTool(
        "canada-hr-search",
        "Find Canadian employee leave and benefits policies.",
        [toolSource])
    {
        RetrievalReasoningEffort =
            new KnowledgeRetrievalMinimalReasoningEffort(),
        RetrieveDefaults = new KnowledgeBaseRetrieveDefaults
        {
            MaxRuntimeInSeconds = 30,
            MaxOutputSizeInTokens = 5000,
            MaxOutputDocuments = 12,
        },
    };
    knowledgeBase.Tools.Add(tool);
    knowledgeBase = (await indexClient.CreateOrUpdateKnowledgeBaseAsync(
        knowledgeBase)).Value;
    

    Reference:SearchIndexClient.

Senden Sie die vollständige Wissensbasisdefinition mit einem Tool.

PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}

{
  "name": "{{knowledgeBaseName}}",
  "knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
  "retrievalReasoningEffort": { "kind": "minimal" },
  "outputMode": "extractiveData",
  "tools": [{
    "name": "canada-hr-search",
    "description": "Find Canadian employee leave and benefits policies.",
    "knowledgeSources": [{
      "name": "{{knowledgeSourceName}}",
      "filterAddOn": "jurisdiction eq 'CA'",
      "rerankerThreshold": 0,
      "maxOutputDocuments": 50,
      "failOnError": true
    }],
    "retrievalReasoningEffort": { "kind": "minimal" },
    "retrieveDefaults": {
      "maxRuntimeInSeconds": 30,
      "maxOutputSizeInTokens": 5000,
      "maxOutputDocuments": 12
    }
  }]
}

Referenz:Knowledge-Bases – Erstellen oder aktualisieren.

Der Zertifizierungsstellenfilter gehört zur Wissensquellenreferenz des Tools, nicht zur Wissensquellendefinition. Wenn Sie das Tool auswählen, wird der Abruf auf die konfigurierten Wissensquellen beschränkt, bevor der Abruf beginnt. In diesem Beispiel mit einer Quelle schränkt der Filter den Abruf auf kanadische Dokumente ein.

Aufrufen des Tools

Wählen Sie das Tool für den vorhandenen Abrufvorgang aus. Verwenden Sie eine semantische Intention, die die vollständige Frage enthält.

from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalMinimalReasoningEffort,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalSemanticIntent,
)

question = "What parental leave do Canadian employees receive and how do they request it?"
retrieval_client = KnowledgeBaseRetrievalClient(
    search_endpoint, credential, knowledge_base_name=knowledge_base.name,
)
request = KnowledgeBaseRetrievalRequest(
    tool_name="canada-hr-search",
    intents=[KnowledgeRetrievalSemanticIntent(search=question)],
    retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
    output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
    include_activity=True,
)
response = retrieval_client.retrieve(request)

Reference:KnowledgeBaseRetrievalClient.

using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

string question = "What parental leave do Canadian employees receive and how do they request it?";
var retrievalClient = new KnowledgeBaseRetrievalClient(
    new Uri(searchEndpoint), knowledgeBase.Name, credential);
var request = new KnowledgeBaseRetrievalRequest
{
    ToolName = "canada-hr-search",
    Intents = { new KnowledgeRetrievalSemanticIntent(question) },
    RetrievalReasoningEffort =
        new KnowledgeRetrievalMinimalReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData,
    IncludeActivity = true,
};
var response = await retrievalClient.RetrieveAsync(request);

Reference:KnowledgeBaseRetrievalClient.

Senden Sie eine semantische Absicht, die die vollständige Frage enthält.

POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}

{
  "toolName": "canada-hr-search",
  "intents": [{
    "type": "semantic",
    "search": "What parental leave do Canadian employees receive and how do they request it?"
  }],
  "retrievalReasoningEffort": { "kind": "minimal" },
  "outputMode": "extractiveData",
  "includeActivity": true
}

Reference:Knowledge Retrieval - Retrieve.

Vergewissern Sie sich, dass die Antwort sowohl kanadische Richtlinien als auch Ausgeschlossene us-leaveenthält. Informationen zum Überprüfen der zurückgegebenen Nachweise und der Quellausführung finden Sie unter Extrahierte Antwort, Referenzarray und Aktivitätsarray.

Lassen Sie den Toolnamen aus, um gewöhnlichen wissensbasierten Abruf zu verwenden. Ein leerer oder unbekannter Toolname schlägt fehl, anstatt auf den wissensbasierten Abruf zurückzufallen.

Standardeinstellungen anwenden und Filter überschneiden

Tool-Standardwerte setzen Knowledge-Base-Standardwerte außer Kraft. Explizite Anforderungswerte setzen gewöhnliche Toolstandardwerte außer Kraft, aber Anforderungsfilter ersetzen keine Toolfilter: sie kombinieren mit AND.

Verwenden Sie diese Steuerelemente nach der kanadischen Basislinie. Eine Anforderung kann dem Tool keine Wissensquellen hinzufügen oder den Filter ersetzen. Der Quellenausschluss alwaysQuerySource hat Vorrang vor der Einstellung eines Tools.

  1. Fordern Sie US-Richtlinien an, ohne ein Tool auszuwählen.

    from azure.search.documents.knowledgebases.models import (
        KnowledgeBaseRetrievalRequest,
        KnowledgeRetrievalMinimalReasoningEffort,
        KnowledgeRetrievalOutputMode,
        KnowledgeRetrievalSemanticIntent,
        SearchIndexKnowledgeSourceParams,
    )
    
    us_request = KnowledgeBaseRetrievalRequest(
        intents=[KnowledgeRetrievalSemanticIntent(
            search="What parental leave do US employees receive?",
        )],
        knowledge_source_params=[SearchIndexKnowledgeSourceParams(
            knowledge_source_name=source.name,
            filter_add_on="jurisdiction eq 'US'",
        )],
        retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
        output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
        include_activity=True,
    )
    us_response = retrieval_client.retrieve(us_request)
    

    Reference:KnowledgeBaseRetrievalClient.

  2. Wählen Sie das kanadische Tool in derselben US-Anfrage aus.

    us_request.tool_name = "canada-hr-search"
    intersection_response = retrieval_client.retrieve(us_request)
    

    Reference:KnowledgeBaseRetrievalClient.

    Der effektive Filter ist CA UND US, sodass keine Ergebnisse zurückgegeben werden.

  3. Legen Sie ein Dokumentbudget für die ursprüngliche kanadische Anforderung fest.

    request.max_output_documents = 1
    limited_response = retrieval_client.retrieve(request)
    

    Reference:KnowledgeBaseRetrievalClient.

  1. Fordern Sie US-Richtlinien an, ohne ein Tool auszuwählen.

    using Azure.Search.Documents.KnowledgeBases.Models;
    
    var usRequest = new KnowledgeBaseRetrievalRequest
    {
        Intents =
        {
            new KnowledgeRetrievalSemanticIntent(
                "What parental leave do US employees receive?"),
        },
        KnowledgeSourceParams =
        {
            new SearchIndexKnowledgeSourceParams(source.Name)
            {
                FilterAddOn = "jurisdiction eq 'US'",
            },
        },
        RetrievalReasoningEffort =
            new KnowledgeRetrievalMinimalReasoningEffort(),
        OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData,
        IncludeActivity = true,
    };
    var usResponse = await retrievalClient.RetrieveAsync(usRequest);
    

    Reference:KnowledgeBaseRetrievalClient.

  2. Wählen Sie das kanadische Tool auf derselben US-Anforderung aus.

    usRequest.ToolName = "canada-hr-search";
    var intersectionResponse = await retrievalClient.RetrieveAsync(usRequest);
    

    Reference:KnowledgeBaseRetrievalClient.

    Der effektive Filter ist CA UND US, sodass keine Ergebnisse zurückgegeben werden.

  3. Legen Sie ein Dokumentbudget für die ursprüngliche kanadische Anforderung fest.

    request.MaxOutputDocuments = 1;
    var limitedResponse = await retrievalClient.RetrieveAsync(request);
    

    Reference:KnowledgeBaseRetrievalClient.

  1. Fordern Sie US-Richtlinien ohne toolName mit einem expliziten US-Quellfilter an.

    POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "intents": [{
        "type": "semantic",
        "search": "What parental leave do US employees receive?"
      }],
      "knowledgeSourceParams": [{
        "knowledgeSourceName": "{{knowledgeSourceName}}",
        "kind": "searchIndex",
        "filterAddOn": "jurisdiction eq 'US'"
      }],
      "retrievalReasoningEffort": { "kind": "minimal" },
      "outputMode": "extractiveData",
      "includeActivity": true
    }
    

    Reference:Knowledge Retrieval - Retrieve.

  2. Wiederholen Sie dieselbe US-Frage und den Anfragefilter bei ausgewähltem kanadischen Tool.

    POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "toolName": "canada-hr-search",
      "intents": [{
        "type": "semantic",
        "search": "What parental leave do US employees receive?"
      }],
      "knowledgeSourceParams": [{
        "knowledgeSourceName": "{{knowledgeSourceName}}",
        "kind": "searchIndex",
        "filterAddOn": "jurisdiction eq 'US'"
      }],
      "retrievalReasoningEffort": { "kind": "minimal" },
      "outputMode": "extractiveData",
      "includeActivity": true
    }
    

    Reference:Knowledge Retrieval - Retrieve.

    Der effektive Filter ist CA UND US, sodass keine Ergebnisse zurückgegeben werden.

  3. Überschreiben Sie den normalen Ausgabedokumentstandard des Tools mit einem Anfragebudget für ein Dokument.

    POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{searchAccessToken}}
    
    {
      "toolName": "canada-hr-search",
      "intents": [{
        "type": "semantic",
        "search": "What parental leave do Canadian employees receive and how do they request it?"
      }],
      "retrievalReasoningEffort": { "kind": "minimal" },
      "outputMode": "extractiveData",
      "includeActivity": true,
      "maxOutputDocuments": 1
    }
    

    Reference:Knowledge Retrieval - Retrieve.

Die Quellebene filterAddOn wird für kompatible Suchindexquellen unterstützt; inkompatible Quelltypen bestehen die Validierung beim Speichern nicht. Verweisen Sie auf die Abfragezeitfilterung für das Anforderungs-Shape und agentische Abrufgrenzwerte für gemeinsame Grenzwerte.

Das Tool über MCP ermitteln und aufrufen

Führen Sie zum Ermitteln und Aufrufen von canada-hr-search die Schritte in Den MCP-Endpunkt aufrufen mit zwei Änderungen für benutzerdefinierte Knowledge-Base-Abruftools aus. Verwenden Sie den 2026-11-01-preview MCP-Endpunkt, da benutzerdefinierte Tools in früheren API-Versionen nicht verfügbar sind. Wenn Sie ein Tool zulassen oder aufrufen, verwenden Sie den konfigurierten Namen canada-hr-search anstelle von knowledge_base_retrieve; Discovery gibt denselben Namen zurück.

Tool entfernen

Löschen Sie die Tools, und aktualisieren Sie die Wissensbasis.

knowledge_base.tools = []
knowledge_base = index_client.create_or_update_knowledge_base(
    knowledge_base,
)

Reference:SearchIndexClient.

Leeren Sie die Tools, und aktualisieren Sie die Wissensbasis.

knowledgeBase.Tools.Clear();
knowledgeBase = (await indexClient.CreateOrUpdateKnowledgeBaseAsync(
    knowledgeBase)).Value;

Referenz:SearchIndexClient.

Senden Sie die vollständige Wissensbasisdefinition mit einem leeren tools Array.

PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}

{
  "name": "{{knowledgeBaseName}}",
  "knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
  "retrievalReasoningEffort": { "kind": "minimal" },
  "outputMode": "extractiveData",
  "tools": []
}

Reference:Wissensdatenbanken – Erstellen oder Aktualisieren.

Troubleshooting

Ausführlichere Problembehandlung finden Sie unter Abfragen einer Wissensdatenbank mithilfe der Abrufen-Aktion oder des MCP-Endpunkts.

Bereinigen von Beispielressourcen

Das Entfernen eines Tools löscht weder die Wissensbasis noch deren Quelle. Löschen Sie nur Ressourcen, die Sie für dieses Beispiel erstellt haben, in Abhängigkeitsreihenfolge: Knowledge Base, Wissensquelle und dann Index.

index_client.delete_knowledge_base(knowledge_base_name)
index_client.delete_knowledge_source(knowledge_source_name)
index_client.delete_index(index_name)

Reference:SearchIndexClient.

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
await indexClient.DeleteIndexAsync(indexName);

Reference:SearchIndexClient.

### Delete the owned sample KB
DELETE {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}

### Delete the owned sample knowledge source
DELETE {{searchEndpoint}}/knowledgesources/{{knowledgeSourceName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}

### Delete the owned sample index
DELETE {{searchEndpoint}}/indexes/{{indexName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}

Referenz:Wissensdatenbanken, Wissensquellen und Indizes.