Update docs and make mypy happy

Author: pamelafox

app/backend/approaches/approach.py

@@ -322,7 +322,8 @@ async def run_agentic_retrieval(
 
         # Create documents from reference source data
         for ref in refs:
-            if ref.source_data:
+            if ref.source_data and ref.doc_key:
+                # Note that ref.doc_key is the same as source_data["id"]
                 documents.append(
                     Document(
                         id=ref.source_data.get("id"),
@@ -337,7 +338,7 @@ async def run_agentic_retrieval(
                         search_agent_query=activity_mapping[ref.activity_source],
                     )
                 )
-                doc_to_ref_id[ref.source_data.get("id")] = ref.id
+                doc_to_ref_id[ref.doc_key] = ref.id
                 if top and len(documents) >= top:
                     break
 

docs/agentic_retrieval.md

@@ -1,28 +1,18 @@
 # RAG chat: Using agentic retrieval
 
-This repository includes an optional feature that uses agentic retrieval to find the most relevant content given a user's conversation history.
+This repository includes an optional feature that uses [agentic retrieval from Azure AI Search](https://learn.microsoft.com/azure/search/search-agentic-retrieval-concept) to find the most relevant content given a user's conversation history. The agentic retrieval feature uses a LLM to analyze the conversation and generate multiple search queries to find relevant content. This can improve the quality of the responses, especially for complex or multi-faceted questions.
 
-## Using the feature
-
-### Supported Models
-
-See the agentic retrieval documentation.
-
-### Prerequisites
-
-* A deployment of any of the supported agentic retrieval models in the [supported regions](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability). If you're not sure, try to create a gpt-4.1-mini deployment from your Azure OpenAI deployments page.
-
-### Deployment
+## Deployment
 
 1. **Enable agentic retrieval:**
 
-   Set the environment variables for your Azure OpenAI GPT deployments to your reasoning model
+   Set the azd environment variable to enable the agentic retrieval feature:
 
    ```shell
    azd env set USE_AGENTIC_RETRIEVAL true
    ```
 
-2. **(Optional) Set the agentic retrieval model**
+2. **(Optional) Customize the agentic retrieval model**
 
    You can configure which model agentic retrieval uses. By default, gpt-4.1-mini is used.
 
@@ -34,17 +24,19 @@ See the agentic retrieval documentation.
    azd env set AZURE_OPENAI_SEARCHAGENT_MODEL_VERSION 2025-04-14
    ```
 
+   You can only change it to one of the [supported models](https://learn.microsoft.com/azure/search/search-agentic-retrieval-how-to-create#supported-models).
+
 3. **Update the infrastructure and application:**
 
-   Execute `azd up` to provision the infrastructure changes (only the new model, if you ran `up` previously) and deploy the application code with the updated environment variables.
+   Execute `azd up` to provision the infrastructure changes (only the new model, if you ran `up` previously) and deploy the application code with the updated environment variables. The post-provision script will configure Azure AI Search with a Knowledge agent pointing at the search index.
 
 4. **Try out the feature:**
 
    Open the web app and start a new chat. Agentic retrieval will be used to find all sources.
 
 5. **Review the query plan**
 
-   Agentic retrieval use additional billed tokens behind the scenes for the planning process.
+   Agentic retrieval uses additional billed tokens behind the scenes for the planning process.
    To see the token usage, select the lightbulb icon on a chat answer. This will open the "Thought process" tab, which shows the amount of tokens used by and the queries produced by the planning process
 
    ![Thought process token usage](./images/query-plan.png)