Query a knowledge base using the retrieve action or MCP endpoint

• If you call the MCP endpoint through the Azure OpenAI Responses API, you need:

  • A deployed LLM and the Cognitive Services OpenAI User role (or an API key) on the Foundry resource. You can reuse the LLM and resource specified in your knowledge base, if applicable.

  • The Azure.AI.OpenAI package: dotnet add package Azure.AI.OpenAI

• Required Azure.Search.Documents package:

  • For 2026-08-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

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

• If you call the MCP endpoint through the Azure OpenAI Responses API, you need:

  • A deployed LLM and the Cognitive Services OpenAI User role (or an API key) on the Foundry resource. You can reuse the LLM and resource specified in your knowledge base, if applicable.

  • The openai package: pip install openai

• Required azure-search-documents package:

  • For 2026-08-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

• For keyless authentication, the azure-identity package: pip install azure-identity

• Required Search Service REST API version:

  • For preview features: 2026-08-01-preview

  • For generally available features: 2026-04-01

• For keyless authentication, include a Microsoft Entra ID token in the Authorization header of each HTTP request.

using System;
using System.Linq;
using Azure.Identity;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var client = new KnowledgeBaseRetrievalClient(
    new Uri("<search-endpoint>"),
    "product-catalog-kb",
    new DefaultAzureCredential());

var request = new KnowledgeBaseRetrievalRequest
{
    IncludeActivity = true
};
request.Intents.Add(
    new KnowledgeRetrievalSemanticIntent(
        "Find the power adapter for SKU 88421."));
request.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("product-catalog-ks")
    {
        AlwaysQuerySource = true,
        IncludeReferences = true,
        ResultsProcessing = KnowledgeSourceResultsProcessing.None
    });

var result = await client.RetrieveAsync(request);
Console.WriteLine(
    $"References with a reranker score: "
    + $"{result.Value.References.Count(x => x.RerankerScore.HasValue)}");

Reference: KnowledgeBaseRetrievalClient, SearchIndexKnowledgeSourceParams

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalSemanticIntent,
    SearchIndexKnowledgeSourceParams,
)

client = KnowledgeBaseRetrievalClient(
    endpoint="<search-endpoint>",
    knowledge_base_name="product-catalog-kb",
    credential=DefaultAzureCredential(),
)

request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search="Find the power adapter for SKU 88421."
        )
    ],
    include_activity=True,
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="product-catalog-ks",
            always_query_source=True,
            include_references=True,
            results_processing="none",
        )
    ],
)

result = client.retrieve(request)
reranked_count = sum(
    reference.reranker_score is not None
    for reference in result.references
)
print("References with a reranker score:", reranked_count)

Reference: KnowledgeBaseRetrievalClient, SearchIndexKnowledgeSourceParams

@search-endpoint = <search-endpoint>
@search-access-token = <search-access-token> // Run: az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv
@knowledge-base-name = product-catalog-kb

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

{
  "intents": [
    {
      "type": "semantic",
      "search": "Find the power adapter for SKU 88421."
    }
  ],
  "includeActivity": true,
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "product-catalog-ks",
      "kind": "searchIndex",
      "alwaysQuerySource": true,
      "includeReferences": true,
      "resultsProcessing": "none"
    }
  ]
}

Reference: Knowledge Retrieval - Retrieve

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

var client = new KnowledgeBaseRetrievalClient(
    new Uri("<search-endpoint>"),
    "<knowledge-base-name>",
    new DefaultAzureCredential());

var request = new KnowledgeBaseRetrievalRequest
{
    OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData,
    RetrievalReasoningEffort =
        new KnowledgeRetrievalMinimalReasoningEffort(),
    IncludeActivity = true,
};
request.Intents.Add(
    new KnowledgeRetrievalSemanticIntent("What is the return policy?"));
request.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams(
        "<knowledge-source-name>")
    {
        ResultsProcessing = KnowledgeSourceResultsProcessing.None,
        IncludeReferences = true,
    });

var eventCounts = new Dictionary<string, int>();

await foreach (var item in client.RetrieveStreamAsync(request))
{
    eventCounts.TryGetValue(item.EventType, out var count);
    eventCounts[item.EventType] = count + 1;
}

