Merge pull request #4728 from HeidiSteen/heidist-rb-rag

Updates to logic apps doc

Author: JamesJBarnett

articles/search/media/agentic-retrieval/agentic-retrieval-architecture.png

@@ -16,9 +16,9 @@ ms.date: 05/08/2025
 
 [!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
 
-In Azure AI Search, *agentic retrieval* is a new parallel query processing architecture that uses conversational language models to generate multiple subqueries for a single retrieval request, incorporating conversation history and semantic ranking to produce high-quality grounding data for custom chat and generative AI solutions.
+In Azure AI Search, *agentic retrieval* is a new parallel query processing architecture that uses conversational language models to generate multiple subqueries for a single retrieval request, incorporating conversation history and semantic ranking to produce high-quality grounding data for custom chat and generative AI solutions that include agents.
 
-Programmatically, agentic retrieval is supported through a new Agents object in the 2025-05-01-preview data plane REST API and in Azure SDK prerelease packages that provide the feature. An agent's retrieval response is designed for downstream consumption by other agents and chat apps based on generative AI.
+Programmatically, agentic retrieval is supported through a new Knowledge Agents object (also known as a search agent) in the 2025-05-01-preview data plane REST API and in Azure SDK prerelease packages that provide the feature. An agent's retrieval response is designed for downstream consumption by other agents and chat apps based on generative AI.
 
 ## Why use agentic retrieval
 
@@ -47,14 +47,15 @@ Agentic retrieval invokes the entire query processing pipeline multiple times fo
 
 ## Agentic retrieval architecture
 
-Agentic retrieval is designed for a conversational search experience that includes an LLM. An important part of agentic retrieval is that an entire chat conversation can be included as inputs in subsequent queries, providing context and nuance for more relevant responses.
+Agentic retrieval is designed for a conversational search experience that includes an LLM. An important part of agentic retrieval is how the LLM breaks down an initial query into subqueries, which are more effective at locating the best matches in your index.
+
+:::image type="content" source="media/agentic-retrieval/agentic-retrieval-architecture.png" alt-text="Diagram of agentic retrieval workflow using an example query." lightbox="media/agentic-retrieval/agentic-retrieval-architecture.png" :::
 
-<!-- Insert architecture diagram here -->
 Agentic retrieval has these components:
 
 | Component | Resource | Usage |
 |-----------|----------|-------|
-| LLM (gpt-4o and gpt-4.1 series) | Azure OpenAI | Formulates subqueries for the query plan. You can use these models for other downstream operations. Specifically, you can send the unified response string to one of these models and ask it ground its answer on the string. |
+| LLM (gpt-4o and gpt-4.1 series) | Azure OpenAI | An LLM has two functions. First, it formulates subqueries for the query plan and sends it back to the search agent. Second, after the query executes, the LLM receives grounding data from the query response and uses it for answer formulation. |
 | Search index | Azure AI Search | Contains plain text and vector content, a semantic configuration, and other elements as needed. |
 | Search agent | Azure AI Search | Connects to your LLM, providing parameters and inputs to build a query plan. |
 | Retrieval engine | Azure AI Search | Executes on the LLM-generated query plan and other parameters, returning a rich response that includes content and query plan metadata. Queries are keyword, vector, and hybrid. Results are merged and ranked. |
@@ -138,7 +139,7 @@ Putting it all together, you'd pay about $3.30 for semantic ranking in Azure AI
 
 ## How to get started
 
-You must use the REST APIs or a prerelease Azure SDK page that provides the functionality. At this time, there's no Azure portal or Azure AI Foundry portal support.
+You must use the preview REST APIs or a prerelease Azure SDK package that provides the functionality. At this time, there's no Azure portal or Azure AI Foundry portal support.
 
 Choose any of these options for your next step.
 

articles/search/media/logic-apps-connectors/logic-app-workflow.png

@@ -15,27 +15,50 @@ ms.date: 05/15/2025
 
 [!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
 
-Support for Logic Apps integration is now in public preview, available in the Azure portal [Quickstart wizard](search-get-started-portal-import-vectors.md) only.
+Support for Logic Apps integration is now in public preview, available in the Azure portal [Import and vectorize data wizard](search-get-started-portal-import-vectors.md) only. In Azure AI Search, a logic apps workflow is used for indexing and vectorization, and it's equivalent to an indexer and data source in Azure AI Search. 
 
-A Logic apps workflow is equivalent to an indexer in Azure AI Search, inclusive of both the data source and indexer definition. Logic Apps integration adds support for more data sources, and extends to Azure OpenAI models for vectorizing data during indexing.
+You can create a workflow in Azure AI Search using the Import and vectorize data wizard, and then manage the workflow in Logic Apps alongside your other workflows. Behind the scenes, the wizard follows a workflow template that pulls in (ingests) content from a source for indexing in AI Search. The connectors used in this scenario are prebuilt and already exist in Azure Logic Apps, so the workflow template just provides details for those connectors to create connections to the data source, AI Search, and other items to complete the ingestion workflow. 
 
-You can create a workflow in Azure AI Search using the Quickstart wizard, and then manage it in Logic Apps alongside your other workflows. Behind the scenes, the wizard follows a workflow template that pulls in (ingests) content from a source for indexing in AI Search. The connectors used in this scenario are prebuilt and already exist in Azure Logic Apps, so the workflow template just provides details for those connectors to create connections to the data source, AI Search, and other items to complete the ingestion workflow. 
-
-After you're done with the wizard, you've got a logic app resource and workflow that's live and running. You can view the running workflow, or you can open the designer in Azure Logic Apps to edit the workflow, as you regularly do if you'd started from Azure Logic Apps instead.
-
-Logic Apps workflows are a billable resource. For more information, see [Azure Logic Apps pricing](/azure/logic-apps/logic-apps-pricing).
+> [!NOTE]
+> Logic Apps workflows are a billable resource. For more information, see [Azure Logic Apps pricing](/azure/logic-apps/logic-apps-pricing).
 
 ## Key features
 
-The Quickstart wizard generates a Logic Apps template one each for on-demand or scheduled indexing, and a search index. This capability provides:
+Logic Apps integration in Azure AI Search adds support for:
 
-+ Support for more data sources
++ More data sources from Microsoft and other providers
 + Integrated vectorization
 + Scheduled or on-demand indexing
++ Change detection of new and existing documents
+
+Import and vectorize data wizard inputs include:
+
++ A supported data source
++ A supported text embedding model
+
+After the wizard completes, you have the following components:
+
+| Component | Location | Description |
+|-----------|----------|------------|
+| Search index | Azure AI Search | Contains indexed content from a supported Logic Apps connector. The index schema is a default index created by the wizard. You can add extra elements, such as scoring profile or semantic configuration, but you can't change existing fields. You view, manage, and access the search index on Azure AI Search. |
+| Logic app resource and workflow | Azure Logic Apps | You can view the running workflow, or you can open the designer in Azure Logic Apps to edit the workflow, as you regularly do if you'd started from Azure Logic Apps instead. You can edit and extend the workflow, but exercise caution so as to not break the indexing pipeline. |
+| Logic app templates | Azure Logic Apps | Up to two templates created per workflow: one for on-demand indexing, and a second template for scheduled indexing. You can modify the indexing schedule in the **Index multiple documents** step of the workflow. |
+
+## Prerequisites
+
+Review the following requirements before you start:
+
++ You must be an **Owner** or **Contributor** in your Azure subscription, with permissions to create resources.
+
++ Azure AI Search in a [supported region](#supported-regions), basic tier or higher if you want to use a search service identity for connections to an Azure data source, otherwise you can use any tier, subject to tier limits. 
 
-## Supported regions
++ Azure OpenAI, with a [supported embedding model](#supported-models) deployment. Vectorization is integrated into the workflow. If you don't need vectors, you can ignore the fields or try another indexing strategy.
 
-End-to-end functionality is available in the following regions, which provide the data source connection, document cracking, document chunks, support for Azure OpenAI embedding models, and the Azure AI indexer support for pulling the data:
++ Logic Apps should have a [system-assigned managed identity](/azure/logic-apps/authenticate-with-managed-identity) if you want to use Microsoft Entra ID authentication on connections rather than API keys.
+
+### Supported regions
+
+End-to-end functionality is available in the following regions, which provide the data source connection, document cracking, document chunks, support for Azure OpenAI embedding models, and the Azure AI indexer support for pulling the data.
 
 + Australia East
 + Brazil South
@@ -50,21 +73,91 @@ End-to-end functionality is available in the following regions, which provide th
 + West US 2
 + West US 3
 
+### Supported models
+
+Deploy one of the following [embedding models](/azure/ai-services/openai/concepts/models#embeddings) on Azure OpenAI.
+
++ text-embedding-3-small
++ text-embedding-3-large
++ text-embedding-ada-002
+
+### Supported connectors
+
+The following connectors are helpful for indexing unstructured data, as a complement to classic indexers that primarily target structured data. 
+
++ [SharePoint](/connectors/sharepointonline/)
++ [OneDrive](/connectors/onedrive/)
++ [OneDrive for Business](/connectors/onedriveforbusiness/)
++ [Azure File Storage](/connectors/azurefile/)
++ [Azure Queues](/connectors/azurequeues/)
++ [Service Bus](/connectors/servicebus/)
+
+## Limitations
+
+Currently, the public preview has these limitations:
+
++ The search index is generated using a fixed schema (document ID, content, and vectorized content), with text extraction only. You can [modify the index](#modify-existing-objects) as long as the update doesn't affect existing fields.
++ Vectorization supports text embedding only.
++ Deletion detection isn't supported. You must manually [delete orphaned documents](search-howto-reindex.md#delete-orphan-documents) from the index.
++ Duplicate documents in the search index are a known issue in this preview. Consider deleting objects and starting over if this becomes an issue.
+
 ## Create a Logic Apps workflow
 
 Follow these steps to create a Logic Apps workflow for indexing content in Azure AI Search.
 
-1. Start the Quickstart wizard in the Azure portal.
+1. Start the Import and vectorize data wizard in the Azure portal.
+
+1. Choose a [supported Logic Apps indexer](#supported-connectors).
+
+   :::image type="content" source="media/logic-apps-connectors/choose-data-source.png" alt-text="Screenshot of the chosen data source page in the Import and vectorize data wizard." lightbox="media/logic-apps-connectors/choose-data-source.png" :::
+
+1. In **Connect to your data**, provide a name prefix used for the search index and workflow. Having a common name helps you manage them together.
+
+1. Specify the indexing frequency. If you choose on a schedule, a template that includes a scheduling option is used to create the workflow. You can modify the indexing schedule in the **Index multiple documents** step of the workflow after it's created.
+
+1. Select an authentication type where the logic app workflow connects to the search engine and starts the indexing process. The workflow can connect using  [Azure AI Search API keys](search-security-api-keys.md) or the wizard can create a role assignment that grants permissions to the Logic Apps system-assigned managed identity, assuming one exists.
+
+1. Select **Next** to continue to the next page.
+
+1. In **Vectorize your text**, provide the model deployment and Azure OpenAI connection information. Choose the subscription and service, a [supported text embedding model](#supported-models), and the authentication type that the workflow uses to connect to Azure OpenAI.
 
-1. Choose a Logic Apps indexer.
+1. Select **Next** to continue to the next page. Review the configuration.
+ 
+1. Select **Create** to begin processing.
 
-   :::image type="content" source="media/logic-apps-connectors/choose-data-source.png" alt-text="Screenshot of the choose data source page in the Quickstart wizard." lightbox="media/logic-apps-connectors/choose-data-source.png" :::
+   The workflow runs as a serverless workflow in Logic Apps (Consumption), separate from the AI Search service.  
 
-## Template management
+1. Confirm index creation in the Azure portal, in the **Indexes** page in Azure AI Search. [Search Explorer](search-explorer.md) is the first tab. Select **Search** to return some content.
 
-Templates are created by the wizard when you specify a Logic Apps indexer. To create and manage templates, including template deletion, do this through Logic Apps. The Azure portal search service dashboard doesn't provide template management, and currently there's no programmatic support in Azure AI Search APIs.
+## Modify existing objects
+
+You can make the following modifications to a search index without breaking indexing:
+
++ [Add scoring profiles](index-add-scoring-profiles.md)
++ [Add semantic ranking](semantic-how-to-configure.md)
++ [Add spell check](speller-how-to-add.md)
++ [Add synonym maps](search-synonyms.md)
++ [Add suggesters](index-add-suggesters.md)
+
+You can make the following updates to a workflow without breaking indexing:
+
++ Modify **List files in folder** to change the number of documents sent to indexing.
++ Modify **Chunk Text** to vary token inputs. The recommended token size is 512 tokens for most scenarios.
++ Modify **Chunk Text** to add a page overlap length.
++ Modify **Index multiple documents** step to control indexing frequency if you chose scheduled indexing in the wizard.
+
+In logic apps designer, review the workflow and each step in the indexing pipeline. The workflow specifies document extraction, default document chunking ([Text Split skill](cognitive-search-skill-textsplit.md)), embedding ([Azure OpenAI embedding skill](cognitive-search-skill-azure-openai-embedding.md)), output field mappings, and finally indexing.
+
+:::image type="content" source="media/logic-apps-connectors/logic-app-workflow.png" alt-text="Screenshot of the workflow in logic app designer." lightbox="media/logic-apps-connectors/logic-app-workflow.png" :::
+
+## Template and workflow management
+
+The wizard creates templates and workflows when you specify a Logic Apps indexer. To create and manage them, including template deletion, use the logic app designer. The Azure portal search service dashboard doesn't provide template or workflow management, and currently there's no programmatic support in Azure AI Search APIs.
 
 ## Related content
 
 + [Indexers](search-indexer-overview.md)
 
++ [Connect to Azure AI services from workflows in Azure Logic Apps](/azure/logic-apps/connectors/azure-ai)
+
++ [Manage logic apps](/azure/logic-apps/manage-logic-apps-with-azure-portal)