RAG

Microsoft Agent Framework prend en charge la récupération de génération augmentée (RAG) par le biais de fournisseurs de contexte qui ajoutent du contenu récupéré avant l’appel de modèle et les outils de recherche qui permettent au modèle de récupérer des données de base à la demande.

Pour connaître les modèles de conversation/session en même temps que la récupération, consultez La vue d’ensemble des conversations et de la mémoire. Pour une configuration spécifique au service, consultez Recherche Azure AI, Microsoft Foundry et Neo4j.

Utilisation de TextSearchProvider

La TextSearchProvider classe est une implémentation prête à l’emploi d’un fournisseur de contexte RAG. Il prend en charge différents modes d’opération, par exemple en effectuant une recherche pour chaque agent exécuté avec l’historique des conversations ou les outils de fonction publicitaire pour effectuer des recherches.

Il peut facilement être attaché à une ChatClientAgent option à l’aide de l’option AIContextProviders .

// Configure the options for the TextSearchProvider.
TextSearchProviderOptions textSearchOptions = new()
{
    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
};

// Create the AI agent with the TextSearchProvider.
AIAgent agent = azureOpenAIClient
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new() { Instructions = "You are a helpful support specialist. Answer questions using the provided context and cite the source document when available." },
        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)]
    });

La TextSearchProvider fonction nécessite une fonction qui fournit les résultats de la recherche en fonction d’une requête. Cela peut être implémenté à l’aide de n’importe quelle technologie de recherche, par exemple Recherche Azure AI ou d’un moteur de recherche web.

Tip

Pour plus d’informations sur l’utilisation d’un magasin vectoriel pour les résultats de la recherche, consultez les intégrations de magasin de vecteurs .

Voici un exemple de fonction de recherche fictif qui retourne des résultats prédéfinis en fonction de la requête. SourceName et SourceLink sont facultatifs, mais si fourni sera utilisé par l’agent pour citer la source des informations lors de la réponse à la question de l’utilisateur.

static Task<IEnumerable<TextSearchProvider.TextSearchResult>> SearchAdapter(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 = new();

    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."
        });
    }

    return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
}

TextSearchProvider Options

Il TextSearchProvider peut être personnalisé par le biais de la TextSearchProviderOptions classe. Voici un exemple de création d’options permettant d’exécuter la recherche avant chaque appel de modèle et de conserver une courte fenêtre propagée de l’historique des conversations pour les recherches.

TextSearchProviderOptions textSearchOptions = new()
{
    // Run the search prior to every model invocation and keep a short rolling window of chat history for searches.
    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
    RecentMessageMemoryLimit = 6,
};

La TextSearchProvider classe prend en charge les options suivantes via la TextSearchProviderOptions classe.

Option	Type	Description	Default
TempsDeRecherche	`TextSearchProviderOptions.TextSearchBehavior`	Indique quand la recherche doit être exécutée. Il existe deux options, chaque fois que l’agent est exécuté ou à la demande via l’appel de fonction.	`TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke`
FunctionToolName	`string`	Nom de l’outil de recherche exposé lors de l’utilisation en mode à la demande.	« Rechercher »
FunctionToolDescription	`string`	Description de l’outil de recherche exposé lors de l’utilisation en mode à la demande.	« Permet de rechercher des informations supplémentaires pour répondre à la question de l’utilisateur. »
ContextPrompt	`string`	L’invite de contexte est précédée des résultats.	« ## Contexte supplémentaire\nprendre en compte les informations suivantes des documents sources lors de la réponse à l’utilisateur : »
CitationsPrompt	`string`	L’instruction ajoutée après les résultats pour demander des citations.	« Incluez des citations au document source avec le nom du document et le lien si le nom et le lien du document sont disponibles. »
ContextFormatter	`Func<IList<TextSearchProvider.TextSearchResult>, string>`	Délégué facultatif pour personnaliser entièrement la mise en forme de la liste de résultats. Si elles sont fournies et `ContextPromptCitationsPrompt` sont ignorées.	`null`
RecentMessageMemoryLimit	`int`	Nombre de messages de conversation récents (utilisateur et Assistant) à conserver en mémoire et à inclure lors de la construction de l’entrée de recherche pour `BeforeAIInvoke` les recherches.	`0` (désactivé)
RecentMessageRolesIncluded	`List<ChatRole>`	Liste des `ChatRole` types à filtrer pour filtrer les messages récents lors du choix des messages récents à inclure lors de la construction de l’entrée de recherche.	`ChatRole.User`

Tip

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

Agent Framework fournit des contrats de magasin vectoriel natif et create_vector_search_tool(). L’assistance transforme toute SupportsVectorSearch implémentation en outil de fonction, afin que le modèle puisse récupérer des données de base avant de répondre.

Créer un outil de recherche vectorielle natif

Tout d’abord, définissez votre modèle de magasin de vecteurs, créez une collection et chargez ses enregistrements. L’exemple suivant utilise InMemoryCollection avec OpenAIEmbeddingClient, mais vous pouvez fournir n’importe quelle collection Native Agent Framework qui implémente SupportsVectorSearch. Il expose ensuite des filtres de catégorie et d’évaluation facultatifs au modèle, mappe chaque résultat au texte de base et demande à l’agent de rechercher avant de répondre :

