Merge pull request #5107 from HeidiSteen/heidist-work

Edits based on MattG updates

Author: JillGrant615

articles/search/includes/quickstarts/agentic-retrieval-python.md

@@ -9,10 +9,12 @@ ms.date: 05/12/2025
 
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
 
-In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for integration with custom chat solutions.
+In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for integration with agentic and custom chat solutions.
 
 Although you can provide your own data, this quickstart uses [sample JSON documents](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/nasa-e-book/earth-at-night-json) from NASA's Earth at Night e-book. The documents describe general science topics and images of Earth at night as observed from space.
 
+This quickstart is based on the [Quickstart-Agentic-Retrieval](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/Quickstart-Agentic-Retrieval) Jupyter notebook on GitHub.
+
 ## Prerequisites
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
@@ -66,7 +68,7 @@ To configure the recommended role-based access:
 
 1. On your Azure AI Search service, [assign the following roles](../../search-security-rbac.md#how-to-assign-roles-in-the-azure-portal) to yourself.
 
-    + **Owner/Contributor** or **Search Service Contributor**
+    + **Search Service Contributor**
 
     + **Search Index Data Contributor**
 

articles/search/includes/quickstarts/agentic-retrieval-rest.md

@@ -279,9 +279,9 @@ POST {{baseUrl}}/indexes/{{index-name}}/docs/index?api-version={{api-version}}
     }
 ```
 
-## Create a search agent
+## Create a knowledge agent
 
-To connect Azure AI Search to your `gpt-4o-mini` deployment and target the `earth_at_night` index at query time, you need a search agent. Use [Create Knowledge Agents](/rest/api/searchservice/knowledge-agents/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to define an agent named `earth-search-agent`, which you specified using the `@agent-name` variable in a previous section.
+To connect Azure AI Search to your `gpt-4o-mini` deployment and target the `earth_at_night` index at query time, you need a knowledge agent. Use [Create Knowledge Agents](/rest/api/searchservice/knowledge-agents/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to define an agent named `earth-search-agent`, which you specified using the `@agent-name` variable in a previous section.
 
 To ensure relevant and semantically meaningful responses, `defaultRerankerThreshold` is set to exclude responses with a reranker score of `2.5` or lower.
 

articles/search/search-agentic-retrieval-how-to-pipeline.md

@@ -8,7 +8,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 05/10/2025
+ms.date: 05/21/2025
 ---
 
 # Build an agent-to-agent retrieval solution using Azure AI Search
@@ -19,30 +19,80 @@ This article describes an approach or pattern for building a solution that uses
 
 This article supports the [agentic-retrieval-pipeline-example](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/agentic-retrieval-pipeline-example) Python sample on GitHub.
 
-This exercise differs from the [Agentic Retrieval Quickstart](search-get-started-agentic-retrieval.md) in how it uses Azure AI Agent to determine whether to retrieve data from the index, and how it uses an agent tool for orchestration.
+This exercise differs from the [Agentic Retrieval Quickstart](search-get-started-agentic-retrieval.md) in how it uses Azure AI Agent to retrieve data from the index, and how it uses an agent tool for orchestration. If you want to understand the retrieval pipeline in its simplest form, begin with the quickstart.
 
 ## Prerequisites
 
 The following resources are required for this design pattern:
 
-+ Azure AI Search, basic tier or higher, in a [region that provides semantic ranker](search-region-support.md).
++ Azure AI Search, basic tier or higher, in a [region that provides semantic ranking](search-region-support.md).
 
 + A search index that satisfies the [index criteria for agentic retrieval](search-agentic-retrieval-how-to-index.md).
 
-+ Azure OpenAI, and you should have an **Azure AI Developer** role assignment to create a Foundry project.
++ A project in Azure AI Foundry, with an Azure AI Agent in a Basic setup.
 
-+ A project in Azure AI Foundry, with a deployment of a supported large language model and an Azure AI Agent in a basic setup. To meet this requirement, follow the steps in [Quickstart: Create a new agent (Preview)](/azure/ai-services/agents/quickstart?pivots=ai-foundry-portal). We recommend 100,000 token capacity for your model. You can find capacity and the rate limit in the model deployments list in the Azure AI Foundry portal.
+  Follow the steps in [Create a project for Azure AI Foundry](/azure/ai-foundry/how-to/create-projects). Creating the project also creates the Azure AI Foundry resource in your Azure subscription.
+
++ Azure OpenAI with a deployment of one of the chat completion models listed below. We recommend a minimum of 100,000 token capacity for your model. You can find capacity and the rate limit in the model deployments list in the Azure AI Foundry portal. You can also deploy text embedding models if you want [vectorization at query time](vector-search-integrated-vectorization.md#using-integrated-vectorization-in-queries).
 
 ### Supported large language models
 
-Use Azure OpenAI or an equivalent open source model:
+Use one of the following chat completion models with your AI agent:
 
 + `gpt-4o`
 + `gpt-4o-mini`
 + `gpt-4.1`
 + `gpt-4.1-nano`
 + `gpt-4.1-mini`
 
+### Package version requirements
+
+Use a package version that provides preview functionality. See the [`requirements.txt`](https://github.com/Azure-Samples/azure-search-python-samples/blob/main/agentic-retrieval-pipeline-example/requirements.txt) file for more packages used in the example solution.
+
+```
+azure-ai-projects==1.0.0b11
+azure-ai-agents==1.0.0
+azure-search-documents==11.6.0b12
+```
+
+### Configure access
+
+Before you begin, make sure you have permissions to access content and operations. We recommend Microsoft Entra ID authentication and role-based access for authorization. You must be an **Owner** or **User Access Administrator** to assign roles. If roles aren't feasible, you can use [key-based authentication](search-security-api-keys.md) instead.
+
+Configure access to each resource identified in this section.
+
+### [**Azure AI Search**](#tab/search-perms)
+
+Azure AI Search provides the agentic retrieval pipeline. Configure access for yourself, your app, and your search service for downstream access to models.
+
+1. [Enable role-based access](search-security-enable-roles.md).
+1. [Configure a managed identity](search-howto-managed-identities-data-sources.md).
+1. [Assign roles](search-security-rbac.md):
+
+   + For local testing, you must have **Search Service Contributor**, **Search Index Data Contributor**, and **Search Index Data Reader** role assignments to create, load, and retrieve on Azure AI Search.
+
+   + For integrated operations, ensure that all clients using the retrieval pipeline (agent and tool) have **Search Index Data Reader** role assignments for sending retrieval requests.
+
+### [**Azure AI Foundry**](#tab/foundry-perms)
+
+Azure AI Foundry hosts the AI agent and tool. Permissions are needed to create and use the resource.
+
++ You must be an **Owner** of your Azure subscription to create the project and resource.
+
++ For local testing, you must be an **Azure AI User** to access chat completion models deployed to the Foundry resource. This assignment is conferred automatically for **Owners** when you create the resource. Other users need a specific role assignment. For more information, see [Role-based access control in Azure AI Foundry portal](/azure/ai-foundry/concepts/rbac-azure-ai-foundry).
+
++ For integrated operations, ensure your [search service identity](search-howto-managed-identities-data-sources.md) has an **Azure AI User** role assignment on the Foundry resource.
+
+### [**Azure OpenAI**](#tab/openai-perms)
+
+Azure OpenAI hosts the models used by the agentic retrieval pipeline. Configure access for yourself and for the search service.
+
++ For local testing, ensure that you have a **Cognitive Services User** role assignment to access the chat completion model and embedding models (if using).
+
++ For integrated operations, ensure your [search service identity](search-howto-managed-identities-data-sources.md) has a **Cognitive Services User** role assignment for model access.
+
+---
+
 ## Development tasks
 
 Development tasks on the Azure AI Search side include:
@@ -55,25 +105,13 @@ Development tasks on the Azure AI Search side include:
 
 Your custom application makes API calls to Azure AI Search and an Azure SDK.
 
-+ External data from anywhere
-+ Azure AI Search, hosting indexed data and the agentic data retrieval engine
-+ Azure AI Foundry Model, providing a chat model (an LLM) for user interaction
-+ Azure SDK with a Foundry project, providing programmatic access to chat and chat history
-+ Azure AI Agent, with an agent for handling the conversation, and a tool for orchestration
-
-## How to customize grounding data
-
-Search results are consolidating into a large unified string that you can pass to a conversational language model for a grounded answer. The following indexing and relevance tuning features in Azure AI Search are available to help you generate high quality results:
++ External data from anywhere, although we recommend [data sources used for integrated indexing](search-data-sources-gallery.md).
++ Azure AI Search, hosting indexed data and the agentic data retrieval engine.
++ Azure AI Foundry, hosting the AI agent and tool.
++ Azure SDK with a Foundry project, providing programmatic access to Azure AI Foundry.
++ Azure OpenAI, hosting a chat completion model used by the knowledge agent and any embedding models used by vectorizers for vector search.
 
-+ Scoring profiles (added to your search index) provide built-in boosting criteria. Your index must specify a default scoring profile, and that's the one used by the retrieval engine when queries include fields associated with that profile.
-
-+ Semantic configuration is required, but you determine which fields are prioritized and used for ranking.
-
-+ For plain text content, you can use analyzers to control tokenization during indexing.
-
-+ For multimodal or image content, you can use image verbalization for LLM-generated descriptions of your images, or classic OCR and image analysis via skillsets during indexing.
-
-## Create the project
+## Set up your environment
 
 The canonical use case for agentic retrieval is through the Azure AI Agent service. We recommend it because it's the easiest way to create a chatbot.
 
@@ -85,29 +123,73 @@ You need endpoints for:
 + Azure OpenAI
 + Azure AI Foundry project
 
-You can find endpoints for Azure AI Search and Azure OpenAI in the [Azure portal](https://portal.azure.com).
+You can find endpoints for Azure AI Search and Azure OpenAI in the [Azure portal](https://portal.azure.com), in the **Overview** pages for each resource.
 
-You can find the project connection string in the Azure AI Foundry portal:
+You can find the project endpoint in the Azure AI Foundry portal:
 
 1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com) and open your project. 
 
-1. In the **Project details** tile, find and copy the **Project connection string**. 
-
-   A hypothetical connection string might look like this: `eastus2.api.azureml.ms;00000000-0000-0000-0000-0000000000;rg-my-resource-group-name;my-foundry-project-name`
+1. In the **Overview** tile, find and copy the Azure AI Foundry project endpoint.
 
-1. Check the authentication type for your Azure OpenAI resource and make sure it uses an API key shared to all projects. Still in **Project details**, expand the **Connected resources** tile to view the authentication type for your Azure OpenAI resource.
+   A hypothetical endpoint might look like this: `https://your-foundry-resource.services.ai.azure.com/api/projects/your-foundry-project`
 
 If you don't have an Azure OpenAI resource in your Foundry project, revisit the model deployment prerequisite. A connection to the resource is created when you deploy a model.
 
