@@ -1,7 +1,7 @@
 ---
 title: 'Tutorial: Build an Agentic Retrieval Solution'
 description: Build an agentic retrieval solution that connects Azure AI Search to Foundry Agent Service via MCP. Follow this tutorial to create a knowledge base and agent.
-ms.date: 07/20/2026
+ms.date: 08/06/2026
 ms.service: azure-ai-search
 ms.topic: tutorial
 ms.custom:
@@ -437,56 +437,73 @@ agent = project_client.agents.create_version(
 print(f"AI agent '{agent_name}' created or updated successfully")
 ```
 
-#### (Optional) Connect to a remote SharePoint knowledge source
+#### (Optional) Enforce permissions with per-request headers
 
-[!INCLUDE [foundry-iq-limitation](../foundry/includes/foundry-iq-limitation.md)]
+If any of your knowledge sources contain permission-protected content, the retrieval engine can filter results so that each user sees only the documents they're authorized to access. To enable this filtering, forward the signed-in user's identity token in the `x-ms-query-source-authorization` header of the MCP tool connection. Without the token, permission-enabled sources return results unfiltered. For more information, see [Enforce permissions at query time (preview)](agentic-retrieval-how-to-retrieve.md#enforce-permissions-at-query-time-preview).
 
-Optionally, if your knowledge base includes a remote SharePoint knowledge source, you must also include the `x-ms-query-source-authorization` header in the MCP tool connection. For more information, see [Enforce permissions at query time (preview)](agentic-retrieval-how-to-retrieve.md#enforce-permissions-at-query-time-preview).
+[!INCLUDE [vary-mcp-headers-per-request](../foundry/includes/vary-mcp-headers-per-request.md)]
 
-```python
-from azure.search.documents.indexes.models import RemoteSharePointKnowledgeSource, KnowledgeSourceReference
-from azure.search.documents.indexes import SearchIndexClient
-from azure.identity import get_bearer_token_provider
-
-remote_sp_ks = RemoteSharePointKnowledgeSource(
-    name="remote-sharepoint",
-    description="SharePoint knowledge source"
-)
-
-index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
-index_client.create_or_update_knowledge_source(knowledge_source=remote_sp_ks)
-print(f"Knowledge source '{remote_sp_ks.name}' created or updated successfully.")
-
-knowledge_base.knowledge_sources = [
-    KnowledgeSourceReference(name=remote_sp_ks.name), KnowledgeSourceReference(name=knowledge_source_name)
-]
+The following code updates the agent from the previous step so the MCP tool reads its authorization header from a structured input.
 
-index_client.create_or_update_knowledge_base(knowledge_base=knowledge_base)
-print(f"Knowledge base '{base_name}' updated with new knowledge source successfully")
+```python
+from azure.ai.projects.models import StructuredInputDefinition
 
+# Reference the token as a placeholder in the header
 mcp_kb_tool = MCPTool(
     server_label="knowledge-base",
     server_url=mcp_endpoint,
     require_approval="never",
     allowed_tools=["knowledge_base_retrieve"],
     project_connection_id=project_connection_name,
     headers={
-        "x-ms-query-source-authorization": get_bearer_token_provider(credential, "https://search.azure.com/.default")()
+        "x-ms-query-source-authorization": "{{search_auth_token}}"
     }
 )
 
+# Declare the structured input so the caller can supply the token per request
 agent = project_client.agents.create_version(
     agent_name=agent_name,
     definition=PromptAgentDefinition(
         model=agent_model,
         instructions=instructions,
-        tools=[mcp_kb_tool]
+        tools=[mcp_kb_tool],
+        structured_inputs={
+            "search_auth_token": StructuredInputDefinition(
+                description="Per-user Azure AI Search bearer token",
+                required=True,
+                schema={"type": "string"},
+            )
+        }
     )
 )
 
 print(f"AI agent '{agent_name}' created or updated successfully")
 ```
 
+When you invoke the agent, supply an Azure AI Search token in `structured_inputs`. This example resolves a token from the current `credential`. For a multi-user app, pass the token of each signed-in user instead. For example, use a token obtained through an on-behalf-of flow so the retrieval engine can filter results for that user.
+
+```python
+# Resolve an Azure AI Search token from the current credential (use a per-user token in production)
+from azure.identity import get_bearer_token_provider
+
+search_token = get_bearer_token_provider(credential, "https://search.azure.com/.default")()
+
+openai_client = project_client.get_openai_client()
+conversation = openai_client.conversations.create()
+
+response = openai_client.responses.create(
+    conversation=conversation.id,
+    tool_choice="required",
+    input="{user_query}",
+    extra_body={
+        "agent_reference": {"name": agent.name, "type": "agent_reference"},
+        "structured_inputs": {"search_auth_token": search_token},
+    },
+)
+
+print(f"Response: {response.output_text}")
+```
+
 ### Chat with the agent
 
 Your client app uses the Conversations and [Responses](/azure/ai-foundry/openai/how-to/responses) APIs from Azure OpenAI to interact with the agent.
@@ -507,7 +524,7 @@ response = openai_client.responses.create(
         Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
         Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
     """,
-    extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
+    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
 )
 
 print(f"Response: {response.output_text}")

@@ -23,8 +23,7 @@ This skill uses the machine learning models provided by [Azure Vision in Foundry
 
 Supported data sources for OCR and image analysis are blobs in Azure Blob Storage and Azure Data Lake Storage (ADLS) Gen2, and image content in Microsoft OneLake. Images can be standalone files or embedded images in a PDF or other files.
 
-This skill is implemented using the [AI Image Analysis API](/azure/ai-services/computer-vision/overview-image-analysis) version 3.2. If your solution requires calling a newer version of that service API (such as version 4.0), consider implementing through [Web API custom skill](cognitive-search-custom-skill-web-api.md) or use the [ImageAnalysisV4 power skill](https://github.com/Azure-Samples/azure-search-power-skills/blob/main/Vision/ImageAnalysisV4/README.md).
-
+This skill is implemented using the [AI Image Analysis API](/azure/ai-services/computer-vision/overview-image-analysis) version 3.2. If your solution requires calling a newer version of that service API, such as version 4.0, consider implementing through the [Custom Web API skill](cognitive-search-custom-skill-web-api.md).
 > [!NOTE]
 > This skill is bound to Foundry Tools and requires [a billable resource](cognitive-search-attach-cognitive-services.md) for transactions that exceed 20 documents per indexer per day. Execution of built-in skills is charged at the existing [Foundry Tools Standard price](https://azure.microsoft.com/pricing/details/cognitive-services/).
 >

@@ -5,11 +5,11 @@ ms.topic: include
 ms.service: azure-ai-search
 author: mattwojo
 ms.author: mattwoj
-ms.date: 06/02/2026
+ms.date: 08/10/2026
 ---
 
 > [!IMPORTANT]
 > The Serverless Developer tier is currently in 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](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).<br><br>
-> Billing for the Serverless Developer tier isn't yet enabled during the preview. Estimated costs for your usage are available in the Azure portal and telemetry, but that usage won't appear on your Azure bill during this initial period. Microsoft will provide at least 30 days notice before billing begins. The deferral of billing during this preview is temporary. Serverless Developer is a paid tier and you'll be responsible for any charges accrued once billing begins.<br><br>
+> Billing for the Serverless Developer tier begins on September 13, 2026. Charges for usage on or after that date appear on your Azure bill. You aren't charged for usage before September 13, 2026. Serverless Developer is a paid tier once billing begins.
 > The Serverless Developer tier doesn't support migration to or from other pricing tiers and some features available on other tiers aren't supported during Public Preview. Service limits, supported features, and pricing details may change before general availability.<br><br>
 > The preview is currently only available in West Central US, Switzerland North, and Japan East.
\ No newline at end of file

@@ -43,13 +43,13 @@ Before you create resources for a key-based connection, confirm regional support
 
 ## Choose a pricing model and tier
 
-Azure AI Search offers two pricing models: Dedicated and Serverless (Preview). For a free-trial account, you can evaluate Dedicated Free and Basic tiers, and you can also try the Serverless Developer tier at no charge during the initial preview period while reviewing estimated usage costs. Microsoft provides at least 30 days notice before Serverless Developer billing begins.
+Azure AI Search offers two pricing models: Dedicated and Serverless (Preview).
 
-+ **Free** doesn't consume credits and provides 50 MB of storage. You can have one free search service per Azure subscription. This tier is always free and doesn't expire, even after your 30-day trial ends. However, it doesn't support semantic ranking or managed identities for Microsoft Entra ID authentication and authorization, which are commonly used in quickstarts.
+- **Dedicated pricing model** - **Free tier** doesn't consume credits and provides 50 MB of storage. You can have one free search service per Azure subscription. This tier is always free and doesn't expire, even after your 30-day trial ends. However, it doesn't support semantic ranking or managed identities for Microsoft Entra ID authentication and authorization, which are commonly used in quickstarts.
 
-+ **Basic** (recommended) is in the Dedicated pricing model, consumes about one-third of your USD200 credits over 30 days, and provides 15 GB of storage in most regions. This tier supports all features, including semantic ranking and managed identities, and runs on dedicated infrastructure for consistent performance.
+- **Dedicated pricing model** - **Basic tier** (recommended) consumes about one-third of your USD200 credits over 30 days, and provides 15 GB of storage in most regions. This tier supports all features, including semantic ranking and managed identities, and runs on dedicated infrastructure for consistent performance.
 
-+ **Serverless Developer** (Preview) is in the Serverless pricing model and uses consumption-based pricing. During the initial preview period, you can evaluate estimated usage costs without billing. Microsoft provides at least 30 days notice before billing begins.
+- **Serverless pricing model** - **Serverless Developer tier** (Preview) uses consumption-based pricing. To evaluate usage costs in this tier, visit the [Azure portal](https://portal.azure.com) where you can view charges accrued once the billing period begins in the **Scale + Cost** tab.
 
 [!INCLUDE [Serverless preview](./includes/previews/preview-serverless.md)]
 

@@ -29,8 +29,24 @@ For more information about pricing model and service tier differences, see [Choo
 In the Serverless model, **performance optimization directly affects cost**. Cost is directly tied to workload execution:
 
 - Queries and indexing consume compute, measured in Compute Units per hour (CU/h).
-- Storage is billed separately based on index size on disk.
-- When the service is idle with no active queries or indexing, compute usage is zero. There's no reserved or minimum capacity charge.
+- Active indexes consume compute based on their resource usage and how long they remain active.
+- An index stays active for 10 minutes after its last query or indexing request before it goes inactive.
+- Inactive indexes have no minimum or reserved compute charge. The compute usage for inactive indexes scales to zero. There's no minimum compute charge when an index is inactive.
+- Storage is billed separately based on index size on disk and continues whether or not an index is in use.
+- Agentic retrieval consumes compute for each query executed against knowledge sources backed by Azure AI Search indexes, plus a separate orchestration charge for generating those queries and merging the results into a single response.
+
+Storage charges stop only when you delete the index.
+
+### How index size affects compute usage
+
+While an index is active, Azure AI Search evaluates two finite resources to determine its compute usage:
+
+- **Total index size**: The total space that the index occupies on disk, including text, metadata, and vectors.
+- **Vector index size**: The memory used by the [vector index](vector-search-index-size.md). Memory is more resource intensive than disk, so vector index size has a higher weighting when converted to CUs.
+
+Azure AI Search doesn't add the two resulting CU amounts together. Compute usage is based on whichever amount is higher. For example, vector index size can determine compute usage even when the total index size on disk is relatively small.
+
+To reduce active-index compute usage, identify which resource produces the higher CU amount. Then reduce total index size, vector index size, or both. Indexed storage remains a separate per-GB/month charge.
 
 The Serverless pricing model is most cost-effective for workloads with variable, intermittent, or unpredictable traffic, where provisioned capacity would be underutilized.
 
@@ -57,17 +73,17 @@ Different operations have different cost profiles:
 
 ### Monitor compute usage
 
-Monitoring compute consumption helps you identify expensive operations, optimize query patterns, and estimate costs. The Compute Unit (CU) cost of every request is returned in the `x-ms-request-charge` HTTP response header as a floating-point number. Use this header to identify expensive operations and optimize query patterns. You can track the CU cost of every request by inspecting the HTTP response headers and operation events in Azure Monitor. For more guidance on the types of monitoring data available and methods for analyzing that data, see [Monitor Azure AI Search](/azure/azure-monitor/fundamentals/overview).
+Monitoring compute consumption helps you identify expensive operations, optimize query patterns, and estimate costs. The Compute Unit (CU) cost of every request is returned in the `x-ms-azs-compute-units-consumed` HTTP response header as a floating-point number. Use this header to identify expensive operations and optimize query patterns. You can track the CU cost of every request by inspecting the HTTP response headers and operation events in Azure Monitor. For more guidance on the types of monitoring data available and methods for analyzing that data, see [Monitor Azure AI Search](/azure/azure-monitor/fundamentals/overview).
 
-- **Header**: `x-ms-request-charge: <value>`
+- **Header**: `x-ms-azs-compute-units-consumed: <value>`
 - **Value**: A floating-point number representing the CUs consumed.
 
 Example:
 
 ```http
 Status: 200 OK
 Content-Type: application/json
-x-ms-request-charge: 12.45
+x-ms-azs-compute-units-consumed: 12.45
 ```
 
 In this example, the request consumed 12.45 compute units. You can use this value to identify high-cost operations and compare the relative cost of different query patterns.
@@ -107,16 +123,20 @@ To estimate serverless costs:
 
 1. Index representative sample data.
 1. Run typical indexing and query workloads.
-1. Record the `x-ms-request-charge` value returned for each operation.
+1. Record the `x-ms-azs-compute-units-consumed` value returned for each operation.
 1. Use Azure Monitor metrics to measure aggregate usage over time.
 1. Extrapolate costs based on expected production traffic.
 
+Use the **Scale + Cost** tab in the Azure portal to see your current usage and estimate costs.
+
 Because the same request executed against the same data generally produces similar compute consumption, representative workloads can provide a reliable basis for cost estimation.
 
 Serverless usage is measured continuously and aggregated for billing. Compute consumption is tracked throughout each minute and emitted only when compute resources are used.
 
 When estimating costs, use request charge values to understand the cost of individual operations and Azure Monitor metrics to understand overall service consumption patterns.
 
+Use both data sources together to understand costs: per-request charge data helps you evaluate individual operations, while Azure Monitor metrics help you understand aggregate service consumption over time. For a complete cost picture, also account for features that are billed separately from Compute Units.
+
 Billing is based on aggregate compute usage rather than individual requests. Usage is measured in one-minute intervals and rounded up to the nearest 0.25 CU per minute. These one-minute usage intervals accumulate over the course of an hour to determine the billable CU/hour amount. Internally, usage aggregates from milli-compute units (mCU) to compute units (CU) and converts into the hourly usage reported for billing.
 
 Different operations consume different amounts of compute. In general:
@@ -150,16 +170,28 @@ How you send data to the index affects both cost and throughput:
 
 - **Index only new or changed data**: Avoid full reindexing when possible. Sending only additions and updates reduces the number of documents processed, lowering compute cost and improving ingestion speed.
 
-- **Use change detection for incremental indexing**: Detect what changed before you reprocess content. Incremental indexing avoids repeated work on unchanged documents and keeps reprocessing costs down.
-
 - **Skip image extraction unless you need it**: Image extraction adds extra processing work and can become a separate cost driver. Turn it on only for documents or workflows that actually need image content.
 
-- **Target skills to relevant fields and documents**: Scope enrichment skills to the specific fields or documents they need. Avoid running skills across content that doesn't need enrichment, especially when the outputs aren't used downstream.
-
 - **Account for index size growth**: Where possible, create smaller indexes. As an index grows, indexing costs increase because more data must be stored and maintained, and operations require more compute. For very large datasets, consider partitioning data across multiple indexes to help manage performance and costs. Although costs rise with index size, the increase is sublinear. Larger indexes cost more per operation, but not proportionally more.
 
 For more guidance, see [Tips for better performance in Azure AI Search](./search-performance-tips.md).
 
+### Optimize indexer operations
+
+Serverless indexer compute usage depends on the work performed during each indexer run. For row-oriented sources, use the number of documents processed as an indicator of workload volume. For file-based sources such as Azure Blob Storage and Azure Data Lake Storage Gen2, monitor the amount of source data processed. Actual compute usage also depends on document payloads, index structure, enrichment, and other processing performed during the run.
+
+To reduce indexer compute usage:
+
+- **Use change detection and incremental indexing**: Process only new or changed data instead of repeatedly indexing the full data source.
+
+- **Right-size indexer schedules**: Choose a schedule that meets your data freshness requirements. Use Compute Unit telemetry to evaluate the effect of schedule frequency.
+
+- **Reduce unnecessary document content**: Remove content that doesn't need to be indexed, and exclude files or file types that aren't required.
+
+- **Scope enrichment skills carefully**: Run skills only on fields and documents that require enrichment, and avoid generating outputs that aren't used downstream. Billable skills can incur separate transaction charges.
+
+- **Monitor failed and repeated runs**: An indexer can consume compute for work completed before it fails. Review execution history and Compute Unit usage to identify recurring failures and retry patterns.
+
 ### Optimize your queries
 
 Query design is a primary driver of variable cost:
@@ -208,6 +240,8 @@ Vector queries are compute-intensive because they require similarity calculation
 
 - **Use hybrid search selectively**: Hybrid queries run both keyword and vector retrieval. Use only when necessary for relevance.
 
+- **Tune `maxTextRecallSize` for hybrid queries**: Set `hybridSearch.maxTextRecallSize` to control how many BM25-ranked text results are available to Reciprocal Rank Fusion (RRF). The default is 1,000, and the supported range is 1 through 10,000. Lowering the value can reduce text retrieval and result-fusion work, which can reduce resource utilization and latency. However, it can exclude relevant keyword results, including exact terms, IDs, and acronyms that vector search might miss. Test representative queries, and compare relevance, latency, and the `x-ms-azs-compute-units-consumed` response header before selecting a value. Control vector candidates separately by setting `k` on each vector query.
+
 - **Apply filters before vector queries**: Narrow the candidate set before vector search to reduce the amount of data processed. See [How filtering works in vector queries](./vector-search-filters.md#how-filtering-works-in-vector-queries).
 
 ## Reduce costs by minimizing usage

@@ -185,10 +185,6 @@ Output for two consecutive chunks shows the text from the first chunk overlappin
 
 `'**Darkness is not void of illumination. It is the contrast, the area between light and **\ndark, that is often the most illustrative. Darkness reminds me of where I came from and where I am now-from a small town in the mountains, to the unique vantage point of the Nation's capital. Darkness is where dreamers and learners of all ages peer into the universe and think of questions about themselves and their space in the cosmos. Light is where they work, where they gather, and take time together.\nNASA's spacefaring satellites have compiled an unprecedented record of our \nEarth, and its luminescence in darkness, to captivate and spark curiosity. These missions see the contrast between dark and light through the lenses of scientific instruments. Our home planet is full of complex and dynamic cycles and processes. These soaring observers show us new ways to discern the nuances of light created by natural and human-made sources, such as auroras, wildfires, cities, phytoplankton, and volcanoes.' metadata={'source': './data/earth_at_night_508.pdf', 'page': 9}`
 
-### Custom skill
-
-A [fixed-sized chunking and embedding generation sample](https://github.com/Azure-Samples/azure-search-power-skills/blob/main/Vector/EmbeddingGenerator/README.md) demonstrates both chunking and vector embedding generation using [Azure OpenAI](/azure/ai-services/openai/) embedding models. This sample uses an [Azure AI Search custom skill](cognitive-search-custom-skill-web-api.md) in the [Power Skills repo](https://github.com/Azure-Samples/azure-search-power-skills/tree/main#readme) to wrap the chunking step.
-
 ## Related content
 
 - [Understand embeddings in Azure OpenAI in Foundry Models](/azure/ai-services/openai/concepts/understand-embeddings)

@@ -157,4 +157,3 @@ Keep the following considerations in mind when implementing a web API endpoint f
 + [Integrated vectorization](vector-search-integrated-vectorization.md)
 + [How to configure a vectorizer in a search index](vector-search-how-to-configure-vectorizer.md)
 + [Custom Web API skill](cognitive-search-custom-skill-web-api.md)
-+ [Hugging Face Embeddings Generator power skill (can be used for a custom web API vectorizer as well)](https://github.com/Azure-Samples/azure-search-power-skills/tree/main/Vector/EmbeddingGenerator)