import asyncio
import json
import os
from typing import Annotated, Any, Literal
from urllib.request import urlopen

from agent_framework import (
    Agent,
    Filter,
    FilterGroup,
    InMemoryCollection,
    Param,
    VectorStoreField,
    create_vector_search_tool,
    vectorstoremodel,
)
from agent_framework.openai import OpenAIChatClient, OpenAIEmbeddingClient
from dotenv import load_dotenv
async def main() -> None:
    """Create an in-memory hotel search tool and give it to an agent."""
    api_key = os.environ["OPENAI_API_KEY"]
    collection: InMemoryCollection[str, Hotel] = InMemoryCollection(
        Hotel,
        embedding_generator=OpenAIEmbeddingClient(
            model="text-embedding-3-small",
            api_key=api_key,
        ),
    )
    await collection.ensure_collection_exists()

    # 1. Load the hotel records.
    hotels = await asyncio.to_thread(load_hotels)
    await collection.upsert(hotels)

    # 2. Param values become optional model-visible filter arguments.
    # When the allowed values are known, use Literal so the tool schema exposes
    # them as an enum.
    category = Param(
        "category",
        Literal["Boutique", "Budget", "Extended-Stay", "Luxury", "Resort and Spa", "Suite"],
        description="Only return hotels in this category.",
    )
    min_rating = Param(
        "min_rating",
        float,
        description="The minimum guest rating.",
        minimum=0,
        maximum=5,
    )
    tool = create_vector_search_tool(
        collection,
        description="Search the hotel dataset, optionally filtering by category and minimum rating.",
        filter=FilterGroup(
            "and",
            (
                Filter("category", "eq", category),
                Filter("rating", "gte", min_rating),
            ),
        ),
        result_mapper=lambda result: (
            f"(hotel_id: {result['record'].hotel_id}) {result['record'].hotel_name} "
            f"(rating {result['record'].rating}) - {result['record'].description}. "
            f"Address: {result['record'].address.city}, {result['record'].address.country}."
        ),
    )

    # 3. The agent chooses whether to supply the exposed category and minimum-rating filters.
    async with Agent(
        client=OpenAIChatClient(
            model="gpt-5.4-nano",
            api_key=api_key,
        ),
        name="HotelAgent",
        instructions=(
            "Always use the search tool to answer hotel questions. "
            "Use category and minimum rating filters when the request provides them. "
            "Include the hotel_id in the answer."
        ),
        tools=[tool],
    ) as agent:
        result = await agent.run("Find a resort and spa with a rating of at least 4.")
        print(result)

L’exemple complet définit le Hotel modèle et charge les enregistrements sources avant la configuration de collection affichée. Définissez OPENAI_API_KEY avant de l’exécuter.

Personnaliser le comportement de recherche

Configurez create_vector_search_tool() avec les options suivantes :

Option	Purpose
`name`	Définit le nom de la fonction exposé au modèle. Utilisez un nom unique lorsque vous ajoutez plusieurs outils de recherche.
`description`	Explique quand et pourquoi le modèle doit utiliser l’outil.
`approval_mode`	Définit l’approbation de l’outil sur `always_require` ou `never_require`.
`search_type`	`vector` Sélectionne ou `keyword_hybrid` recherche. La collection doit prendre en charge le mode sélectionné.
`top` et `skip`	Définissez des valeurs de pagination fixes ou utilisez des valeurs typées `Param` que le modèle fournit.
`filter`	Applique un portable `Filter` ou `FilterGroup`. Un filtre peut contenir des valeurs typées exposées `Param` dans le schéma de l’outil.
`result_mapper`	Convertit chacun `SearchResponse` en texte ou modal `Content` pour le modèle.

L’outil généré inclut toujours une query chaîne. Toutes les Param valeurs du filtre, topou skip des paramètres deviennent des arguments d’outil validés supplémentaires. Utilisez Literal et des contraintes numériques pour conserver les valeurs fournies par le modèle dans la plage acceptée par votre application.

Vous pouvez créer plusieurs outils pour différents regroupements ou modes de recherche. Donnez à chaque outil une valeur distincte name , ce description qui permet au modèle de sélectionner la source de connaissances appropriée.

Choisir un magasin vectoriel natif

Les implémentations natives de Python sont disponibles pour la recherche en mémoire, Recherche Azure AI, PostgreSQL avec pgvector, Qdrant et Redis. Leurs modes de recherche, leur cycle de vie des packages, les commandes d’installation et les limitations diffèrent. Consultez les intégrations de magasin de vecteurs pour sélectionner et configurer une implémentation. Cette page identifie également les bases de données qui n’ont actuellement qu’un connecteur Noyau sémantique distinct.

Note

La prise en charge de Go pour cette fonctionnalité arrivera bientôt. Consultez le référentiel Agent Framework Go pour connaître l’état le plus récent.

Graph RAG

Pour GraphRAG à l’aide d’une recherche enrichie graphique avec des requêtes Cypher, consultez le fournisseur Neo4j GraphRAG.

Étapes suivantes

Agents déclaratifs

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-09-11