RAG

Microsoft Agent Framework ondersteunt Rag (Retrieval Augmented Generation) via contextproviders die opgehaalde inhoud toevoegen vóór het aanroepen en zoeken van modellen waarmee het model grondgegevens op aanvraag kan ophalen.

Zie gespreks- en geheugenoverzicht voor gespreks-/sessiepatronen naast het ophalen. Zie Azure AI Zoeken, Microsoft Foundry en Neo4j voor servicespecifieke instellingen.

TextSearchProvider gebruiken

De TextSearchProvider klasse is een out-of-the-box-implementatie van een RAG-contextprovider. Het ondersteunt verschillende bewerkingsmodi, zoals het uitvoeren van een zoekopdracht voor elke agent die wordt uitgevoerd met chatgeschiedenis, of hulpprogramma's voor advertentiefuncties voor het uitvoeren van zoekopdrachten.

Het kan eenvoudig worden gekoppeld aan een ChatClientAgent met behulp van de AIContextProviders optie.

// 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)]
    });

Hiervoor TextSearchProvider is een functie vereist die de zoekresultaten levert op basis van een query. Dit kan worden geïmplementeerd met behulp van elke zoektechnologie, bijvoorbeeld Azure AI Zoeken of een zoekmachine op internet.

Tip

Zie Vector Store-integraties voor meer informatie over het gebruik van een vectorarchief voor zoekresultaten.

Hier volgt een voorbeeld van een mockzoekfunctie die vooraf gedefinieerde resultaten retourneert op basis van de query. SourceName en SourceLink zijn optioneel, maar indien opgegeven wordt gebruikt door de agent om de bron van de informatie te citeren bij het beantwoorden van de vraag van de gebruiker.

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

Opties voor TextSearchProvider

De TextSearchProvider kan worden aangepast via de TextSearchProviderOptions klasse. Hier volgt een voorbeeld van het maken van opties voor het uitvoeren van de zoekopdracht vóór elke aanroep van het model en het bewaren van een kort lopend chatvenster voor zoekopdrachten.

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,
};

De TextSearchProvider klasse ondersteunt de volgende opties via de TextSearchProviderOptions klasse.

Option	Type	Beschrijving	Default
Zoektijd	TextSearchProviderOptions.TextSearchBehavior	Geeft aan wanneer de zoekopdracht moet worden uitgevoerd. Er zijn twee opties, telkens wanneer de agent wordt uitgevoerd of op aanvraag via functieoproepen.	TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke
FunctionToolName	string	De naam van het weergegeven zoekprogramma wanneer u in de modus op aanvraag werkt.	"Zoeken"
FunctionToolDescription	string	De beschrijving van het weergegeven zoekprogramma wanneer u in de modus op aanvraag werkt.	"Hiermee kunt u zoeken naar aanvullende informatie om de vraag van de gebruiker te beantwoorden."
ContextPrompt	string	De contextprompt voorafgegaan door resultaten.	"## Aanvullende context\nHoud rekening met de volgende informatie uit brondocumenten bij het reageren op de gebruiker:"
CitationsPrompt	string	De instructie toegevoegd na resultaten om bronvermeldingen aan te vragen.	"Bronvermeldingen opnemen in het brondocument met documentnaam en koppeling als documentnaam en koppeling beschikbaar is."
ContextFormatter	Func<IList<TextSearchProvider.TextSearchResult>, string>	Optionele gemachtigde om de opmaak van de lijst met resultaten volledig aan te passen. Indien opgegeven ContextPrompt en CitationsPrompt worden genegeerd.	null
RecentMessageMemoryLimit	int	Het aantal recente gespreksberichten (zowel gebruiker als assistent) dat in het geheugen moet worden bewaard en moet worden opgenomen bij het samenstellen van de zoekinvoer voor BeforeAIInvoke zoekopdrachten.	0 (uitgeschakeld)
RecentMessageRolesIncluded	List<ChatRole>	De lijst met ChatRole typen waarop recente berichten moeten worden gefilterd bij het bepalen welke recente berichten moeten worden opgenomen bij het samenstellen van de zoekinvoer.	ChatRole.User

Tip

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

Agent Framework biedt systeemeigen vectorarchiefcontracten en create_vector_search_tool(). Met de helper wordt elke SupportsVectorSearch implementatie omgezet in een functiehulpprogramma, zodat het model grondgegevens kan ophalen voordat deze antwoordt.

Een systeemeigen vectorzoekprogramma maken

Definieer eerst uw vectorarchiefmodel, maak een verzameling en laad de records. In het volgende voorbeeld wordt gebruikgemaakt InMemoryCollection van OpenAIEmbeddingClient, maar u kunt elke systeemeigen Agent Framework-verzameling opgeven die wordt geïmplementeerd SupportsVectorSearch. Vervolgens worden optionele categorie- en classificatiefilters aan het model weergegeven, wordt elk resultaat toegewezen aan tekst die wordt geaard en wordt de agent geïnstrueerd om te zoeken voordat deze antwoordt:

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)

Het volledige voorbeeld definieert het Hotel model en laadt de bronrecords voordat de weergegeven verzameling wordt ingesteld. Stel in OPENAI_API_KEY voordat u het uitvoert.

Zoekgedrag aanpassen

Configureer create_vector_search_tool() met de volgende opties:

Option	Purpose
name	Hiermee stelt u de functienaam in die beschikbaar is voor het model. Gebruik een unieke naam wanneer u meerdere zoekhulpprogramma's toevoegt.
description	Hier wordt uitgelegd wanneer en waarom het model het hulpprogramma moet gebruiken.
approval_mode	Hiermee stelt u goedkeuring van hulpprogramma's in op always_require of never_require.
search_type	Selecteert vector of keyword_hybrid zoekt. De verzameling moet de geselecteerde modus ondersteunen.
top en skip	Stel vaste pagingwaarden in of gebruik getypte Param waarden die door het model worden geleverd.
filter	Hiermee past u een draagbare Filter of FilterGroup. Een filter kan getypte Param waarden bevatten die beschikbaar zijn in het hulpprogrammaschema.
result_mapper	Converteert elk SearchResponse naar tekst of multimodale Content voor het model.

Het gegenereerde hulpprogramma bevat altijd een query tekenreeks. Alle Param waarden in het filter of topinstellingen skip worden extra gevalideerde hulpprogrammaargumenten. Gebruik Literal en numerieke beperkingen om door het model geleverde waarden binnen het bereik te houden dat uw toepassing accepteert.

U kunt meerdere hulpprogramma's maken voor verschillende verzamelingen of zoekmodi. Geef elk hulpprogramma een afzonderlijke name functie, description zodat het model de juiste kennisbron kan selecteren.

Een systeemeigen vectorarchief kiezen

Systeemeigen Python-implementaties zijn beschikbaar voor in-memory zoekopdrachten, Azure AI Zoeken, PostgreSQL met pgvector, Qdrant en Redis. Hun zoekmodi, pakketlevenscyclus, installatieopdrachten en beperkingen verschillen. Zie Vector Store-integraties om een implementatie te selecteren en te configureren. Deze pagina identificeert ook databases die momenteel slechts een afzonderlijke Semantic Kernel-connector hebben.

Opmerking

Ondersteuning voor deze functie is binnenkort beschikbaar. Zie de opslagplaats Agent Framework Go voor de meest recente status.

Grafiek RAG

Zie de Neo4j GraphRAG-provider voor graph traversal verrijkte zoekopdrachten met Cypher-query's voor GraphRAG.

Volgende stappen 

Declaratieve agents