+### Set up an AI project client and create an agent
+
+Use [AIProjectClient](/python/api/azure-ai-projects/azure.ai.projects.aiprojectclient?view=azure-python-preview&preserve-view=true) to create your AI agent.
+
+```python
+from azure.ai.projects import AIProjectClient
+
+project_client = AIProjectClient(endpoint=project_endpoint, credential=credential)
+
+list(project_client.agents.list_agents())
+```
+
+Your agent is backed by a supported language model and instructions inform the agent of its scope.
+
+```python
+instructions = """
+A Q&A agent that can answer questions about the Earth at night.
+Sources have a JSON format with a ref_id that must be cited in the answer using the format [ref_id].
+If you do not have the answer, respond with "I don't know".
+"""
+agent = project_client.agents.create_agent(
+    model=agent_model,
+    name=agent_name,
+    instructions=instructions
+)
+
+print(f"AI agent '{agent_name}' created or updated successfully")
+```
+
 ### Add an agentic retrieval tool to AI Agent
 
 An end-to-end pipeline needs an orchestration mechanism for coordinating calls to the retriever and knowledge agent. You can use a [tool](/azure/ai-services/agents/how-to/tools/function-calling) for this task. The tool calls the Azure AI Search knowledge retrieval client and the Azure AI agent, and it drives the conversations with the user.
 
