LUMP

Använda TextSearchProvider

Klassen TextSearchProvider är en out-of-the-box-implementering av en RAG-kontextprovider. Den stöder olika driftslägen, t.ex. att söka efter varje agent som körs med chatthistorik eller verktyg för annonseringsfunktioner för att göra sökningar.

Den kan enkelt kopplas till en ChatClientAgent med hjälp av AIContextProviders alternativet .

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

Kräver TextSearchProvider en funktion som ger sökresultaten som ges en fråga. Detta kan implementeras med hjälp av sökteknik, t.ex. Azure AI-sökning eller en webbsökmotor.

Här är ett exempel på en modellsökningsfunktion som returnerar fördefinierade resultat baserat på frågan. SourceName och SourceLink är valfria, men om de tillhandahålls kommer att användas av agenten för att citera källan till informationen när användarens fråga besvaras.

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

Alternativ för TextSearchProvider

TextSearchProvider Kan anpassas via TextSearchProviderOptions klassen. Här är ett exempel på hur du skapar alternativ för att köra sökningen före varje modellanrop och hålla ett kort rullande fönster med chatthistorik för sökningar.

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

Klassen TextSearchProvider stöder följande alternativ via TextSearchProviderOptions klassen.

Agent Framework tillhandahåller interna vektorlagringskontrakt och create_vector_search_tool(). Hjälpen omvandlar en SupportsVectorSearch implementering till ett funktionsverktyg, så att modellen kan hämta grunddata innan den svarar.

Skapa ett internt vektorsökningsverktyg

Definiera först vektorlagringsmodellen, skapa en samling och läs in dess poster. Följande exempel använder InMemoryCollection med OpenAIEmbeddingClient, men du kan ange vilken intern Agent Framework-samling som helst som implementerar SupportsVectorSearch. Sedan exponeras valfria kategori- och klassificeringsfilter för modellen, mappar varje resultat till jordningstext och instruerar agenten att söka innan den svarar:

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)

Det fullständiga exemplet definierar Hotel modellen och läser in källposterna före den visade samlingskonfigurationen. Ställ in OPENAI_API_KEY innan du kör den.

Anpassa sökbeteende

Konfigurera create_vector_search_tool() med följande alternativ:

Det genererade verktyget innehåller alltid en query sträng. Alla Param värden i filtret, topeller skip inställningarna blir ytterligare verifierade verktygsargument. Använd Literal och numeriska begränsningar för att hålla värden som tillhandahålls av modellen inom det intervall som programmet accepterar.

Du kan skapa flera verktyg för olika samlingar eller söklägen. Ge varje verktyg en distinkt name och description så att modellen kan välja lämplig kunskapskälla.

Välj ett internt vektorlager

Inbyggda Python implementeringar är tillgängliga för minnesintern sökning, Azure AI-sökning, PostgreSQL med pgvector, Qdrant och Redis. Deras söklägen, paketlivscykel, installationskommandon och begränsningar skiljer sig åt. Se Vector Store-integreringar för att välja och konfigurera en implementering. Den sidan identifierar även databaser som för närvarande bara har en separat Semantic Kernel anslutningsapp.