Condividi tramite

Generazione aumentata dell'agente

Microsoft Agent Framework supporta l'aggiunta di funzionalità di generazione aumentata di recupero agli agenti facilmente aggiungendo provider di contesto di intelligenza artificiale all'agente.

Uso di TextSearchProvider

La TextSearchProvider classe è un'implementazione predefinita di un provider di contesto RAG.

Può essere facilmente collegato a un ChatClientAgent oggetto usando l'opzione AIContextProviderFactory per fornire funzionalità RAG all'agente.

// Create the AI agent with the TextSearchProvider as the AI context provider.
AIAgent agent = azureOpenAIClient
    .GetChatClient(deploymentName)
    .CreateAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
        AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
    });

richiede TextSearchProvider una funzione che fornisce i risultati della ricerca in base a una query. Questa operazione può essere implementata usando qualsiasi tecnologia di ricerca, ad esempio Ricerca di intelligenza artificiale di Azure o un motore di ricerca Web.

Di seguito è riportato un esempio di una funzione di ricerca fittizia che restituisce risultati predefiniti basati sulla query. SourceName e SourceLink sono facoltativi, ma se forniti verranno usati dall'agente per citare l'origine delle informazioni quando risponde alla domanda dell'utente.

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

Opzioni TextSearchProvider

Può TextSearchProvider essere personalizzato tramite la TextSearchProviderOptions classe . Di seguito è riportato un esempio di creazione di opzioni per eseguire la ricerca prima di ogni chiamata al modello e mantenere una breve finestra di conversazione in sequenza.

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

La TextSearchProvider classe supporta le opzioni seguenti tramite la TextSearchProviderOptions classe .

Opzione TIPO Description Impostazione predefinita
SearchTime TextSearchProviderOptions.TextSearchBehavior Indica quando deve essere eseguita la ricerca. Sono disponibili due opzioni, ogni volta che l'agente viene richiamato o su richiesta tramite chiamata di funzione. TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke
FunctionToolName string Nome dello strumento di ricerca esposto quando si opera in modalità su richiesta. "Cerca"
FunctionToolDescription string Descrizione dello strumento di ricerca esposto quando si opera in modalità su richiesta. "Consente la ricerca di informazioni aggiuntive per rispondere alla domanda dell'utente."
ContextPrompt string Il prompt del contesto è preceduto dai risultati quando si opera in BeforeAIInvoke modalità . "## Contesto aggiuntivo\nPrendere in considerazione le informazioni seguenti dai documenti di origine quando rispondono all'utente:"
CitazioniPrompt string L'istruzione è stata aggiunta dopo i risultati per richiedere citazioni quando si opera in BeforeAIInvoke modalità . "Includi citazioni al documento di origine con il nome del documento e collega se il nome e il collegamento del documento sono disponibili".
ContextFormatter Func<IList<TextSearchProvider.TextSearchResult>, string> Delegato facoltativo per personalizzare completamente la formattazione dell'elenco risultati quando si opera in BeforeAIInvoke modalità. Se specificato, ContextPrompt e CitationsPrompt vengono ignorati. null
RecentMessageMemoryLimit int Numero di messaggi di conversazione recenti (sia utente che assistente) da mantenere in memoria e includere quando si costruisce l'input di ricerca per BeforeAIInvoke le ricerche. 0 (disabilitato)
RecentMessageRolesIncluded List<ChatRole> Elenco di ChatRole tipi a cui filtrare i messaggi recenti quando si decide quali messaggi recenti includere quando si costruisce l'input di ricerca. ChatRole.User

Uso di Semantic Kernel VectorStore con Agent Framework

Agent Framework supporta l'uso delle raccolte VectorStore del kernel semantico per fornire funzionalità RAG agli agenti. Questo risultato viene ottenuto tramite la funzionalità bridge che converte le funzioni di ricerca del kernel semantico in strumenti di Agent Framework.

Importante

Questa funzionalità richiede semantic-kernel la versione 1.38 o successiva.

Creazione di uno strumento di ricerca da VectorStore

Il create_search_function metodo da un insieme Semantic Kernel VectorStore restituisce un oggetto KernelFunction che può essere convertito in uno strumento di Agent Framework usando .as_agent_framework_tool(). Usare la documentazione dei connettori dell'archivio vettoriale per informazioni su come configurare raccolte di archivi vettoriali diverse.

from semantic_kernel.connectors.ai.open_ai import OpenAITextEmbedding
from semantic_kernel.connectors.azure_ai_search import AzureAISearchCollection
from semantic_kernel.functions import KernelParameterMetadata
from agent_framework.openai import OpenAIResponsesClient

# Define your data model
class SupportArticle:
    article_id: str
    title: str
    content: str
    category: str
    # ... other fields

# Create an Azure AI Search collection
collection = AzureAISearchCollection[str, SupportArticle](
    record_type=SupportArticle,
    embedding_generator=OpenAITextEmbedding()
)