foreach (var (eventType, count) in eventCounts)
{
    Console.WriteLine($"{eventType}: {count}");
}

Reference: KnowledgeBaseRetrievalClient

from collections import Counter

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes.models import (
    KnowledgeSourceResultsProcessing,
)
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalMinimalReasoningEffort,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalSemanticIntent,
    SearchIndexKnowledgeSourceParams,
)


client = KnowledgeBaseRetrievalClient(
    endpoint="<search-endpoint>",
    knowledge_base_name="<knowledge-base-name>",
    credential=DefaultAzureCredential(),
)

request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search="What is the return policy?"
        )
    ],
    output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
    retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
    include_activity=True,
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="<knowledge-source-name>",
            results_processing=KnowledgeSourceResultsProcessing.NONE,
            include_references=True,
        )
    ],
)

event_counts = Counter()

with client.retrieve_stream(request) as stream:
    for event in stream:
        event_counts[event.event_type] += 1

for event_type, count in event_counts.items():
    print(f"{event_type}: {count}")

Reference: KnowledgeBaseRetrievalClient

To opt in to streaming, include the Accept: text/event-stream header in a retrieve request. Without this header, the retrieve action returns its standard JSON response.

POST {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer {{search-access-token}}

{
    "intents": [
        {
            "type": "semantic",
            "search": "What is the return policy?"
        }
    ],
    "outputMode": "extractiveData",
    "retrievalReasoningEffort": {
        "kind": "minimal"
    },
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "{{knowledge-source-name}}",
            "kind": "searchIndex",
            "resultsProcessing": "none",
            "includeReferences": true
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

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

var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri("<search-endpoint>"),
    knowledgeBaseName: "<knowledge-base-name>",
    credential: new DefaultAzureCredential()
);

var retrievalRequest = new KnowledgeBaseRetrievalRequest();

retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "You are a support agent. Answer questions based on published documentation. "
                + "If you don't know the answer, say so."
            )
        }
    ) { Role = "assistant" }
);

retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "What is the process for submitting an expense report?"
            )
        }
    ) { Role = "user" }
);

// Apply a filter to search only published documents
var searchIndexParams = new SearchIndexKnowledgeSourceParams(
    knowledgeSourceName: "internal-documentation-ks"
);
searchIndexParams.FilterAddOn = "status eq 'published'";

retrievalRequest.KnowledgeSourceParams.Add(searchIndexParams);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

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

kb_client = KnowledgeBaseRetrievalClient(
    endpoint="<search-endpoint>",
    knowledge_base_name="<knowledge-base-name>",
    credential=DefaultAzureCredential(),
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="assistant",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="You are a support agent. Answer questions based on published documentation. "
                    "If you don't know the answer, say so."
                )
            ],
        ),
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="What is the process for submitting an expense report?"
                )
            ],
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="internal-documentation-ks",
            # Apply a filter to search only published documents
            filter_add_on="status eq 'published'",
        )
    ],
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

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": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "You are a support agent. Answer questions based on published documentation. If you don't know the answer, say so."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is the process for submitting an expense report?"
                }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "internal-documentation-ks",
            "kind": "searchIndex",
            "filterAddOn": "status eq 'published'"
        }
    ]
}

searchIndexParams.FilterAddOn = "(status eq 'published' or status eq 'internal') and created ge 2025-01-01";

filter_add_on="(status eq 'published' or status eq 'internal') and created ge 2025-01-01"

{
    "knowledgeSourceName": "internal-documentation-ks",
    "kind": "searchIndex",
    "filterAddOn": "(status eq 'published' or status eq 'internal') and created ge 2025-01-01"
}

using System;
using Azure.Identity;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var endpoint = new Uri("<search-endpoint>");
var retrievalClient = new KnowledgeBaseRetrievalClient(
    endpoint,
    "product-kb",
    new DefaultAzureCredential());

var languageBoost =
    new SearchIndexKnowledgeSourceFieldValueBoost(
        "language",
        2.0);
languageBoost.FieldValues.Add("ja-JP");
var queryHintOverrides =
    new SearchIndexKnowledgeSourceQueryHints();
queryHintOverrides.Boosts.Add(languageBoost);