-## How to design a prompt
+```python
+from azure.ai.agents.models import FunctionTool, ToolSet, ListSortOrder
+
+from azure.search.documents.agent import KnowledgeAgentRetrievalClient
+from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, KnowledgeAgentIndexParams
 
-The prompt sent to the LLM includes instructions for working with the grounding data, which is passed as a large single string with no serialization or structure.
+agent_client = KnowledgeAgentRetrievalClient(endpoint=endpoint, agent_name=agent_name, credential=credential)
 
-The tool or function that you use to drive the pipeline provides the instructions to the LLM for the conversation.
+thread = project_client.agents.threads.create()
+retrieval_results = {}
+
+# AGENTIC RETRIEVAL DEFINITION DEFERRED TO NEXT SECTION
+
+functions = FunctionTool({ agentic_retrieval })
+toolset = ToolSet()
+toolset.add(functions)
+project_client.agents.enable_auto_function_calls(toolset)
+```
+
+## How to structure messages
+
+The messages sent to the agent tool include instructions for chat history and using the results obtained from [knowledge retrieval](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-05-01-preview&preserve-view=true) on Azure AI Search. The response is passed as a large single string with no serialization or structure.
 
 ```python
 def agentic_retrieval() -> str:
@@ -135,22 +217,17 @@ def agentic_retrieval() -> str:
     return retrieval_result.response[0].content[0].text
 ```
 
