RAG

Microsoft Agent Framework dá suporte à RAG (Recuperação de Geração Aumentada) por meio de provedores de contexto que adicionam conteúdo recuperado antes da invocação de modelo e ferramentas de pesquisa que permitem que o modelo recupere dados de aterramento sob demanda.

Para obter padrões de conversa/sessão juntamente com a recuperação, consulte a visão geral de Conversas & Memória. Para configuração específica do serviço, consulte Pesquisa de IA do Azure , Microsoft Foundry e Neo4j.

Usando TextSearchProvider

A TextSearchProvider classe é uma implementação pronta para uso de um provedor de contexto RAG. Ele dá suporte a diferentes modos de operação, por exemplo, fazer uma pesquisa para cada agente executado com o histórico de chat ou ferramentas de funções de publicidade para fazer pesquisas.

Ele pode ser facilmente anexado a uma ChatClientAgent opção usando a opção 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)]
    });

A TextSearchProvider função requer uma função que fornece os resultados da pesquisa dada uma consulta. Isso pode ser implementado usando qualquer tecnologia de pesquisa, por exemplo, Pesquisa de IA do Azure ou um mecanismo de pesquisa na Web.

Tip

Confira as integrações do repositório Vector para obter mais informações sobre como usar um repositório de vetores para obter resultados de pesquisa.

Aqui está um exemplo de uma função de pesquisa simulada que retorna resultados predefinidos com base na consulta. SourceName e SourceLink são opcionais, mas se fornecidos serão usados pelo agente para citar a origem das informações ao responder à pergunta do usuário.

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

Opções textSearchProvider

Pode TextSearchProvider ser personalizado por meio da TextSearchProviderOptions classe. Aqui está um exemplo de como criar opções para executar a pesquisa antes de cada invocação de modelo e manter uma breve janela sem interrupção do histórico de chat para pesquisas.

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

A TextSearchProvider classe dá suporte às seguintes opções por meio da TextSearchProviderOptions classe.

Opção	Tipo	Description	Default
Tempo de Pesquisa	`TextSearchProviderOptions.TextSearchBehavior`	Indica quando a pesquisa deve ser executada. Há duas opções, cada vez que o agente é executado ou sob demanda por meio de chamada de função.	`TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke`
FunctionToolName	`string`	O nome da ferramenta de pesquisa exposta ao operar no modo sob demanda.	"Pesquisar"
FunctionToolDescription	`string`	A descrição da ferramenta de pesquisa exposta ao operar no modo sob demanda.	"Permite pesquisar informações adicionais para ajudar a responder à pergunta do usuário."
ContextPrompt	`string`	O prompt de contexto prefixado nos resultados.	"## Contexto Adicional\nConsidere as seguintes informações de documentos de origem ao responder ao usuário:"
CitationsPrompt	`string`	A instrução acrescentada após os resultados para solicitar citações.	"Inclua citações ao documento de origem com o nome do documento e o link se o nome e o link do documento estiverem disponíveis."
ContextFormatter	`Func<IList<TextSearchProvider.TextSearchResult>, string>`	Delegado opcional para personalizar totalmente a formatação da lista de resultados. Se fornecido e `ContextPromptCitationsPrompt` ignorado.	`null`
RecentMessageMemoryLimit	`int`	O número de mensagens de conversa recentes (usuário e assistente) para manter na memória e incluir ao construir a entrada de pesquisa para `BeforeAIInvoke` pesquisas.	`0` (desabilitado)
RecentMessageRolesIncluded	`List<ChatRole>`	A lista de `ChatRole` tipos para os quais filtrar mensagens recentes ao decidir quais mensagens recentes incluir ao construir a entrada de pesquisa.	`ChatRole.User`

Tip

Consulte os exemplos do .NET para obter exemplos executáveis completos.

O Agent Framework fornece contratos de repositório de vetores nativos e create_vector_search_tool(). O auxiliar transforma qualquer SupportsVectorSearch implementação em uma ferramenta de função, para que o modelo possa recuperar dados de aterramento antes de responder.

Criar uma ferramenta de pesquisa de vetor nativo

Primeiro, defina seu modelo de repositório de vetores, crie uma coleção e carregue seus registros. O exemplo a seguir usa InMemoryCollection com OpenAIEmbeddingClient, mas você pode fornecer qualquer coleção nativa do Agent Framework que implemente SupportsVectorSearch. Em seguida, expõe filtros opcionais de categoria e classificação para o modelo, mapeia cada resultado para texto de aterramento e instrui o agente a pesquisar antes de responder:

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)

O exemplo completo define o Hotel modelo e carrega os registros de origem antes da configuração da coleção mostrada. Defina OPENAI_API_KEY antes de executá-lo.

Personalizar o comportamento da pesquisa

Configure create_vector_search_tool() com as seguintes opções:

Opção	Purpose
`name`	Define o nome da função exposto ao modelo. Use um nome exclusivo ao adicionar várias ferramentas de pesquisa.
`description`	Explica quando e por que o modelo deve usar a ferramenta.
`approval_mode`	Define a aprovação da ferramenta como `always_require` ou `never_require`.
`search_type`	`vector` Seleciona ou `keyword_hybrid` pesquisa. A coleção deve dar suporte ao modo selecionado.
`top` e `skip`	Defina valores de paginação fixos ou use valores tipados `Param` fornecidos pelo modelo.
`filter`	Aplica um portátil `Filter` ou `FilterGroup`. Um filtro pode conter valores tipado `Param` expostos no esquema de ferramentas.
`result_mapper`	Converte cada um `SearchResponse` em texto ou multimodal `Content` para o modelo.

A ferramenta gerada sempre inclui uma query cadeia de caracteres. Quaisquer Param valores no filtro topou skip configurações se tornam argumentos de ferramenta validados adicionais. Use Literal e restrições numéricas para manter valores fornecidos pelo modelo dentro do intervalo que seu aplicativo aceita.

Você pode criar várias ferramentas para diferentes coleções ou modos de pesquisa. Dê a cada ferramenta um diferencial name e description , portanto, o modelo pode selecionar a fonte de conhecimento apropriada.

Escolher um repositório de vetores nativo

Implementações de Python nativas estão disponíveis para pesquisa na memória, Pesquisa de IA do Azure , PostgreSQL com pgvector, Qdrant e Redis. Os modos de pesquisa, o ciclo de vida do pacote, os comandos de instalação e as limitações diferem. Confira as integrações do Repositório vetor para selecionar e configurar uma implementação. Essa página também identifica bancos de dados que atualmente têm apenas um conector Kernel semântico separado.

Note

O suporte para Go a este recurso estará disponível em breve. Consulte o repositório Agent Framework Go para obter o status mais recente.

Graph RAG

Para GraphRAG usando a pesquisa enriquecida de grafo com consultas Cypher, consulte o Provedor Do GraphRAG Neo4j.

Próximas Etapas

Agentes Declarativos

Comentários

Esta página foi útil?

Last updated on 2026-09-11