var request = new KnowledgeBaseRetrievalRequest
{
    RetrievalReasoningEffort =
        new KnowledgeRetrievalLowReasoningEffort(),
    IncludeActivity = true
};
request.Messages.Add(
    new KnowledgeBaseMessage([
        new KnowledgeBaseMessageTextContent(
            "Find Japanese service guidance for Model-X200.")
    ])
    {
        Role = "user"
    });
request.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams(
        "product-docs-ks")
    {
        QueryHintOverrides = queryHintOverrides
    });

var result = await retrievalClient.RetrieveAsync(request);

Reference: KnowledgeBaseRetrievalClient, SearchIndexKnowledgeSourceParams

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes.models import (
    SearchIndexKnowledgeSourceFieldValueBoost,
    SearchIndexKnowledgeSourceQueryHints,
)
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalLowReasoningEffort,
    SearchIndexKnowledgeSourceParams,
)

retrieval_client = KnowledgeBaseRetrievalClient(
    endpoint="<search-endpoint>",
    credential=DefaultAzureCredential(),
    knowledge_base_name="product-kb",
)

query_hint_overrides = SearchIndexKnowledgeSourceQueryHints(
    boosts=[
        SearchIndexKnowledgeSourceFieldValueBoost(
            field="language",
            field_values=["ja-JP"],
            boost=2.0,
        )
    ]
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="Find Japanese service guidance for Model-X200."
                )
            ],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="product-docs-ks",
            query_hint_overrides=query_hint_overrides,
        )
    ],
    retrieval_reasoning_effort=(
        KnowledgeRetrievalLowReasoningEffort()
    ),
    include_activity=True,
)

result = retrieval_client.retrieve(request)

Reference: KnowledgeBaseRetrievalClient, SearchIndexKnowledgeSourceParams

POST {{search-endpoint}}/knowledgebases('product-kb')/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "messages": [{
    "role": "user",
    "content": [{
      "type": "text",
      "text": "Find Japanese service guidance for Model-X200."
    }]
  }],
  "knowledgeSourceParams": [{
    "knowledgeSourceName": "product-docs-ks",
    "kind": "searchIndex",
    "queryHintOverrides": {
      "boosts": [{
        "kind": "fieldValue",
        "field": "language",
        "fieldValues": ["ja-JP"],
        "boost": 2.0
      }]
    }
  }],
  "retrievalReasoningEffort": {"kind": "low"},
  "includeActivity": true
}

Reference: Knowledge Retrieval - Retrieve

In the .NET SDK, pass the token as the querySourceAuthorization parameter on RetrieveAsync:

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

// Service credential: Authenticates to the search service
var serviceCredential = new DefaultAzureCredential();

// User identity token: Represents the end user for document-level permissions filtering
var userTokenContext = new Azure.Core.TokenRequestContext(
    new[] { "https://search.azure.com/.default" }
);
string userToken = (await serviceCredential.GetTokenAsync(userTokenContext)).Token;

// Create the retrieval client with the service credential
var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri("<search-endpoint>"),
    knowledgeBaseName: "<knowledge-base-name>",
    credential: serviceCredential
);

var request = new KnowledgeBaseRetrievalRequest();
request.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "What companies are in the financial sector?")
        }
    ) { Role = "user" }
);

// Pass the user identity token for permissions filtering
var result = await kbClient.RetrieveAsync(
    request, querySourceAuthorization: userToken);

var text = (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text;
Console.WriteLine(text);

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

In the Python SDK, pass the token as the query_source_authorization parameter on retrieve:

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

# Service credential: Authenticates to the search service
service_credential = DefaultAzureCredential()

# User identity token: Represents the end user for document-level permissions filtering
user_token_provider = get_bearer_token_provider(
    service_credential, "https://search.azure.com/.default")
user_token = user_token_provider()

# Create the retrieval client with the service credential
kb_client = KnowledgeBaseRetrievalClient(
    endpoint="<search-endpoint>",
    knowledge_base_name="<knowledge-base-name>",
    credential=service_credential,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(
                text="What companies are in the financial sector?")],
        )
    ]
)

# Pass the user identity token for permissions filtering
result = kb_client.retrieve(
    retrieval_request=request, query_source_authorization=user_token)
