Create a knowledge base in Azure AI Search

Note

This agentic retrieval feature is generally available in the 2026-04-01 REST API version via programmatic access. The Azure portal continue to provide preview-only access to all agentic retrieval features.

If you choose to use a preview REST API version, you can access capabilities that aren't yet generally available for this feature. Preview features are provided without a service-level agreement and aren't recommended for production workloads.

Important

These features and functionality are part of the 2026-05-01-preview REST API. The 2026-05-01-preview is licensed to you as part of your Azure subscription and is subject to the terms applicable to "Previews" in the Microsoft Product Terms, the Microsoft Products and Services Data Protection Addendum ("DPA"), and the Supplemental Terms of Use for Azure Previews.

The 2026-05-01-preview supports connections to other Microsoft services and third-party services. Use of these services is subject to their respective terms and might result in data processing or storage outside of the Azure compliance boundary, as well as data flowing into the Azure compliance boundary.

It's your responsibility to manage whether your data will flow outside of your organization's compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards.

In Azure AI Search, a knowledge base is a top-level object that orchestrates agentic retrieval. It defines which knowledge sources to query and the default behavior for retrieval operations. At query time, the retrieve method targets the knowledge base to run the configured retrieval pipeline.

A knowledge base specifies:

  • One or more knowledge sources that point to searchable content.
  • An optional LLM for query planning, answer synthesis, or web content summarization. Supported tasks vary by API version and knowledge source type.
  • Custom properties that control routing, source selection, and object encryption.

Usage support

Azure portal .NET SDK Python SDK Java SDK JavaScript SDK REST API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️

  • Required Azure.Search.Documents package:

    • For 2026-05-01-preview features, the latest preview package: dotnet add package Azure.Search.Documents --prerelease

    • For 2026-04-01 features, the latest stable package: dotnet add package Azure.Search.Documents

  • Required azure-search-documents package:

    • For 2026-05-01-preview features, the latest preview package: pip install --pre azure-search-documents

    • For 2026-04-01 features, the latest stable package: pip install azure-search-documents

Configure access

Azure AI Search needs access to the LLM from Azure AI services. We recommend Microsoft Entra ID for authentication and role-based access for authorization. To assign roles, you must be an Owner or User Access Administrator. If you can't use roles, use key-based authentication instead.

  1. Configure Azure AI Search to use a managed identity.

  2. On your model provider, assign Cognitive Services User to the managed identity of your search service. If you're testing locally, assign the same role to your user account.

  3. For local testing, follow the steps in Quickstart: Connect without keys to sign in to a specific subscription and tenant. Use DefaultAzureCredential instead of AzureKeyCredential in each request, which should look similar to the following example:

    // Authenticate using roles
using Azure.Search.Documents.Indexes;
using Azure.Identity;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

  1. Configure Azure AI Search to use a managed identity.

  2. On your model provider, assign Cognitive Services User to the managed identity of your search service. If you're testing locally, assign the same role to your user account.

  3. For local testing, follow the steps in Quickstart: Connect without keys to sign in to a specific subscription and tenant. Use DefaultAzureCredential instead of AzureKeyCredential in each request, which should look similar to the following example:

    # Authenticate using roles
from azure.identity import DefaultAzureCredential
index_client = SearchIndexClient(endpoint = "search_url", credential = DefaultAzureCredential())

  1. Configure Azure AI Search to use a managed identity.

  2. On your model provider, assign Cognitive Services User to the managed identity of your search service. If you're testing locally, assign the same role to your user account.

  3. For local testing, follow the steps in Quickstart: Connect without keys to get a personal access token for a specific subscription and tenant. Specify your access token in each request, which should look similar to the following example:

    # List indexes using roles
GET https://{{search-url}}/indexes?api-version=2026-04-01
Content-Type: application/json
Authorization: Bearer {{access-token}}

Important

Code snippets in this article use API keys. If you use role-based authentication, update each request accordingly. In a request that specifies both approaches, the API key takes precedence.

Check for existing knowledge bases

A knowledge base is a top-level, reusable object. Knowing about existing knowledge bases is helpful for either reuse or naming new objects.

Run the following code to list existing knowledge bases by name. The list includes all knowledge bases on your search service, regardless of which API version you used to create them.

// List knowledge bases by name
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

Reference: SearchIndexClient

# List knowledge bases by name
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

Reference: SearchIndexClient

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

Reference: Knowledge Bases - List

You can also return a single knowledge base by name to review its JSON definition.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Reference: SearchIndexClient

# Get a knowledge base definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

kb = index_client.get_knowledge_base("knowledge_base_name")
print(json.dumps(kb.as_dict(), indent = 2))

Reference: SearchIndexClient

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Content-Type: application/json
api-key: {{search-api-key}}

Reference: Knowledge Bases - Get

The following JSON is an example response for a knowledge base.

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Note

The response schema reflects the API version you used to create the knowledge base. A knowledge base created with the generally available 2026-04-01 API version returns a narrower definition than the 2026-05-01-preview. For more information about which properties each version supports, see the next section.

