Edit

What is a knowledge source?

Note

Some agentic retrieval features are generally available in the 2026-04-01 REST API via programmatic access. The Azure portal and Microsoft Foundry portal continue to provide preview-only access to all agentic retrieval features. For migration guidance, including a breakdown of what's generally available and what remains in preview, see Migrate agentic retrieval code to the latest version.

If you choose to use a preview REST API, you can access agentic retrieval capabilities that aren't yet generally available. Preview features are provided without a service-level agreement and aren't recommended for production workloads. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

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 Microsoft 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. For more information, see the Azure AI Search Transparency Note.

A knowledge source specifies the content used for agentic retrieval. It either encapsulates a search index populated by external data, or it's a direct connection to a remote target such as Bing or SharePoint that's queried directly. A knowledge source is a required definition in a knowledge base.

  • Create a knowledge source as a top-level resource on your search service. Each knowledge source points to exactly one data structure, either a search index that meets the criteria for agentic retrieval or a supported external resource.

  • Reference one or more knowledge sources in a knowledge base. In an agentic retrieval pipeline, you can query against multiple knowledge sources in a single request. Subqueries are generated for each knowledge source. Top results are returned in the retrieval response.

  • For certain knowledge sources, you can use a knowledge source definition to generate a full indexer pipeline (data source, skillset, indexer, and index) that works for agentic retrieval. Instead of creating multiple objects manually, the information in the knowledge source is used to generate all objects, including a populated, chunked, and searchable index.

Make sure you have at least one knowledge source before creating a knowledge base. The full specification for knowledge sources and knowledge bases can be found in the REST API reference.

Working with a knowledge source

  • Creation path: first create a knowledge source, then create a knowledge base.

  • Deletion path: update or delete knowledge bases to remove references to a knowledge source, and then delete the knowledge source last.

  • A knowledge source, its index, and the knowledge base must all exist on the same search service. External content is either accessed over the public internet (Bing) or in a Microsoft tenant (remote SharePoint).

Supported knowledge sources

You can create the following knowledge sources:

Kind Indexed or remote
"searchIndex" API wraps an existing index. Indexed
"azureBlob" API generates an indexer pipeline that pulls from a blob container. Indexed
"file" API uploads files directly to Azure AI Search for processing and retrieval. Indexed
"indexedOneLake" API generates an indexer pipeline that pulls from a lakehouse. Indexed
"indexedSql" API (preview) generates an indexer pipeline that pulls from an Azure SQL table or view. Indexed
"indexedSharePoint" API (preview) generates an indexer pipeline that pulls from a SharePoint site. Indexed
"remoteSharePoint" API (preview) retrieves content directly from SharePoint. Remote
"fabricOntology" API (preview) queries a Microsoft Fabric ontology for entity-based and relationship-based answers. Remote
"workIQ" API (preview) queries Work IQ directly for organizational intelligence. Remote
"web" API retrieves real-time grounding data from Microsoft Bing. Remote
"mcpServer" API (preview) connects to an external MCP server for live, tool-backed retrieval. Remote
"fabricDataAgent" API (preview) queries a Microsoft Fabric data agent directly. Remote

Indexed knowledge sources point to a target index on Azure AI Search. Query execution is local to the search engine on your search service. Keyword (full-text search), vector, and hybrid query capabilities are used for retrieving data from indexed knowledge sources.

You access remote knowledge sources at query time. The agentic retrieval engine calls the retrieval APIs that are native to the platform (Bing or SharePoint APIs).

All retrieved content, whether indexed or remote, is pulled into the ranking pipeline in Azure AI Search where it's scored for relevance, merged (assuming multiple queries), reranked, and returned in the retrieval response.

Sensitivity label ingestion (preview)

For blob, indexed OneLake, and indexed SharePoint knowledge sources, you can also ingest Microsoft Purview sensitivity labels by setting ingestionPermissionOptions to include sensitivityLabel. Make sure that you follow all the requirements before setting this value. After they're synchronized to the index, labels are surfaced in retrieve responses and used to enforce document-level access at query time. For more information, see Enforce permissions at query time.

If your indexed knowledge source uses a chunked index, such as with integrated vectorization or a custom Text Split skill, you must also map the sensitivity label to each chunk row via index projections in the skillset. Otherwise, chunk-level references in retrieve responses won't be returned if they have labels in the source document.

Creating knowledge sources

Create knowledge sources as standalone objects. Then, specify them in a knowledge base within a "knowledgeSources" array.

To create objects on a search service, you need Search Service Contributor permissions. If you're using a knowledge source that creates an indexer pipeline, you also need Search Index Data Contributor permissions to load an index. Alternatively, you can use an API admin key instead of roles.

Use the Azure portal, REST API, or an Azure SDK package to create a knowledge source. The following links provide instructions for creating a knowledge source:

After you create the knowledge source, reference it in a knowledge base.

Asset store for image serving (preview)

For file-based indexed knowledge sources (blob, indexed OneLake, and indexed SharePoint), you can configure an assetStore in the knowledge source's ingestionParameters to persist images that are embedded in your source documents. When you also enable image serving on the knowledge base, the retrieve action injects those images into the answer synthesis prompt so the LLM can reason over diagrams, charts, and extracted image content. For more information, see Surface document-embedded images in agentic retrieval (preview).

Using knowledge sources

You can explicitly control knowledge source usage by setting alwaysQuery on the knowledge source definition or through steering instructions used during query planning. Steering instructions refer to descriptions on an index, or explicit retrieval instructions in the knowledge source, that provide guidance on when to use the index. Query planning happens when you use a low or medium retrieval reasoning effort from the LLM. For a minimal reasoning effort, all knowledge sources listed in the knowledge base are in scope for every query. For low and medium, the knowledge base and the LLM can determine at query time which knowledge sources are likely to provide the best search corpus.

Knowledge source selection logic is based on these factors:

  • Is alwaysQuery set? If yes, the knowledge source is always used on every query.

  • The name of the knowledge source.

  • The description of an index, assuming an indexed knowledge source.

  • The retrievalInstructions specified in the retrieve action or in the knowledge base definition provides guidance that includes or excludes a knowledge source. It's similar to a prompt. You can specify brevity, tone, and formatting as a retrieval instruction.

  • outputMode on a knowledge base also affects query output and what goes in the response.

Use a retrieval reasoning effort to control LLM usage (preview)

Not all solutions benefit from LLM query planning and execution. If simplicity and speed outweigh the benefits the LLM query planning and context engineering provide, specify a minimal reasoning effort to prevent LLM processing in your pipeline.

For low and medium, the level of LLM processing is either a balanced or maximal approach that improves relevance. For more information, see Set the retrieval reasoning effort.

  • Last updated on