print(result.response[0].content[0].text)

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

In the REST API, include the x-ms-query-source-authorization header with the user's access token:

@search-endpoint = <search-endpoint>
@search-access-token = <search-access-token> // Service credential
@user-access-token = <user-access-token> // User identity token

POST {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
x-ms-query-source-authorization: {{user-access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What companies are in the financial sector?"
                }
            ]
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using Azure.Core;
using Azure.Identity;

// citationUrl comes from a retrieve response
string citationUrl = "<citation-url>";

var credential = new DefaultAzureCredential();
AccessToken token = await credential.GetTokenAsync(
    new TokenRequestContext(
        new[] { "https://search.azure.com/.default" }));

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token.Token);

string document = await httpClient.GetStringAsync(citationUrl);
Console.WriteLine(document);

Reference: DefaultAzureCredential

import json
from urllib.request import Request, urlopen

from azure.identity import DefaultAzureCredential

# citation_url comes from a retrieve response
citation_url = "<citation-url>"

credential = DefaultAzureCredential()
token = credential.get_token("https://search.azure.com/.default")
document_request = Request(
    citation_url,
    headers={"Authorization": f"Bearer {token.token}"},
)
with urlopen(document_request) as response:
    document = json.load(response)

print(json.dumps(document, indent=2))

Reference: DefaultAzureCredential

GET {{citation-url}}
Authorization: Bearer {{search-access-token}}

Reference: Documents - Get

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

var kbClient = new KnowledgeBaseRetrievalClient(
    new Uri("<search-endpoint>"),
    "<knowledge-base-name>",
    new DefaultAzureCredential()
);

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[]
        {
            new KnowledgeBaseMessageTextContent(
                "Which policy applies to returns?"
            )
        }
    ) { Role = "user" }
);
retrievalRequest.IncludeActivity = true;
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams(
        "<knowledge-source-name>"
    )
    {
        ResultsProcessing = KnowledgeSourceResultsProcessing.None
    }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);
foreach (var activity in result.Value.Activity)
{
    KnowledgeBaseActivityRecordModel? model = activity switch
    {
        KnowledgeBaseModelQueryPlanningActivityRecord queryPlanning =>
            queryPlanning.Model,
        KnowledgeBaseModelAnswerSynthesisActivityRecord answerSynthesis =>
            answerSynthesis.Model,
        KnowledgeBaseModelWebSummarizationActivityRecord webSummarization =>
            webSummarization.Model,
        _ => null
    };

    if (model is not null)
    {
        Console.WriteLine(
            $"modelName={model.ModelName}, deploymentId={model.DeploymentId}");
    }
}

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import (
    KnowledgeBaseRetrievalClient,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseModelAnswerSynthesisActivityRecord,
    KnowledgeBaseModelQueryPlanningActivityRecord,
    KnowledgeBaseModelWebSummarizationActivityRecord,
    KnowledgeBaseRetrievalRequest,
    SearchIndexKnowledgeSourceParams,
)

kb_client = KnowledgeBaseRetrievalClient(
    "<search-endpoint>",
    DefaultAzureCredential(),
    knowledge_base_name="<knowledge-base-name>",
)

model_activity_types = (
    KnowledgeBaseModelQueryPlanningActivityRecord,
    KnowledgeBaseModelAnswerSynthesisActivityRecord,
    KnowledgeBaseModelWebSummarizationActivityRecord,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="Which policy applies to returns?"
                )
            ],
        )
    ],
    include_activity=True,
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="<knowledge-source-name>",
            results_processing="none",
        )
    ],
)

result = kb_client.retrieve(request)
for entry in result.activity or []:
    if isinstance(entry, model_activity_types) and entry.model:
        print(
            "modelName=", entry.model.model_name,
            "deploymentId=", entry.model.deployment_id,
        )

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

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

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "Which policy applies to returns?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "{{knowledge-source-name}}",
            "kind": "searchIndex",
            "resultsProcessing": "none"
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("Which HR policy applies?")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("hr-policy-ks")
    {
        FailOnError = true,
        AlwaysQuerySource = true
    }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("hr-faq-ks")
);

var result = await kbClient.RetrieveAsync(retrievalRequest);