Create a knowledge base

Important

The 2026-04-01 API version only accepts generally available knowledge source types and supports minimal, extractive retrieval. Preview-only capabilities, such as query planning, answer synthesis, and configurable reasoning effort, aren't supported. For full functionality, use the 2026-05-01-preview.

After you create a knowledge base, you can update its properties at any time. If the knowledge base is in use, updates take effect on the next retrieval.

// Create a knowledge base
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var aoaiParams = new AzureAIservicesVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var knowledgeBase = new KnowledgeBase(
    name: "my-kb",
    knowledgeSources: new KnowledgeSourceReference[] 
    { 
        new KnowledgeSourceReference("hotels-ks"),
        new KnowledgeSourceReference("earth-at-night-ks")
    }
)
{
    Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    AnswerInstructions = "Provide a two-sentence, concise, and informative answer based on the retrieved documents.",
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { new KnowledgeBaseAzureAIservicesModel(AzureAIservicesParameters: aoaiParams) },
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBase.Name}' created or updated successfully.");

Reference: SearchIndexClient, KnowledgeBase

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    KnowledgeBase,
    KnowledgeSourceReference,
)
from azure.search.documents.knowledgebases.models import KnowledgeRetrievalLowReasoningEffort

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

aoai_params = AzureAIservicesVectorizerParameters(
    resource_url = "aoai_endpoint",
    api_key="aoai_api_key",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two-sentence, concise, and informative answer based on the retrieved documents.",
    output_mode = "answerSynthesis",
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureAIservicesModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort(),
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

Reference: SearchIndexClient, KnowledgeBase

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2026-05-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "AzureAIservices",
            "AzureAIservicesParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-5.4-mini",
                "modelName": "gpt-5.4-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

Reference: Knowledge Bases - Create or Update

Knowledge base properties

Pass the following properties to create a knowledge base.

Name Description Type Required
Name The name of the knowledge base. It must be unique within the knowledge bases collection and follow the naming guidelines for objects in Azure AI Search. String Yes
KnowledgeSources One or more supported knowledge sources. Array Yes
Description A description of the knowledge base. The LLM uses the description to inform query planning. String No
RetrievalInstructions A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Instructions are passed directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. String No
AnswerInstructions Custom instructions to shape synthesized answers. The default is null. For more information, see Use answer synthesis for citation-backed responses. String No
OutputMode Valid values are AnswerSynthesis for an LLM-formulated answer or ExtractedData for full search results that you can pass to an LLM as a downstream step. String No
RetrievalReasoningEffort Determines the level of LLM-related query processing. Valid values are minimal, low (default), and medium. For more information, see Set the retrieval reasoning effort. Object No
Name Description Type Required
name The name of the knowledge base. It must be unique within the knowledge bases collection and follow the naming guidelines for objects in Azure AI Search. String Yes
description A description of the knowledge base. The LLM uses the description to inform query planning. String No
retrieval_instructions A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Pass instructions directly to the LLM. It's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. String No
answer_instructions Custom instructions to shape synthesized answers. The default is null. For more information, see Use answer synthesis for citation-backed responses. String No
output_mode Valid values are answerSynthesis for an LLM-formulated answer or extractedData for full search results that you can pass to an LLM as a downstream step. String No
knowledge_sources One or more supported knowledge sources. Array Yes
encryption_key A customer-managed key to encrypt sensitive information in both the knowledge base and the generated objects. Object No
retrieval_reasoning_effort Determines the level of LLM-related query processing. Valid values are minimal, low (default), and medium. For more information, see Set the retrieval reasoning effort. Object No
Name Description Type Required
name The name of the knowledge base. It must be unique within the knowledge bases collection and follow the naming guidelines for objects in Azure AI Search. String Yes
description A description of the knowledge base. The LLM uses the description to inform query planning. String No
retrievalInstructions A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. You pass instructions directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. String No
answerInstructions Custom instructions to shape synthesized answers. The default is null. For more information, see Use answer synthesis for citation-backed responses. String No
outputMode Valid values are answerSynthesis for an LLM-formulated answer or extractedData for full search results that you can pass to an LLM as a downstream step. String No
knowledgeSources One or more supported knowledge sources. Array Yes
encryptionKey A customer-managed key to encrypt sensitive information in both the knowledge base and the generated objects. Object No
retrievalReasoningEffort.kind Determines the level of LLM-related query processing. Valid values are minimal, low (default), and medium. For more information, see Set the retrieval reasoning effort. Object No

Query a knowledge base

After you create a knowledge base, use the retrieve action to query it and verify the LLM connection.

Delete a knowledge base

If you no longer need the knowledge base or need to rebuild it on your search service, run the following code to delete the object.

// Delete a knowledge base
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

Reference: SearchIndexClient

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

Reference: SearchIndexClient

# Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{search-api-key}}

Reference: Knowledge Bases - Delete

Related content

  • Last updated on