chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use TextSearchProvider to add retrieval augmented generation (RAG) capabilities to an AI agent.
+// The sample uses an In-Memory vector store, which can easily be replaced with any other vector store that implements the Microsoft.Extensions.VectorData abstractions.
+// The TextSearchProvider runs a search against the vector store via the TextSearchStore before each model invocation and injects the results into the model context.
+// The TextSearchStore is a sample store implementation that hardcodes a storage schema and uses the vector store to store and retrieve documents.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Samples;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.InMemory;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+var embeddingDeploymentName = Environment.GetEnvironmentVariable("FOUNDRY_EMBEDDING_MODEL") ?? "text-embedding-3-large";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(
+    new Uri(endpoint),
+    new DefaultAzureCredential());
+
+// Create an In-Memory vector store that uses the Azure AI Foundry embedding model to generate embeddings.
+VectorStore vectorStore = new InMemoryVectorStore(new()
+{
+    EmbeddingGenerator = aiProjectClient.GetProjectOpenAIClient().GetEmbeddingClient(embeddingDeploymentName).AsIEmbeddingGenerator()
+});
+
+// Create a store that defines a storage schema, and uses the vector store to store and retrieve documents.
+TextSearchStore textSearchStore = new(vectorStore, "product-and-policy-info", 3072);
+
+// Upload sample documents into the store.
+await textSearchStore.UpsertDocumentsAsync(GetSampleDocuments());
+
+// Create an adapter function that the TextSearchProvider can use to run searches against the TextSearchStore.
+Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> SearchAdapter = async (text, ct) =>
+{
+    // Here we are limiting the search results to the single top result to demonstrate that we are accurately matching
+    // specific search results for each question, but in a real world case, more results should be used.
+    var searchResults = await textSearchStore.SearchAsync(text, 1, ct);
+    return searchResults.Select(r => new TextSearchProvider.TextSearchResult
+    {
+        SourceName = r.SourceName,
+        SourceLink = r.SourceLink,
+        Text = r.Text ?? string.Empty,
+        RawRepresentation = r
+    });
+};
+
+// Configure the options for the TextSearchProvider.
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+};
+
+// Create the AI agent with the TextSearchProvider as the AI context provider.
+AIAgent agent = aiProjectClient
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
+        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        // Since we are using ChatCompletion which stores chat history locally, we can also add a message filter
+        // that removes messages produced by the TextSearchProvider before they are added to the chat history, so that
+        // we don't bloat chat history with all the search result messages.
+        // By default the chat history provider will store all messages, except for those that came from chat history in the first place.
+        // We also want to maintain that exclusion here.
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+        {
+            StorageInputRequestMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
+        }),
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine(">> Asking about returns\n");
+Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));
+
+Console.WriteLine("\n>> Asking about shipping\n");
+Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", session));
+
+Console.WriteLine("\n>> Asking about product care\n");
+Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", session));
+
+// Produces some sample search documents.
+// Each one contains a source name and link, which the agent can use to cite sources in its responses.
+static IEnumerable<TextSearchDocument> GetSampleDocuments()
+{
+    yield return new TextSearchDocument
+    {
+        SourceId = "return-policy-001",
+        SourceName = "Contoso Outdoors Return Policy",
+        SourceLink = "https://contoso.com/policies/returns",
+        Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
+    };
+    yield return new TextSearchDocument
+    {
+        SourceId = "shipping-guide-001",
+        SourceName = "Contoso Outdoors Shipping Guide",
+        SourceLink = "https://contoso.com/help/shipping",
+        Text = "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout."
+    };
+    yield return new TextSearchDocument
+    {
+        SourceId = "tent-care-001",
+        SourceName = "TrailRunner Tent Care Instructions",
+        SourceLink = "https://contoso.com/manuals/trailrunner-tent",
+        Text = "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating."
+    };
+}
@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// Represents a document that can be used for Retrieval Augmented Generation (RAG) that stores textual data.
+/// </summary>
+public sealed class TextSearchDocument
+{
+    /// <summary>
+    /// Gets or sets an optional list of namespaces that the document should belong to.
+    /// </summary>
+    /// <remarks>
+    /// A namespace is a logical grouping of documents, e.g. may include a group id to scope the document to a specific group of users.
+    /// </remarks>
+    public IList<string> Namespaces { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the content as text.
+    /// </summary>
+    public string? Text { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional source ID for the document.
+    /// </summary>
+    /// <remarks>
+    /// This ID should be unique within the collection that the document is stored in, and can
+    /// be used to map back to the source artifact for this document.
+    /// If updates need to be made later or the source document was deleted and this document
+    /// also needs to be deleted, this id can be used to find the document again.
+    /// </remarks>
+    public string? SourceId { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional name for the source document.
+    /// </summary>
+    /// <remarks>
+    /// This can be used to provide display names for citation links when the document is referenced as
+    /// part of a response to a query.
+    /// </remarks>
+    public string? SourceName { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional link back to the source of the document.
+    /// </summary>
+    /// <remarks>
+    /// This can be used to provide citation links when the document is referenced as
+    /// part of a response to a query.
+    /// </remarks>
+    public string? SourceLink { get; set; }
+}
@@ -0,0 +1,388 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Linq.Expressions;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.VectorData;
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// A class that allows for easy storage and retrieval of documents in a Vector Store for Retrieval Augmented Generation (RAG).
+/// </summary>
+/// <remarks>
+/// <para>
+/// This class provides an opinionated schema for storing documents in a vector store. It is valuable for simple scenarios
+/// where you want to store text + embedding, or a reference to an external document + embedding without needing to customize the schema.
+/// If you want to control the schema yourself, use an implementation of <see cref="VectorStoreCollection{TKey, TRecord}"/> directly instead.
+/// </para>
+/// <para>
+/// This class and its related types are currently provided as a sample implementation, but may be promoted to a first-class supported API in future releases.
+/// </para>
+/// </remarks>
+public sealed partial class TextSearchStore : IDisposable
+{
+#if NET
+    [GeneratedRegex(@"\p{L}+", RegexOptions.IgnoreCase, "en-US")]
+    private static partial Regex AnyLanguageWordRegex();
+
+    private static readonly Func<string, ICollection<string>> s_defaultWordSegmenter = text => AnyLanguageWordRegex().Matches(text).Select(x => x.Value).ToList();
+#else
+    private static readonly Regex s_anyLanguageWordRegex = new(@"\p{L}+", RegexOptions.Compiled);
+    private static Regex AnyLanguageWordRegex() => s_anyLanguageWordRegex;
+
+    private static readonly Func<string, ICollection<string>> s_defaultWordSegmenter = text =>
+    {
+        List<string> words = new();
+        foreach (Match word in AnyLanguageWordRegex().Matches(text))
+        {
+            words.Add(word.Value);
+        }
+        return words;
+    };
+#endif
+
+    private readonly VectorStore _vectorStore;
+    private readonly TextSearchStoreOptions _options;
+    private readonly Func<string, ICollection<string>> _wordSegmenter;
+
+    private readonly VectorStoreCollection<object, Dictionary<string, object?>> _vectorStoreRecordCollection;
+    private readonly SemaphoreSlim _collectionInitializationLock = new(1, 1);
+    private bool _collectionInitialized;
+    private bool _disposedValue;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TextSearchStore"/> class.
+    /// </summary>
+    /// <param name="vectorStore">The vector store to store and read the memories from.</param>
+    /// <param name="collectionName">The name of the collection in the vector store to store and read the memories from.</param>
+    /// <param name="vectorDimensions">The number of dimensions to use for the memory embeddings.</param>
+    /// <param name="options">Options to configure the behavior of this class.</param>
+    /// <exception cref="NotSupportedException">Thrown if the key type provided is not supported.</exception>
+    public TextSearchStore(
+        VectorStore vectorStore,
+        string collectionName,
+        int vectorDimensions,
+        TextSearchStoreOptions? options = default)
+    {
+        // Verify
+        if (vectorStore is null)
+        {
+            throw new ArgumentNullException(nameof(vectorStore));
+        }
+
+        if (string.IsNullOrWhiteSpace(collectionName))
+        {
+            throw new ArgumentException("Collection name cannot be null or whitespace.", nameof(collectionName));
+        }
+
+        if (vectorDimensions < 1)
+        {
+            throw new ArgumentOutOfRangeException(nameof(vectorDimensions), "Vector dimensions must be greater than zero.");
+        }
+
+        if (options?.KeyType is not null && options.KeyType != typeof(string) && options.KeyType != typeof(Guid))
+        {
+            throw new NotSupportedException($"Unsupported key of type '{options.KeyType.Name}'");
+        }
+
+        if (options?.KeyType is not null && options.KeyType != typeof(string) && options?.UseSourceIdAsPrimaryKey is true)
+        {
+            throw new NotSupportedException($"The {nameof(TextSearchStoreOptions.UseSourceIdAsPrimaryKey)} option can only be used when the key type is 'string'.");
+        }
+
+        // Assign
+        this._vectorStore = vectorStore;
+        this._options = options ?? new TextSearchStoreOptions();
+        this._wordSegmenter = this._options.WordSegmenter ?? s_defaultWordSegmenter;
+
+        // Create a definition so that we can use the dimensions provided at runtime.
+        VectorStoreCollectionDefinition ragDocumentDefinition = new()
+        {
+            Properties =
+            [
+                new VectorStoreKeyProperty("Key", this._options.KeyType ?? typeof(string)),
+                new VectorStoreDataProperty("Namespaces", typeof(List<string>)) { IsIndexed = true },
+                new VectorStoreDataProperty("SourceId", typeof(string)) { IsIndexed = true },
+                new VectorStoreDataProperty("Text", typeof(string)) { IsFullTextIndexed = true },
+                new VectorStoreDataProperty("SourceName", typeof(string)),
+                new VectorStoreDataProperty("SourceLink", typeof(string)),
+                new VectorStoreVectorProperty("TextEmbedding", typeof(string), vectorDimensions),
+            ]
+        };
+
+        this._vectorStoreRecordCollection = this._vectorStore.GetDynamicCollection(collectionName, ragDocumentDefinition);
+    }
+
+    /// <summary>
+    /// Upserts a batch of text chunks into the vector store.
+    /// </summary>
+    /// <param name="textChunks">The text chunks to upload.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that completes when the documents have been upserted.</returns>
+    public async Task UpsertTextAsync(IEnumerable<string> textChunks, CancellationToken cancellationToken = default)
+    {
+        if (textChunks == null)
+        {
+            throw new ArgumentNullException(nameof(textChunks));
+        }
+
+        var vectorStoreRecordCollection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+
+        var storageDocuments = textChunks.Select(textChunk =>
+        {
+            // Without text we cannot generate a vector.
+            if (string.IsNullOrWhiteSpace(textChunk))
+            {
+                throw new ArgumentException("One of the provided text chunks is null.", nameof(textChunks));
+            }
+
+            return new Dictionary<string, object?>
+            {
+                { "Key", this.GenerateUniqueKey(null) },
+                { "Namespaces", new List<string>() },
+                { "Text", textChunk },
+                { "TextEmbedding", textChunk },
+            };
+        });
+
+        await vectorStoreRecordCollection.UpsertAsync(storageDocuments, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Upserts a batch of documents into the vector store.
+    /// </summary>
+    /// <param name="documents">The documents to upload.</param>
+    /// <param name="options">Optional options to control the upsert behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that completes when the documents have been upserted.</returns>
+    public async Task UpsertDocumentsAsync(IEnumerable<TextSearchDocument> documents, TextSearchStoreUpsertOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        if (documents is null)
+        {
+            throw new ArgumentNullException(nameof(documents));
+        }
+
+        var vectorStoreRecordCollection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+
+        var storageDocuments = documents.Select(document =>
+        {
+            if (document is null)
+            {
+                throw new ArgumentNullException(nameof(documents), "One of the provided documents is null.");
+            }
+
+            // Without text we cannot generate a vector.
+            if (string.IsNullOrWhiteSpace(document.Text))
+            {
+                throw new ArgumentException($"The {nameof(TextSearchDocument.Text)} property must be set.", nameof(document));
+            }
+
+            // If we aren't persisting the text, we need a source id or link to refer back to the original document.
+            if (options?.DoNotPersistSourceText is true && string.IsNullOrWhiteSpace(document.SourceId) && string.IsNullOrWhiteSpace(document.SourceLink))
+            {
+                throw new ArgumentException($"Either the {nameof(TextSearchDocument.SourceId)} or {nameof(TextSearchDocument.SourceLink)} properties must be set when the {nameof(TextSearchStoreUpsertOptions.DoNotPersistSourceText)} setting is true.", nameof(document));
+            }
+
+            var key = this.GenerateUniqueKey(this._options.UseSourceIdAsPrimaryKey ?? false ? document.SourceId : null);
+
+            return new Dictionary<string, object?>()
+            {
+                { "Key", key },
+                { "Namespaces", document.Namespaces.ToList() },
+                { "SourceId", document.SourceId },
+                { "Text", options?.DoNotPersistSourceText is true ? null : document.Text },
+                { "SourceName", document.SourceName },
+                { "SourceLink", document.SourceLink },
+                { "TextEmbedding", document.Text },
+            };
+        });
+
+        await vectorStoreRecordCollection.UpsertAsync(storageDocuments, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Search the database for documents similar to the provided query.
+    /// </summary>
+    /// <param name="query">The text query to find similar documents to.</param>
+    /// <param name="top">The maximum number of results to return.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The search results.</returns>
+    public async Task<IEnumerable<TextSearchDocument>> SearchAsync(string query, int top, CancellationToken cancellationToken = default)
+    {
+        var searchResult = await this.SearchCoreAsync(query, top, cancellationToken).ConfigureAwait(false);
+
+        return searchResult.Select(x => new TextSearchDocument()
+        {
+            Namespaces = (List<string>)x["Namespaces"]!,
+            Text = (string?)x["Text"],
+            SourceId = (string?)x["SourceId"],
+            SourceName = (string?)x["SourceName"],
+            SourceLink = (string?)x["SourceLink"],
+        });
+    }
+
+    /// <summary>
+    /// Internal search implementation with hydration of id / link only storage.
+    /// </summary>
+    /// <param name="query">The text query to find similar documents to.</param>
+    /// <param name="top">The maximum number of results to return.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The search results.</returns>
+    private async Task<IEnumerable<Dictionary<string, object?>>> SearchCoreAsync(string query, int top, CancellationToken cancellationToken = default)
+    {
+        // Short circuit if the query is empty.
+        if (string.IsNullOrWhiteSpace(query))
+        {
+            return [];
+        }
+
+        var vectorStoreRecordCollection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+
+        // If the user has not opted out of hybrid search, check if the vector store supports it.
+        var hybridSearchCollection = this._options.UseHybridSearch ?? true ?
+            vectorStoreRecordCollection.GetService(typeof(IKeywordHybridSearchable<Dictionary<string, object?>>)) as IKeywordHybridSearchable<Dictionary<string, object?>> :
+            null;
+
+        // Optional filter to limit the search to a specific namespace.
+        Expression<Func<Dictionary<string, object?>, bool>>? filter = string.IsNullOrWhiteSpace(this._options.SearchNamespace) ? null : x => ((List<string>)x["Namespaces"]!).Contains(this._options.SearchNamespace);
+
+        // Execute a hybrid search if possible, otherwise perform a regular vector search.
+        var searchResult = hybridSearchCollection is null
+            ? vectorStoreRecordCollection.SearchAsync(
+                query,
+                top,
+                options: new()
+                {
+                    Filter = filter,
+                },
+                cancellationToken: cancellationToken)
+            : hybridSearchCollection.HybridSearchAsync(
+                query,
+                this._wordSegmenter(query),
+                top,
+                options: new()
+                {
+                    Filter = filter,
+                },
+                cancellationToken: cancellationToken);
+
+        // Retrieve the documents from the search results.
+        List<Dictionary<string, object?>> searchResponseDocs = [];
+        await foreach (var searchResponseDoc in searchResult.WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            searchResponseDocs.Add(searchResponseDoc.Record);
+        }
+
+        // Find any source ids and links for which the text needs to be retrieved.
+        var sourceIdsToRetrieve = searchResponseDocs
+            .Where(x => string.IsNullOrWhiteSpace((string?)x["Text"]))
+            .Select(x => new TextSearchStoreOptions.SourceRetrievalRequest((string?)x["SourceId"], (string?)x["SourceLink"]))
+            .ToList();
+
+        // If we have none, we can return early.
+        if (sourceIdsToRetrieve.Count == 0)
+        {
+            return searchResponseDocs;
+        }
+
+        if (this._options.SourceRetrievalCallback is null)
+        {
+            throw new InvalidOperationException($"The {nameof(TextSearchStoreOptions.SourceRetrievalCallback)} option must be set if retrieving documents without stored text.");
+        }
+
+        // Retrieve the source text for the documents that need it.
+        var retrievalResponses = await this._options.SourceRetrievalCallback(sourceIdsToRetrieve).ConfigureAwait(false) ??
+            throw new InvalidOperationException($"The {nameof(TextSearchStoreOptions.SourceRetrievalCallback)} must return a non-null value.");
+
+        // Update the retrieved documents with the retrieved text.
+        return searchResponseDocs.GroupJoin(
+            retrievalResponses,
+            searchResponseDoc => (searchResponseDoc["SourceId"], searchResponseDoc["SourceLink"]),
+            retrievalResponse => (retrievalResponse.SourceId, retrievalResponse.SourceLink),
+            (searchResponseDoc, textRetrievalResponse) => (searchResponseDoc, textRetrievalResponse))
+            .SelectMany(
+                joinedSet => joinedSet.textRetrievalResponse.DefaultIfEmpty(),
+                (combined, textRetrievalResponse) =>
+                {
+                    combined.searchResponseDoc["Text"] = textRetrievalResponse?.Text ?? combined.searchResponseDoc["Text"];
+                    return combined.searchResponseDoc;
+                });
+    }
+
+    /// <summary>
+    /// Thread safe method to get the collection and ensure that it is created at least once.
+    /// </summary>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The created collection.</returns>
+    private async Task<VectorStoreCollection<object, Dictionary<string, object?>>> EnsureCollectionExistsAsync(CancellationToken cancellationToken)
+    {
+        // Return immediately if the collection is already created, no need to do any locking in this case.
+        if (this._collectionInitialized)
+        {
+            return this._vectorStoreRecordCollection;
+        }
+
+        // Wait on a lock to ensure that only one thread can create the collection.
+        await this._collectionInitializationLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+
+        // If multiple threads waited on the lock, and the first already created the collection,
+        // we can return immediately without doing any work in subsequent threads.
+        if (this._collectionInitialized)
+        {
+            this._collectionInitializationLock.Release();
+            return this._vectorStoreRecordCollection;
+        }
+
+        // Only the winning thread should reach this point and create the collection.
+        try
+        {
+            await this._vectorStoreRecordCollection.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+            this._collectionInitialized = true;
+        }
+        finally
+        {
+            this._collectionInitializationLock.Release();
+        }
+
+        return this._vectorStoreRecordCollection;
+    }
+
+    /// <summary>
+    /// Generates a unique key for the RAG document.
+    /// </summary>
+    /// <param name="sourceId">Source id of the source document for this RAG document.</param>
+    /// <returns>A new unique key.</returns>
+    /// <exception cref="NotSupportedException">Thrown if the requested key type is not supported.</exception>
+    private object GenerateUniqueKey(string? sourceId)
+        => this._options.KeyType switch
+        {
+            _ when (this._options.KeyType == null || this._options.KeyType == typeof(string)) && !string.IsNullOrWhiteSpace(sourceId) => sourceId!,
+            _ when this._options.KeyType == null || this._options.KeyType == typeof(string) => Guid.NewGuid().ToString(),
+            _ when this._options.KeyType == typeof(Guid) => Guid.NewGuid(),
+
+            _ => throw new NotSupportedException($"Unsupported key of type '{this._options.KeyType.Name}'")
+        };
+
+    /// <inheritdoc/>
+    private void Dispose(bool disposing)
+    {
+        if (!this._disposedValue)
+        {
+            if (disposing)
+            {
+                this._vectorStoreRecordCollection.Dispose();
+                this._collectionInitializationLock.Dispose();
+            }
+
+            this._disposedValue = true;
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
+        this.Dispose(disposing: true);
+        GC.SuppressFinalize(this);
+    }
+}
@@ -0,0 +1,133 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// Contains options for the <see cref="TextSearchStore"/>.
+/// </summary>
+public sealed class TextSearchStoreOptions
+{
+    /// <summary>
+    /// Gets or sets an optional namespace to pre-filter the possible
+    /// records with when doing a vector search.
+    /// </summary>
+    public string? SearchNamespace { get; init; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to use the source ID as the primary key for records.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Using the source ID as the primary key allows for easy updates from the source for any changed
+    /// records, since those records can just be upserted again, and will overwrite the previous version
+    /// of the same record.
+    /// </para>
+    /// <para>
+    /// This setting can only be used when the chosen key type is a string.
+    /// </para>
+    /// </remarks>
+    /// <value>
+    /// Defaults to <c>false</c> if not set.
+    /// </value>
+    public bool? UseSourceIdAsPrimaryKey { get; init; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to use hybrid search if it is available for the provided vector store.
+    /// </summary>
+    /// <value>
+    /// Defaults to <c>true</c> if not set.
+    /// </value>
+    public bool? UseHybridSearch { get; init; }
+
+    /// <summary>
+    /// Gets or sets a word segmenter function to split search text into separate words for the purposes of hybrid search.
+    /// This will not be used if <see cref="UseHybridSearch"/> is set to <c>false</c>.
+    /// </summary>
+    /// <remarks>
+    /// Defaults to a simple text-character-based segmenter that splits the text by any character that is not a text character.
+    /// </remarks>
+    public Func<string, ICollection<string>>? WordSegmenter { get; init; }
+
+    /// <summary>
+    /// Gets or sets the type of key to use for records in the text search store.
+    /// </summary>
+    /// <remarks>
+    /// Make sure to pick a key type that is supported by the underlying vector store.
+    /// Note that you have to choose <see cref="string"/> when using <see cref="UseSourceIdAsPrimaryKey"/>.
+    /// </remarks>
+    /// <value>Defaults to <see cref="string"/> if not set. Only <see cref="string"/> and <see cref="Guid"/> is currently supported.</value>
+    public Type? KeyType { get; init; }
+
+    /// <summary>
+    /// Gets or sets an optional callback to load the source text using the source id or source link
+    /// if the source text is not persisted in the database.
+    /// </summary>
+    /// <remarks>
+    /// The response should include the source id or source link, as provided in the request,
+    /// plus the source text loaded from the source.
+    /// </remarks>
+    public Func<List<SourceRetrievalRequest>, Task<IEnumerable<SourceRetrievalResponse>>>? SourceRetrievalCallback { get; init; }
+
+    /// <summary>
+    /// Represents a request to the <see cref="SourceRetrievalCallback"/>.
+    /// </summary>
+    public sealed class SourceRetrievalRequest
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SourceRetrievalRequest"/> class.
+        /// </summary>
+        /// <param name="sourceId">The source ID of the document to retrieve.</param>
+        /// <param name="sourceLink">The source link of the document to retrieve.</param>
+        public SourceRetrievalRequest(string? sourceId, string? sourceLink)
+        {
+            this.SourceId = sourceId;
+            this.SourceLink = sourceLink;
+        }
+
+        /// <summary>
+        /// Gets or sets the source ID of the document to retrieve.
+        /// </summary>
+        public string? SourceId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the source link of the document to retrieve.
+        /// </summary>
+        public string? SourceLink { get; set; }
+    }
+
+    /// <summary>
+    /// Represents a response from the <see cref="SourceRetrievalCallback"/>.
+    /// </summary>
+    public sealed class SourceRetrievalResponse
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SourceRetrievalResponse"/> class.
+        /// </summary>
+        /// <param name="request">The request matching this response.</param>
+        /// <param name="text">The source text that was retrieved.</param>
+        public SourceRetrievalResponse(SourceRetrievalRequest request, string text)
+        {
+            ArgumentNullException.ThrowIfNull(request);
+            ArgumentNullException.ThrowIfNull(text);
+
+            this.SourceId = request.SourceId;
+            this.SourceLink = request.SourceLink;
+            this.Text = text;
+        }
+
+        /// <summary>
+        /// Gets or sets the source ID of the document that was retrieved.
+        /// </summary>
+        public string? SourceId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the source link of the document that was retrieved.
+        /// </summary>
+        public string? SourceLink { get; set; }
+
+        /// <summary>
+        /// Gets or sets the source text of the document that was retrieved.
+        /// </summary>
+        public string Text { get; set; }
+    }
+}
@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// Contains options for <see cref="TextSearchStore.UpsertDocumentsAsync(IEnumerable{TextSearchDocument}, TextSearchStoreUpsertOptions?, CancellationToken)"/>.
+/// </summary>
+public sealed class TextSearchStoreUpsertOptions
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether the source text should be persisted in the database.
+    /// </summary>
+    /// <value>
+    /// Defaults to <see langword="false"/> if not set.
+    /// </value>
+    public bool DoNotPersistSourceText { get; init; }
+}
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.SemanticKernel.Connectors.Qdrant" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,139 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use Qdrant with a custom schema to add retrieval augmented generation (RAG) capabilities to an AI agent.
+// While the sample is using Qdrant, it can easily be replaced with any other vector store that implements the Microsoft.Extensions.VectorData abstractions.
+// The TextSearchProvider runs a search against the vector store before each model invocation and injects the results into the model context.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.Qdrant;
+using Qdrant.Client;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+var embeddingDeploymentName = Environment.GetEnvironmentVariable("FOUNDRY_EMBEDDING_MODEL") ?? "text-embedding-3-large";
+var afOverviewUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/overview/index.md";
+var afMigrationUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/migration-guide/from-semantic-kernel/index.md";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(
+    new Uri(endpoint),
+    new DefaultAzureCredential());
+
+// Create a Qdrant vector store that uses the Azure AI Foundry embedding model to generate embeddings.
+QdrantClient client = new("localhost");
+VectorStore vectorStore = new QdrantVectorStore(client, ownsClient: true, new()
+{
+    EmbeddingGenerator = aiProjectClient.GetProjectOpenAIClient().GetEmbeddingClient(embeddingDeploymentName).AsIEmbeddingGenerator()
+});
+
+// Create a collection and upsert some text into it.
+var documentationCollection = vectorStore.GetCollection<Guid, DocumentationChunk>("documentation");
+await documentationCollection.EnsureCollectionDeletedAsync(); // Clear out any data from previous runs.
+await documentationCollection.EnsureCollectionExistsAsync();
+await UploadDataFromMarkdown(afOverviewUrl, "Microsoft Agent Framework Overview", documentationCollection, 2000, 200);
+await UploadDataFromMarkdown(afMigrationUrl, "Semantic Kernel to Microsoft Agent Framework Migration Guide", documentationCollection, 2000, 200);
+
+// Create an adapter function that the TextSearchProvider can use to run searches against the collection.
+Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> SearchAdapter = async (text, ct) =>
+{
+    List<TextSearchProvider.TextSearchResult> results = [];
+    await foreach (var result in documentationCollection.SearchAsync(text, 5, cancellationToken: ct))
+    {
+        results.Add(new TextSearchProvider.TextSearchResult
+        {
+            SourceName = result.Record.SourceName,
+            SourceLink = result.Record.SourceLink,
+            Text = result.Record.Text ?? string.Empty,
+            RawRepresentation = result
+        });
+    }
+    return results;
+};
+
+// Configure the options for the TextSearchProvider.
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    // Use up to 5 recent messages when searching so that searches
+    // still produce valuable results even when the user is referring
+    // back to previous messages in their request.
+    RecentMessageMemoryLimit = 5
+};
+
+// Create the AI agent with the TextSearchProvider as the AI context provider.
+AIAgent agent = aiProjectClient
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
+        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        // Configure a filter on the InMemoryChatHistoryProvider so that we don't persist the messages produced by the TextSearchProvider in chat history.
+        // The default is to persist all messages except those that came from chat history in the first place.
+        // You may choose to persist the TextSearchProvider messages, if you want the search output to be provided to the model in future interactions as well.
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions()
+        {
+            StorageInputRequestMessageFilter = msgs => msgs.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider)
+        })
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine(">> Asking about SK sessions\n");
+Console.WriteLine(await agent.RunAsync("Hi! How do I create a thread/session in Semantic Kernel?", session));
+
+// Here we are asking a very vague question when taken out of context,
+// but since we are including previous messages in our search using RecentMessageMemoryLimit
+// the RAG search should still produce useful results.
+Console.WriteLine("\n>> Asking about AF sessions\n");
+Console.WriteLine(await agent.RunAsync("and in Agent Framework?", session));
+
+Console.WriteLine("\n>> Contrasting Approaches\n");
+Console.WriteLine(await agent.RunAsync("Please contrast the two approaches", session));
+
+Console.WriteLine("\n>> Asking about ancestry\n");
+Console.WriteLine(await agent.RunAsync("What are the predecessors to the Agent Framework?", session));
+
+static async Task UploadDataFromMarkdown(string markdownUrl, string sourceName, VectorStoreCollection<Guid, DocumentationChunk> vectorStoreCollection, int chunkSize, int overlap)
+{
+    // Download the markdown from the given url.
+    using HttpClient client = new();
+    var markdown = await client.GetStringAsync(new Uri(markdownUrl));
+
+    // Chunk it into separate parts with some overlap between chunks
+    var chunks = new List<DocumentationChunk>();
+    for (int i = 0; i < markdown.Length; i += chunkSize)
+    {
+        var chunk = new DocumentationChunk
+        {
+            Key = Guid.NewGuid(),
+            SourceLink = markdownUrl,
+            SourceName = sourceName,
+            Text = markdown.Substring(i, Math.Min(chunkSize + overlap, markdown.Length - i))
+        };
+        chunks.Add(chunk);
+    }
+
+    // Upsert each chunk into the provided vector store.
+    await vectorStoreCollection.UpsertAsync(chunks);
+}
+
+// Data model that defines the database schema we want to use.
+internal sealed class DocumentationChunk
+{
+    [VectorStoreKey]
+    public Guid Key { get; set; }
+    [VectorStoreData]
+    public string SourceLink { get; set; } = string.Empty;
+    [VectorStoreData]
+    public string SourceName { get; set; } = string.Empty;
+    [VectorStoreData]
+    public string Text { get; set; } = string.Empty;
+    [VectorStoreVector(Dimensions: 3072)]
+    public string Embedding => this.Text;
+}
@@ -0,0 +1,60 @@
+# Agent Framework Retrieval Augmented Generation (RAG) with an external Vector Store with a custom schema
+
+This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with an external vector store.
+It also uses a custom schema for the documents stored in the vector store.
+This sample uses Qdrant for the vector store, but this can easily be swapped out for any vector store that has a Microsoft.Extensions.VectorStore implementation.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint
+- Both a chat completion and embedding deployment configured in the Azure OpenAI resource
+- Azure CLI installed and authenticated (for Azure credential authentication)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource.
+- An existing Qdrant instance. You can use a managed service or run a local instance using Docker, but the sample assumes the instance is running locally.
+
+**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+
+**Note**: These samples use Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+## Running the sample from the console
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
+$env:AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME="text-embedding-3-large"  # Optional, defaults to text-embedding-3-large
+```
+
+If the variables are not set, you will be prompted for the values when running the samples.
+
+To use Qdrant in docker locally, start your Qdrant instance using the default port mappings.
+
+```powershell
+docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest
+```
+
+Execute the following command to build the sample:
+
+```powershell
+dotnet build
+```
+
+Execute the following command to run the sample:
+
+```powershell
+dotnet run --no-build
+```
+
+Or just build and run in one step:
+
+```powershell
+dotnet run
+```
+
+## Running the sample from Visual Studio
+
+Open the solution in Visual Studio and set the sample project as the startup project. Then, run the project using the built-in debugger or by pressing `F5`.
+
+You will be prompted for any required environment variables if they are not already set.
@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use TextSearchProvider to add retrieval augmented generation (RAG)
+// capabilities to an AI agent. This shows a mock implementation of a search function,
+// which can be replaced with any custom search logic to query any external knowledge base.
+// The provider invokes the custom search function
+// before each model invocation and injects the results into the model context.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation and keep a short rolling window of conversation context.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    RecentMessageMemoryLimit = 6,
+};
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AIProjectClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
+        AIContextProviders = [new TextSearchProvider(MockSearchAsync, textSearchOptions)]
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine(">> Asking about returns\n");
+Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));
+
+Console.WriteLine("\n>> Asking about shipping\n");
+Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", session));
+
+Console.WriteLine("\n>> Asking about product care\n");
+Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", session));
+
+static Task<IEnumerable<TextSearchProvider.TextSearchResult>> MockSearchAsync(string query, CancellationToken cancellationToken)
+{
+    // The mock search inspects the user's question and returns pre-defined snippets
+    // that resemble documents stored in an external knowledge source.
+    List<TextSearchProvider.TextSearchResult> results = [];
+
+    if (query.Contains("return", StringComparison.OrdinalIgnoreCase) || query.Contains("refund", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Return Policy",
+            SourceLink = "https://contoso.com/policies/returns",
+            Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
+        });
+    }
+
+    if (query.Contains("shipping", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Shipping Guide",
+            SourceLink = "https://contoso.com/help/shipping",
+            Text = "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout."
+        });
+    }
+
+    if (query.Contains("tent", StringComparison.OrdinalIgnoreCase) || query.Contains("fabric", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "TrailRunner Tent Care Instructions",
+            SourceLink = "https://contoso.com/manuals/trailrunner-tent",
+            Text = "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating."
+        });
+    }
+
+    return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
+}
@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="contoso-outdoors-knowledge-base.md">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use the built in RAG capabilities that the Foundry service provides when using AI Agents provided by Foundry.
+
+using System.ClientModel;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using OpenAI;
+using OpenAI.Files;
+using OpenAI.Responses;
+using OpenAI.VectorStores;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// Create an AI Project client and get an OpenAI client that works with the foundry service.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(
+    new Uri(endpoint),
+    new DefaultAzureCredential());
+OpenAIClient openAIClient = aiProjectClient.GetProjectOpenAIClient();
+
+// Upload the file that contains the data to be used for RAG to the Foundry service.
+OpenAIFileClient fileClient = openAIClient.GetOpenAIFileClient();
+ClientResult<OpenAIFile> uploadResult = await fileClient.UploadFileAsync(
+    filePath: "contoso-outdoors-knowledge-base.md",
+    purpose: FileUploadPurpose.Assistants);
+
+// Create a vector store in the Foundry service using the uploaded file.
+VectorStoreClient vectorStoreClient = openAIClient.GetVectorStoreClient();
+ClientResult<VectorStore> vectorStoreCreate = await vectorStoreClient.CreateVectorStoreAsync(options: new VectorStoreCreationOptions()
+{
+    Name = "contoso-outdoors-knowledge-base",
+    FileIds = { uploadResult.Value.Id }
+});
+
+// Use the native OpenAI SDK FileSearchTool directly with the vector store ID.
+#pragma warning disable OPENAI001
+FileSearchTool fileSearchTool = new([vectorStoreCreate.Value.Id]);
+#pragma warning restore OPENAI001
+
+ProjectsAgentVersion agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
+    "AskContoso",
+    new ProjectsAgentVersionCreationOptions(
+        new DeclarativeAgentDefinition(model: deploymentName)
+        {
+            Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+            Tools = { fileSearchTool }
+        }));
+FoundryAgent agent = aiProjectClient.AsAIAgent(agentVersion);
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine(">> Asking about returns\n");
+Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));
+
+Console.WriteLine("\n>> Asking about shipping\n");
+Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", session));
+
+Console.WriteLine("\n>> Asking about product care\n");
+Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", session));
+
+// Cleanup
+await fileClient.DeleteFileAsync(uploadResult.Value.Id);
+await vectorStoreClient.DeleteVectorStoreAsync(vectorStoreCreate.Value.Id);
+await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(agent.Name);
@@ -0,0 +1,19 @@
+# Contoso Outdoors Knowledge Base
+
+## Contoso Outdoors Return Policy
+
+Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection.
+
+## Contoso Outdoors Shipping Guide
+
+Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout.
+
+## Product Information
+
+### TrailRunner Tent
+
+The TrailRunner Tent is a lightweight, 2-person tent designed for easy setup and durability. It features waterproof materials, ventilation windows, and a compact carry bag.
+
+#### Care Instructions
+
+Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating.
@@ -0,0 +1,52 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Remove="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Remove="Microsoft.VisualStudio.Threading.Analyzers" />
+    <PackageReference Remove="xunit.analyzers" />
+    <PackageReference Remove="Moq.Analyzers" />
+    <PackageReference Remove="Roslynator.Analyzers" />
+    <PackageReference Remove="Roslynator.CodeAnalysis.Analyzers" />
+    <PackageReference Remove="Roslynator.Formatting.Analyzers" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.2.0" />
+    <PackageReference Include="Neo4j.AgentFramework.GraphRAG" Version="0.1.0-preview.2" />
+    <PackageReference Include="Neo4j.Driver" Version="5.28.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" Version="1.21.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.CodeAnalysis.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Formatting.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Neo4j.AgentFramework.GraphRAG;
+using Neo4j.Driver;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+var neo4jUri = Environment.GetEnvironmentVariable("NEO4J_URI") ?? throw new InvalidOperationException("NEO4J_URI is not set.");
+var neo4jUsername = Environment.GetEnvironmentVariable("NEO4J_USERNAME") ?? "neo4j";
+var neo4jPassword = Environment.GetEnvironmentVariable("NEO4J_PASSWORD") ?? throw new InvalidOperationException("NEO4J_PASSWORD is not set.");
+var fulltextIndex = Environment.GetEnvironmentVariable("NEO4J_FULLTEXT_INDEX_NAME") ?? "search_chunks";
+
+const string RetrievalQuery = """
+    MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)<-[:FILED]-(company:Company)
+    OPTIONAL MATCH (company)-[:FACES_RISK]->(risk:RiskFactor)
+    WITH node, score, company, doc, collect(DISTINCT risk.name)[0..5] AS risks
+    OPTIONAL MATCH (company)-[:MENTIONS]->(product:Product)
+    WITH node, score, company, doc, risks, collect(DISTINCT product.name)[0..5] AS products
+    RETURN
+        node.text AS text,
+        score,
+        company.name AS company,
+        company.ticker AS ticker,
+        doc.title AS title,
+        risks,
+        products
+    ORDER BY score DESC
+    """;
+
+await using var driver = GraphDatabase.Driver(new Uri(neo4jUri), AuthTokens.Basic(neo4jUsername, neo4jPassword));
+await driver.VerifyConnectivityAsync();
+
+await using var provider = new Neo4jContextProvider(
+    driver,
+    new Neo4jContextProviderOptions
+    {
+        IndexName = fulltextIndex,
+        IndexType = IndexType.Fulltext,
+        RetrievalQuery = RetrievalQuery,
+        TopK = 5,
+        ContextPrompt = "Use the retrieved Neo4j graph context to answer accurately and call out when context is missing."
+    });
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AIProjectClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new()
+        {
+            ModelId = deploymentName,
+            Instructions = "You are a helpful assistant that answers questions using Neo4j graph context."
+        },
+        AIContextProviders = [provider]
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+foreach (var question in new[]
+{
+    "What products does Microsoft offer?",
+    "What risks does Apple face?",
+    "Tell me about NVIDIA's AI business and risk factors."
+})
+{
+    Console.WriteLine($">> {question}\n");
+    Console.WriteLine(await agent.RunAsync(question, session));
+    Console.WriteLine();
+}
@@ -0,0 +1,32 @@
+# Agent Framework Retrieval Augmented Generation (RAG) with Neo4j GraphRAG
+
+This sample demonstrates how to create and run an agent that uses the [Neo4j GraphRAG context provider](https://github.com/neo4j-labs/neo4j-maf-provider) with Microsoft Agent Framework for .NET.
+
+The sample uses a Neo4j fulltext index for retrieval and a Cypher `RetrievalQuery` to enrich results with related companies, products, and risk factors.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI endpoint and chat deployment
+- Azure CLI installed and authenticated
+- A Neo4j database with chunked documents and a fulltext index such as `search_chunks`
+
+## Environment variables
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
+$env:NEO4J_URI="neo4j+s://your-instance.databases.neo4j.io"
+$env:NEO4J_USERNAME="neo4j"
+$env:NEO4J_PASSWORD="your-password"
+$env:NEO4J_FULLTEXT_INDEX_NAME="search_chunks"
+```
+
+## Build and run
+
+```powershell
+dotnet build
+dotnet run --framework net10.0 --no-build
+```
+
+The sample issues a few questions against the graph-backed retrieval provider and prints the responses to the console.
@@ -0,0 +1,11 @@
+# Agent Framework Retrieval Augmented Generation (RAG)
+
+These samples show how to create an agent with the Agent Framework that uses Retrieval Augmented Generation (RAG) to enhance its responses with information from a knowledge base.
+
+|Sample|Description|
+|---|---|
+|[Basic Text RAG](./AgentWithRAG_Step01_BasicTextRAG/)|This sample demonstrates how to create and run a basic agent with simple text Retrieval Augmented Generation (RAG).|
+|[RAG with Vector Store and custom schema](./AgentWithRAG_Step02_CustomVectorStoreRAG/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with a vector store. It also uses a custom schema for the documents stored in the vector store.|
+|[RAG with custom RAG data source](./AgentWithRAG_Step03_CustomRAGDataSource/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with a custom RAG data source.|
+|[RAG with Foundry VectorStore service](./AgentWithRAG_Step04_FoundryServiceRAG/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with the Foundry VectorStore service.|
+|[RAG with Neo4j GraphRAG](./AgentWithRAG_Step05_Neo4jGraphRAG/)|This sample demonstrates how to create and run an agent that uses a Neo4j-backed GraphRAG context provider with graph-enriched retrieval.|