Reference: SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="Which HR policy applies?")],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="hr-policy-ks",
            fail_on_error=True,
            always_query_source=True,
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="hr-faq-ks",
        ),
    ],
)

result = kb_client.retrieve(request)

Reference: SearchIndexKnowledgeSourceParams

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

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "Which HR policy applies?" }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "hr-policy-ks",
            "kind": "searchIndex",
            "failOnError": true,
            "alwaysQuerySource": true
        },
        {
            "knowledgeSourceName": "hr-faq-ks",
            "kind": "searchIndex"
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "Explain the official SSO provisioning steps.")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("product-docs-ks")
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("troubleshooting-ks")
    {
        NeverQuerySource = true
    }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);

Reference: SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="Explain the official SSO provisioning steps."
                )
            ],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="product-docs-ks",
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="troubleshooting-ks",
            never_query_source=True,
        ),
    ],
)

result = kb_client.retrieve(request)

Reference: SearchIndexKnowledgeSourceParams

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

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Explain the official SSO provisioning steps."
                }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "product-docs-ks",
            "kind": "searchIndex"
        },
        {
            "knowledgeSourceName": "troubleshooting-ks",
            "kind": "searchIndex",
            "neverQuerySource": true
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What safety procedures apply?")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("operations-ks")
    {
        MaxOutputDocuments = 50
    }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);

Reference: SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What safety procedures apply?")],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="operations-ks",
            max_output_documents=50,
        ),
    ],
)

result = kb_client.retrieve(request)

Reference: SearchIndexKnowledgeSourceParams

POST {{search-endpoint}}/knowledgebases/operations-kb/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What safety procedures apply?" }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "operations-ks",
            "kind": "searchIndex",
            "maxOutputDocuments": 50
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What is the return policy?")
        }
    ) { Role = "user" }
);
retrievalRequest.OutputMode = "extractedData";
retrievalRequest.MaxOutputDocuments = 3;
retrievalRequest.MaxOutputSizeInTokens = 6000;

var result = await kbClient.RetrieveAsync(retrievalRequest);

Reference: KnowledgeBaseRetrievalRequest

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What is the return policy?")],
        )
    ],
    output_mode="extractedData",
    max_output_documents=3,
    max_output_size_in_tokens=6000,
)

result = kb_client.retrieve(request)

Reference: KnowledgeBaseRetrievalRequest

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

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What is the return policy?" }
            ]
        }
    ],
    "outputMode": "extractedData",
    "maxOutputDocuments": 3,
    "maxOutputSizeInTokens": 6000
}

Reference: Knowledge Retrieval - Retrieve

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

string searchEndpoint = "<search-endpoint>";

var options = new SearchClientOptions(
    SearchClientOptions.ServiceVersion.V2026_08_01_Preview);
var kbClient = new KnowledgeBaseRetrievalClient(
    new Uri(searchEndpoint),
    "your-knowledge-base",
    new DefaultAzureCredential(),
    options);

KnowledgeBaseRetrievalRequest CreateRequest()
{
    var request = new KnowledgeBaseRetrievalRequest();
    request.Intents.Add(new KnowledgeRetrievalSemanticIntent(
        "Summarize the latest support guidance."));
    return request;
}

var inherited = await kbClient.RetrieveAsync(CreateRequest());
Console.WriteLine(
    $"Stored defaults: {inherited.Value.References.Count} references");

KnowledgeBaseRetrievalRequest overriddenRequest = CreateRequest();
overriddenRequest.MaxRuntimeInSeconds = 20;
overriddenRequest.MaxOutputDocuments = 1;
overriddenRequest.MaxOutputSize = 5000;

var overridden = await kbClient.RetrieveAsync(overriddenRequest);
Console.WriteLine(
    $"Request overrides: {overridden.Value.References.Count} references");

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalSemanticIntent,
)

kb_client = KnowledgeBaseRetrievalClient(
    endpoint="<search-endpoint>",
    knowledge_base_name="your-knowledge-base",
    credential=DefaultAzureCredential(),
    api_version="2026-08-01-preview",
)


def create_request(**limits):
    return KnowledgeBaseRetrievalRequest(
        intents=[
            KnowledgeRetrievalSemanticIntent(
                search="Summarize the latest support guidance.",
            )
        ],
        **limits,
    )