-To provide instructions used for building the query plan and the subqueries used to get the grounding data, set the message in the knowledge agent:
+## How to improve data quality
 
-```python
-project_client = AIProjectClient.from_connection_string(project_conn_str, credential=credential)
+Search results are consolidated into a large unified string that you can pass to a chat completion model for a grounded answer. The following indexing and relevance tuning features in Azure AI Search are available to help you generate high quality results. You can implement these features in the search index, and the improvements in search relevance are evident in the quality of the response returned during retrieval.
 
-instructions = """
-An Q&A agent that can answer questions about the Earth at night.
-Sources have a JSON format with a ref_id that must be cited in the answer.
-If you do not have the answer, respond with "I don't know".
-"""
-agent = project_client.agents.create_agent(
-    model=agent_model,
-    name=agent_name,
-    instructions=instructions
-)
-```
++ [Scoring profiles](index-add-scoring-profiles.md) (added to your search index) provide built-in boosting criteria. Your index must specify a default scoring profile, and that's the one used by the retrieval engine when queries include fields associated with that profile.
+
++ [Semantic configuration](semantic-how-to-configure.md) is required, but you determine which fields are prioritized and used for ranking.
+
++ For plain text content, you can use [analyzers](index-add-custom-analyzers.md) to control tokenization during indexing.
+
++ For [multimodal or image content](multimodal-search-overview.md), you can use image verbalization for LLM-generated descriptions of your images, or classic OCR and image analysis via skillsets during indexing.
 
 ## Control the number of subqueries
 
@@ -178,7 +255,7 @@ Look at output tokens in the [activity array](search-agentic-retrieval-how-to-re
 
 + Summarize message threads.
 
-+ Use `gpt mini`.
++ Use `gpt mini` or a smaller model that performs faster.
 
 + Set `maxOutputSize` in the [knowledge agent](search-agentic-retrieval-how-to-create.md) to govern the size of the response, or `maxRuntimeInSeconds` for time-bound processing.
 

articles/search/search-query-access-control-rbac-enforcement.md

@@ -43,7 +43,7 @@ The end-user application sends user permission as part of the search query reque
 
 Azure AI Search dynamically constructs security filters based on the user permissions provided. These security filters are automatically appended to any filters that might come in with the query if the index has the permission filter option enabled.
 
-For Azure RBAC, permissions are lists of resource ID strings, and there must be an Azure role assignment (Storage Blob Data Reader) on the data the source that grants access to the security principal token in the authorization header. The filter excludes documents if there's no role assignment for the principal behind the access token on the request.
+For Azure RBAC, permissions are lists of resource ID strings. There must be an Azure role assignment (Storage Blob Data Reader) on the data the source that grants access to the security principal token in the authorization header. The filter excludes documents if there's no role assignment for the principal behind the access token on the request.
 
 ### 3. Results filtering