Edit

Use answer synthesis for citation-backed responses in Azure AI Search (preview)

Note

Azure AI Search is available through the Azure portal, REST APIs, and Azure SDKs. It also underpins Foundry IQ, the managed knowledge layer that transforms enterprise content into reusable, permission-aware knowledge bases for agents in the Microsoft Foundry portal.

Important

Features, capabilities, or properties marked (preview) aren't covered by a service-level agreement, aren't recommended for production workloads, and might change or be constrained before they become generally available. The Azure AI Search preview terms apply to all preview functionality, whether it's standalone or part of a generally available feature.

By default, a knowledge base in Azure AI Search performs data extraction, which returns raw grounding chunks from your knowledge sources. Data extraction is useful for retrieving specific information but lacks the context and reasoning necessary for complex queries.

You can instead enable answer synthesis (preview), which uses the LLM specified in your knowledge base to answer queries in natural language. Each answer includes citations to the retrieved sources and follows any instructions you provide, such as using bulleted lists.

You can set this property in a knowledge base or a retrieve request. The knowledge base setting establishes the default for all queries, while the retrieve request setting overrides the default on a query-by-query basis.

Usage support

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

Prerequisites

  • An Azure AI Search service with a knowledge base that specifies an LLM.

  • Permission to update knowledge bases. Configure keyless authentication with the Search Service Contributor role assigned to your user account (recommended) or use an admin API key.

  • For outbound calls to the LLM, the search service must have a managed identity with Cognitive Services User permissions on the Microsoft Foundry resource.

  • The latest Azure.Search.Documents preview package: dotnet add package Azure.Search.Documents --prerelease

  • For keyless authentication, the Azure.Identity package: dotnet add package Azure.Identity

Limitations and considerations

  • The minimal retrieval reasoning effort disables LLM processing, so it's incompatible with answer synthesis in both knowledge base definitions and retrieve requests. For more information, see Set the retrieval reasoning effort.

  • Answer synthesis incurs pay-as-you-go charges from Azure OpenAI, which are based on the number of input and output tokens. Charges appear under the LLM assigned to the knowledge base. For more information, see Region availability, limits, and billing.

Enable answer synthesis in a knowledge base

This section demonstrates how to enable answer synthesis in an existing knowledge base. Although you can use this configuration for new knowledge bases, knowledge base creation is beyond the scope of this article.

Set OutputMode to "answerSynthesis" on the KnowledgeBase definition. Optionally, set AnswerInstructions to customize the answer output. The following example instructs the knowledge base to Use concise bulleted lists.

var aoaiParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri("<aoai-endpoint>"),
    DeploymentName = "<aoai-gpt-deployment>",
    ModelName = "<aoai-gpt-model>",
};

var knowledgeBase = new KnowledgeBase(
    name: "<knowledge-base-name>",
    knowledgeSources: new[] { new KnowledgeSourceReference("<knowledge-source-name>") })
{
    Models = { new KnowledgeBaseAzureOpenAIModel(aoaiParams) },
    OutputMode = "answerSynthesis",
    AnswerInstructions = "Use concise bulleted lists",
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);

Reference: SearchIndexClient, KnowledgeBase

Set output_mode to "answerSynthesis" on the KnowledgeBase definition. Optionally, set answer_instructions to customize the answer output. The following example instructs the knowledge base to Use concise bulleted lists.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    KnowledgeBase,
    KnowledgeBaseAzureOpenAIModel,
    KnowledgeSourceReference,
)

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url="<aoai-endpoint>",
    deployment_name="<aoai-gpt-deployment>",
    model_name="<aoai-gpt-model>",
)

knowledge_base = KnowledgeBase(
    name="<knowledge-base-name>",
    models=[KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters=aoai_params)],
    knowledge_sources=[KnowledgeSourceReference(name="<knowledge-source-name>")],
    output_mode="answerSynthesis",
    answer_instructions="Use concise bulleted lists",
)

index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)
index_client.create_or_update_knowledge_base(knowledge_base)

Reference: SearchIndexClient, KnowledgeBase

Set outputMode to "answerSynthesis" on the knowledge base definition. Optionally, set answerInstructions to customize the answer output. The following example instructs the knowledge base to Use concise bulleted lists.

### Enable answer synthesis in a knowledge base
PUT {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
    "name": "{{knowledge-base-name}}",
    "knowledgeSources": [ ... // OMITTED FOR BREVITY ],
    "models": [ ... // OMITTED FOR BREVITY ],
    "outputMode": "answerSynthesis",
    "answerInstructions": "Use concise bulleted lists"
}

Reference: Knowledge Base - Create or Update

Enable answer synthesis in a retrieve request

For per-query control over the response format, you can enable answer synthesis at query time. This approach overrides the default output mode specified in the knowledge base.

Set OutputMode to "answerSynthesis" on a KnowledgeBaseRetrievalRequest.

var client = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    credential: credential);

var request = new KnowledgeBaseRetrievalRequest();
request.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[]
        {
            new KnowledgeBaseMessageTextContent("What is healthcare?")
        }) { Role = "user" });
request.OutputMode = "answerSynthesis";

var result = await client.RetrieveAsync(request);

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

Set output_mode to "answerSynthesis" on a KnowledgeBaseRetrievalRequest.

from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
)

agent_client = KnowledgeBaseRetrievalClient(
    endpoint=search_endpoint,
    credential=credential,
    knowledge_base_name=knowledge_base_name,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What is healthcare?")],
        )
    ],
    output_mode="answerSynthesis",
)

result = agent_client.retrieve(retrieval_request=request)

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

Set outputMode to "answerSynthesis" on a retrieve request.

### Enable answer synthesis in a retrieve request
POST {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is healthcare?"
                }
            ]
        }
    ],
    "outputMode": "answerSynthesis"
}

Reference: Knowledge Retrieval - Retrieve

Get a synthesized answer

When answer synthesis is enabled, the knowledge base returns a natural-language answer based on the instructions you optionally specified in the knowledge base. Citations to your knowledge sources are formatted as [ref_id:<number>].

For example, if your instructions are Use concise bulleted lists and your query is What is healthcare?, the response should be similar to the following example.

{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "- Healthcare encompasses various services provided to patients and the general population ..."
        }
      ]
    }
  ]
}

The full text output is as follows:

"- Healthcare encompasses various services provided to patients and the general population, including primary health services, hospital care, dental care, mental health services, and alternative health services [ref_id:1].\n- It involves the delivery of safe, effective, patient-centered care through different modalities, such as in-person encounters, shared medical appointments, and group education sessions [ref_id:0].\n- Behavioral health is a significant aspect of healthcare, focusing on the connection between behavior and overall health, including mental health and substance use [ref_id:2].\n- The healthcare system aims to ensure quality of care, access to providers, and accountability for positive outcomes while managing costs effectively [ref_id:2].\n- The global health system is evolving to address complex health needs, emphasizing the importance of cross-sectoral collaboration and addressing social determinants of health [ref_id:4]."

Depending on your knowledge base's configuration, the response might include other information, such as activity logs and reference arrays. For more information, see Create a knowledge base.

Related content

  • Last updated on