inherited = kb_client.retrieve(create_request())
print(f"Stored defaults: {len(inherited.references or [])} references")

overridden = kb_client.retrieve(
    create_request(
        max_runtime_in_seconds=20,
        max_output_documents=1,
        max_output_size=5000,
    )
)
print(f"Request overrides: {len(overridden.references or [])} references")

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

First, send a request that omits the three request-wide limit fields.

POST {{search-endpoint}}/knowledgebases/your-knowledge-base/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "intents": [
    {
      "type": "semantic",
      "search": "Summarize the latest support guidance."
    }
  ]
}

Next, override all three values for one request.

POST {{search-endpoint}}/knowledgebases/your-knowledge-base/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "intents": [
    {
      "type": "semantic",
      "search": "Summarize the latest support guidance."
    }
  ],
  "maxRuntimeInSeconds": 20,
  "maxOutputDocuments": 1,
  "maxOutputSize": 5000
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What companies are in the financial sector?")
        }
    ) { Role = "user" }
);
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
retrievalRequest.OutputMode = "answerSynthesis";
retrievalRequest.MaxRuntimeInSeconds = 30;
retrievalRequest.MaxOutputSizeInTokens = 6000;

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.search.documents.knowledgebases.models import (
    KnowledgeRetrievalLowReasoningEffort,
    KnowledgeRetrievalOutputMode,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What companies are in the financial sector?")],
        )
    ],
    retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
    output_mode=KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    max_runtime_in_seconds=30,
    max_output_size_in_tokens=6000,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

POST {{search-endpoint}}/knowledgebases/kb-override/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "retrievalReasoningEffort": { "kind": "low" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSizeInTokens": 6000
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What companies are in the financial sector?")
        }
    ) { Role = "user" }
);
retrievalRequest.IncludeActivity = true;
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("demo-financials-ks")
    {
        IncludeReferences = true,
        IncludeReferenceSourceData = true
    }
);

retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("demo-communicationservices-ks")
    {
        IncludeReferences = false,
        IncludeReferenceSourceData = false
    }
);

retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("demo-healthcare-ks")
    {
        IncludeReferences = true,
        IncludeReferenceSourceData = false,
        AlwaysQuerySource = true
    }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.search.documents.knowledgebases.models import SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What companies are in the financial sector?")],
        )
    ],
    include_activity=True,
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="demo-financials-ks",
            include_references=True,
            include_reference_source_data=True,
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="demo-communicationservices-ks",
            include_references=False,
            include_reference_source_data=False,
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="demo-healthcare-ks",
            include_references=True,
            include_reference_source_data=False,
            always_query_source=True,
        ),
    ],
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference: KnowledgeBaseRetrievalClient, SearchIndexKnowledgeSourceParams

POST {{search-endpoint}}/knowledgebases/kb-medium-example/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "demo-financials-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true
        },
        {
            "knowledgeSourceName": "demo-communicationservices-ks",
            "kind": "searchIndex",
            "includeReferences": false,
            "includeReferenceSourceData": false
        },
        {
            "knowledgeSourceName": "demo-healthcare-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": false,
            "alwaysQuerySource": true
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Intents.Add(
    new KnowledgeRetrievalSemanticIntent("what is a brokerage")
);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

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

request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search="what is a brokerage",
        )
    ]
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference: KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

POST {{search-endpoint}}/knowledgebases/kb-minimal/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "intents": [
        {
            "type": "semantic",
            "search": "what is a brokerage"
        }
    ]
}

Reference: Knowledge Retrieval - Retrieve

#pragma warning disable OPENAI001

using Azure.AI.OpenAI;
using Azure.Core;
using Azure.Identity;
using OpenAI.Responses;
using System;
using System.Collections.Generic;

string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!; // Example: https://<resource-name>.openai.azure.com
string mcpServerUrl = Environment.GetEnvironmentVariable("AZURE_SEARCH_MCP_ENDPOINT")!; // Example: https://<search-service-name>.search.windows.net/knowledgebases/<knowledge-base-name>/mcp?api-version=<api-version>
DefaultAzureCredential credential = new();

