Edit

Share via

Create a search index knowledge source

Note

This feature is currently in public preview. This preview is provided without a service-level agreement and isn't recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

A search index knowledge source specifies a connection to an Azure AI Search index that provides searchable content in an agentic retrieval pipeline. Knowledge sources are created independently, referenced in a knowledge agent, and used as grounding data when an agent or chatbot calls a retrieve action at query time.

Knowledge sources are new in the 2025-08-01-preview release.

Prerequisites

You need a search index containing plain text or vector content with a semantic configuration. Review the index criteria for agentic retrieval. The index must be on the same search service as the knowledge agent.

To try the examples in this article, we recommend Visual Studio Code with the REST Client extension for sending preview REST API calls to Azure AI Search. Currently, there's no portal support.

Check for existing knowledge sources

A knowledge source is a top-level, reusable object. All knowledge sources must be uniquely named within the knowledge sources collection. Knowing about existing knowledge sources is helpful for either reuse or naming new objects.

Use Knowledge Sources - Get (REST API) to list knowledge sources by name and type.

### List knowledge sources by name and type
GET {{search-url}}/knowledgeSources?api-version=2025-08-01-preview&$select=name,kind
api-key: {{api-key}}
Content-Type: application/json

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

### Get a knowledge source definition
GET {{search-url}}/knowledgeSources/{{knowledge-source-name}}?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

The following JSON is an example response for a searchIndex knowledge source. Notice that the knowledge source specifies a single index name and which fields in the index to include in the query.

{

  "name": "earth-at-night-ks",
  "kind": "searchIndex",
  "description": "Earth at night e-book knowledge source",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "earth_at_night",
    "sourceDataSelect": "page_chunk,page_number"
  },
  "azureBlobParameters": null,
  "webParameters": null
}

Note

The webParameters property isn't operational in this preview and is reserved for future use.

Create a knowledge source

To create a searchIndex knowledge source:

  1. Set environment variables at the top of your file.

    @search-url = <YOUR SEARCH SERVICE URL>
@api-key = <YOUR ADMIN API KEY>
@ks-name = <YOUR KNOWLEDGE SOURCE NAME>
@index-name = <YOUR INDEX NAME>

  2. Use the 2025-08-01-preview of Knowledge Sources - Create or Update (REST API) or an Azure SDK preview package that provides equivalent functionality to formulate the request.

    POST {{search-url}}/knowledgeSources?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name" : "{{ks-name}}",
    "kind" : "searchIndex",
    "description" : "Earth at night e-book knowledge source",
    "searchIndexParameters" :{
      "searchIndexName" : "{{index-name}}",
      "sourceDataSelect" : "page_chunk,page_number"
    }
}

  3. Select Send Request.

Key points:

  • name must be unique within the knowledge sources collection and follow the naming guidelines for objects in Azure AI Search.

  • kind must be searchIndex for a search index knowledge source.

  • searchIndexName is the name of your index, which must be designed for agentic retrieval.

  • sourceDataSelect is the list of index fields returned when you specify includeReferenceSourceData in the knowledge agent definition. These fields are used for citations and should be retrievable. Examples include the document name, file name, page numbers, or chapter numbers.

Assign to a knowledge agent

If you're satisfied with the index, continue to the next step: specifying the knowledge source in a knowledge agent.

Within the knowledge agent, there are more properties to set on the knowledge source that are specific to query operations.

Delete a knowledge source

If you no longer need the knowledge source, or if you need to rebuild it on the search service, use this request to delete the current object.

Before you can delete a knowledge source, you must delete any knowledge agent that references it, or remote the references in an update action. The associated index and any indexer pipeline objects created from the knowledge source are standalone objects and don't need to be deleted or updated in tandem with the knowledge source.

If you try to delete a knowledge source that's in use, the action fails and a list of affected knowledge agents is returned.

  1. Start by getting a list of all knowledge agents. This request returns all knowledge agents on your search service.

    ### Get the knowledge agent
GET {{search-endpoint}}/agents?api-version=2025-08-01-preview&$select=name
api-key: {{api-key}}
Content-Type: application/json

    An example response might look like the following:

     {
     "@odata.context": "https://my-demo-search-service.search.windows.net/$metadata#agents(name)",
     "value": [
     {
         "name": "earth-blob-ka"
     },
     {
         "name": "hotels-sample-ka"
     }
     ]
 }

  2. Get the individual knowledge agent definition to check for knowledge source references.

    GET {{search-endpoint}}/agents/hotels-sample-ka?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

    An example response might look like the following:

     {
   "name": "hotels-sample-ka",
   "description": null,
   "retrievalInstructions": null,
   "knowledgeSources": [
     {
       "name": "hotels-sample-ks",
       "alwaysQuerySource": false,
       "includeReferences": true,
       "includeReferenceSourceData": false,
       "maxSubQueries": null,
       "rerankerThreshold": null
     }
   ],
   "models": [ trimmed for brevity ],
   "outputConfiguration": { trimmed for brevity },
   "requestLimits": { trimmed for brevity},
   "encryptionKey": null
 }

  3. Either update the knowledge agent by removing the knowledge source if you have multiple sources, or delete the knowledge agent. This example shows deletion.

    ### Delete knowledge agent
DELETE {{search-endpoint}}/agents/hotels-sample-ka?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

  4. Delete the knowledge source.

    ### Delete a knowledge source definition
GET {{search-endpoint}}/knowledgeSources/hotels-sample-ks?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

Related content