async with collection:
    await collection.ensure_collection_exists()
    # Load your knowledge base articles into the collection
    # await collection.upsert(articles)

    # Create a search function from the collection
    search_function = collection.create_search_function(
        function_name="search_knowledge_base",
        description="Search the knowledge base for support articles and product information.",
        search_type="keyword_hybrid",
        parameters=[
            KernelParameterMetadata(
                name="query",
                description="The search query to find relevant information.",
                type="str",
                is_required=True,
                type_object=str,
            ),
            KernelParameterMetadata(
                name="top",
                description="Number of results to return.",
                type="int",
                default_value=3,
                type_object=int,
            ),
        ],
        string_mapper=lambda x: f"[{x.record.category}] {x.record.title}: {x.record.content}",
    )

    # Convert the search function to an Agent Framework tool
    search_tool = search_function.as_agent_framework_tool()

    # Create an agent with the search tool
    agent = OpenAIResponsesClient(model_id="gpt-4o").create_agent(
        instructions="You are a helpful support specialist. Use the search tool to find relevant information before answering questions. Always cite your sources.",
        tools=search_tool
    )

    # Use the agent with RAG capabilities
    response = await agent.run("How do I return a product?")
    print(response.text)

Personalizzazione del comportamento di ricerca

È possibile personalizzare la funzione di ricerca con varie opzioni:

# Create a search function with filtering and custom formatting
search_function = collection.create_search_function(
    function_name="search_support_articles",
    description="Search for support articles in specific categories.",
    search_type="keyword_hybrid",
    # Apply filters to restrict search scope
    filter=lambda x: x.is_published == True,
    parameters=[
        KernelParameterMetadata(
            name="query",
            description="What to search for in the knowledge base.",
            type="str",
            is_required=True,
            type_object=str,
        ),
        KernelParameterMetadata(
            name="category",
            description="Filter by category: returns, shipping, products, or billing.",
            type="str",
            type_object=str,
        ),
        KernelParameterMetadata(
            name="top",
            description="Maximum number of results to return.",
            type="int",
            default_value=5,
            type_object=int,
        ),
    ],
    # Customize how results are formatted for the agent
    string_mapper=lambda x: f"Article: {x.record.title}\nCategory: {x.record.category}\nContent: {x.record.content}\nSource: {x.record.article_id}",
)

Per informazioni dettagliate sui parametri disponibili per create_search_function, vedere la documentazione del kernel semantico.

Uso di più funzioni di ricerca

È possibile fornire più strumenti di ricerca a un agente per domini di conoscenza diversi:

# Create search functions for different knowledge bases
product_search = product_collection.create_search_function(
    function_name="search_products",
    description="Search for product information and specifications.",
    search_type="semantic_hybrid",
    string_mapper=lambda x: f"{x.record.name}: {x.record.description}",
).as_agent_framework_tool()

policy_search = policy_collection.create_search_function(
    function_name="search_policies",
    description="Search for company policies and procedures.",
    search_type="keyword_hybrid",
    string_mapper=lambda x: f"Policy: {x.record.title}\n{x.record.content}",
).as_agent_framework_tool()

# Create an agent with multiple search tools
agent = chat_client.create_agent(
    instructions="You are a support agent. Use the appropriate search tool to find information before answering. Cite your sources.",
    tools=[product_search, policy_search]
)

È anche possibile creare più funzioni di ricerca dalla stessa raccolta con descrizioni e parametri diversi per fornire funzionalità di ricerca specializzate:

# Create multiple search functions from the same collection
# Generic search for broad queries
general_search = support_collection.create_search_function(
    function_name="search_all_articles",
    description="Search all support articles for general information.",
    search_type="semantic_hybrid",
    parameters=[
        KernelParameterMetadata(
            name="query",
            description="The search query.",
            type="str",
            is_required=True,
            type_object=str,
        ),
    ],
    string_mapper=lambda x: f"{x.record.title}: {x.record.content}",
).as_agent_framework_tool()

# Detailed lookup for specific article IDs
detail_lookup = support_collection.create_search_function(
    function_name="get_article_details",
    description="Get detailed information for a specific article by its ID.",
    search_type="keyword",
    top=1,
    parameters=[
        KernelParameterMetadata(
            name="article_id",
            description="The specific article ID to retrieve.",
            type="str",
            is_required=True,
            type_object=str,
        ),
    ],
    string_mapper=lambda x: f"Title: {x.record.title}\nFull Content: {x.record.content}\nLast Updated: {x.record.updated_date}",
).as_agent_framework_tool()

# Create an agent with both search functions
agent = chat_client.create_agent(
    instructions="You are a support agent. Use search_all_articles for general queries and get_article_details when you need full details about a specific article.",
    tools=[general_search, detail_lookup]
)

Questo approccio consente all'agente di scegliere la strategia di ricerca più appropriata in base alla query dell'utente.

Connettori VectorStore supportati

Questo modello funziona con qualsiasi connettore Semantic Kernel VectorStore, tra cui:

  • Ricerca di intelligenza artificiale di Azure (AzureAISearchCollection)
  • Qdrant (QdrantCollection)
  • Pinecone (PineconeCollection)
  • Redis (RedisCollection)
  • Weaviate (WeaviateCollection)
  • In-Memory (InMemoryVectorStoreCollection)
  • Altri aspetti

Ogni connettore fornisce lo stesso create_search_function metodo che può essere connesso agli strumenti di Agent Framework, consentendo di scegliere il database vettoriale più adatto alle proprie esigenze. Vedere l'elenco completo qui.

Passaggi successivi

Middleware agente

  • Last updated on