// Create the Azure OpenAI Responses client
AzureOpenAIClient azureClient = new(new Uri(openAiEndpoint), credential);
ResponsesClient openAIClient = azureClient.GetResponsesClient();

// Get a bearer token for Azure AI Search
string searchToken = credential.GetToken(
    new TokenRequestContext(new[] { "https://search.azure.com/.default" })
).Token;

// Configure the MCP tool for knowledge base retrieval
McpTool mcpTool = ResponseTool.CreateMcpTool(
    serverLabel: "search_kb",
    serverUri: new Uri(mcpServerUrl),
    headers: new Dictionary<string, string>
    {
        ["Authorization"] = $"Bearer {searchToken}",
    },
    allowedTools: new McpToolFilter { ToolNames = { "knowledge_base_retrieve" } },
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)
);

// Build the response request with the MCP tool attached
CreateResponseOptions options = new()
{
    Model = "MODEL_NAME",
    InputItems =
    {
        ResponseItem.CreateUserMessageItem(
            "What causes the strongest nighttime brightness patterns in this dataset?")
    },
    Tools = { mcpTool }
};

ResponseResult response = await openAIClient.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

Reference: Use the Azure OpenAI Responses API

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

openai_endpoint = os.environ["AZURE_OPENAI_ENDPOINT"] # Example: https://<resource-name>.openai.azure.com
mcp_server_url = os.environ["AZURE_SEARCH_MCP_ENDPOINT"] # Example: https://<search-service-name>.search.windows.net/knowledgebases/<knowledge-base-name>/mcp?api-version=<api-version>
credential = DefaultAzureCredential()

# Create token providers for Azure OpenAI and Azure AI Search
openai_token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)
search_token_provider = get_bearer_token_provider(
    credential, "https://search.azure.com/.default"
)

# Create the Azure OpenAI client
client = AzureOpenAI(
    azure_endpoint=openai_endpoint,
    azure_ad_token_provider=openai_token_provider,
    api_version=os.environ["OPENAI_API_VERSION"], # Example: 2025-04-01-preview
)

# Create a response using the MCP tool configuration
response = client.responses.create(
    model="MODEL_NAME",
    input="What causes the strongest nighttime brightness patterns in this dataset?",
    tools=[
        {
            "type": "mcp",
            "server_label": "search_kb",
            "server_url": mcp_server_url,
            "allowed_tools": ["knowledge_base_retrieve"],
            "headers": {
                "Authorization": f"Bearer {search_token_provider()}"
            },
            "require_approval": "never",
        }
    ],
)

print(response.output_text)

Reference: Use the Azure OpenAI Responses API

// This code snippet is currently unavailable.

#pragma warning disable OPENAI001

using OpenAI.Responses;
using System;
using System.Collections.Generic;

string mcpServerUrl = Environment.GetEnvironmentVariable("AZURE_SEARCH_MCP_ENDPOINT")!; // Example: https://<search-service-name>.search.windows.net/knowledgebases/<knowledge-base-name>/mcp?api-version=<api-version>
string searchAdminKey = Environment.GetEnvironmentVariable("AZURE_SEARCH_ADMIN_KEY")!; // Example: <search-api-key>

McpTool mcpTool = ResponseTool.CreateMcpTool(
    serverLabel: "search_kb",
    serverUri: new Uri(mcpServerUrl),
    headers: new Dictionary<string, string> { ["api-key"] = searchAdminKey },
    allowedTools: new McpToolFilter { ToolNames = { "knowledge_base_retrieve" } },
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)
);

Reference: Use the Azure OpenAI Responses API

import os

mcp_server_url = os.environ["AZURE_SEARCH_MCP_ENDPOINT"] # Example: https://<search-service-name>.search.windows.net/knowledgebases/<knowledge-base-name>/mcp?api-version=<api-version>
search_admin_key = os.environ["AZURE_SEARCH_ADMIN_KEY"] # Example: <search-api-key>

tools = [
    {
        "type": "mcp",
        "server_label": "search_kb",
        "server_url": mcp_server_url,
        "allowed_tools": ["knowledge_base_retrieve"],
        "headers": {"api-key": search_admin_key},
        "require_approval": "never",
    }
]

Reference: Use the Azure OpenAI Responses API

// This code snippet is currently unavailable.