RAG

Microsoft Agent Framework admite la generación aumentada de recuperación (RAG) a través de proveedores de contexto que agregan contenido recuperado antes de la invocación del modelo y las herramientas de búsqueda que permiten al modelo recuperar los datos en tierra a petición.

Para conocer los patrones de conversación y sesión junto con la recuperación, consulte Información general sobre conversaciones y memoria. Para obtener una configuración específica del servicio, consulte Búsqueda de Azure AI, Microsoft Foundry y Neo4j.

Uso de TextSearchProvider

La TextSearchProvider clase es una implementación integrada de un proveedor de contexto RAG. Admite diferentes modos de funcionamiento, por ejemplo, realizar una búsqueda de cada agente que se ejecute con el historial de chat o las herramientas de funciones de publicidad para realizar búsquedas.

Se puede asociar fácilmente a mediante ChatClientAgent la AIContextProviders opción .

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

TextSearchProvider requiere una función que proporcione los resultados de la búsqueda dada una consulta. Esto se puede implementar mediante cualquier tecnología de búsqueda, por ejemplo, Búsqueda de Azure AI o un motor de búsqueda web.

Tip

Consulte Integraciones de almacén de vectores para obtener más información sobre cómo usar un almacén de vectores para los resultados de búsqueda.

Este es un ejemplo de una función de búsqueda simulada que devuelve resultados predefinidos en función de la consulta. SourceName y SourceLink son opcionales, pero si el agente lo usará para citar el origen de la información al responder a la pregunta del usuario.

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

Opciones de TextSearchProvider

TextSearchProvider se puede personalizar a través de la TextSearchProviderOptions clase . Este es un ejemplo de creación de opciones para ejecutar la búsqueda antes de cada invocación de modelo y mantener una breve ventana gradual del historial de chat para las búsquedas.

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 clase admite las siguientes opciones a través de la TextSearchProviderOptions clase .

Option	Type	Description	Default
TiempoDeBúsqueda	TextSearchProviderOptions.TextSearchBehavior	Indica cuándo se debe ejecutar la búsqueda. Hay dos opciones, cada vez que se ejecuta el agente o a petición a través de una llamada de función.	TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke
FunctionToolName	string	Nombre de la herramienta de búsqueda expuesta al operar en modo a petición.	"Buscar"
FunctionToolDescription	string	Descripción de la herramienta de búsqueda expuesta al operar en modo a petición.	"Permite buscar información adicional para ayudar a responder a la pregunta del usuario".
ContextPrompt	string	Mensaje de contexto prefijo a los resultados.	"## Contexto adicional\nTenga en cuenta la siguiente información de los documentos de origen al responder al usuario:
CitasPrompt	string	La instrucción anexada después de los resultados para solicitar citas.	"Incluya citas al documento de origen con el nombre del documento y vincule si el nombre del documento y el vínculo están disponibles".
ContextFormatter	Func<IList<TextSearchProvider.TextSearchResult>, string>	Delegado opcional para personalizar completamente el formato de la lista de resultados. Si se proporciona y ContextPromptCitationsPrompt se omiten.	null
RecentMessageMemoryLimit	int	El número de mensajes de conversación recientes (tanto el usuario como el asistente) que se conservan en la memoria e incluyen al construir la entrada de búsqueda para BeforeAIInvoke las búsquedas.	0 (deshabilitado)
RecentMessageRolesIncluded	List<ChatRole>	Lista de ChatRole tipos a los que se van a filtrar los mensajes recientes a al decidir qué mensajes recientes se van a incluir al construir la entrada de búsqueda.	ChatRole.User

Tip

Consulte los ejemplos de .NET para obtener ejemplos completos de ejecución.

Agent Framework proporciona contratos nativos de almacén de vectores y create_vector_search_tool(). El asistente convierte cualquier SupportsVectorSearch implementación en una herramienta de función, por lo que el modelo puede recuperar los datos de puesta a tierra antes de responder.

Creación de una herramienta de búsqueda de vectores nativa

En primer lugar, defina el modelo de almacén de vectores, cree una colección y cargue sus registros. En el ejemplo siguiente se usa InMemoryCollection con OpenAIEmbeddingClient, pero puede proporcionar cualquier colección nativa de Agent Framework que implemente SupportsVectorSearch. A continuación, expone filtros opcionales de categoría y clasificación al modelo, asigna cada resultado al texto de base e indica al agente que busque 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)

El ejemplo completo define el Hotel modelo y carga los registros de origen antes de la configuración de la colección mostrada. Establezca OPENAI_API_KEY antes de ejecutarlo.

Personalización del comportamiento de búsqueda

Configure create_vector_search_tool() con las siguientes opciones:

Option	propósito
name	Establece el nombre de la función expuesto al modelo. Use un nombre único al agregar varias herramientas de búsqueda.
description	Explica cuándo y por qué el modelo debe usar la herramienta.
approval_mode	Establece la aprobación de herramientas en always_require o never_require.
search_type	vector Selecciona o keyword_hybrid busca. La colección debe admitir el modo seleccionado.
top y skip	Establezca valores fijos de paginación o use valores con Param tipo que proporciona el modelo.
filter	Aplica un portátil Filter o FilterGroup. Un filtro puede contener valores con Param tipo expuestos en el esquema de la herramienta.
result_mapper	Convierte cada en SearchResponse texto o multiproceso para Content el modelo.

La herramienta generada siempre incluye una query cadena. Los Param valores del filtro, topo skip la configuración se convierten en argumentos de herramienta validados adicionales. Use Literal restricciones numéricas y para mantener los valores proporcionados por el modelo dentro del intervalo que acepta la aplicación.

Puede crear varias herramientas para diferentes colecciones o modos de búsqueda. Asigne a cada herramienta un valor distinto name , por description lo que el modelo puede seleccionar el origen de conocimiento adecuado.

Elegir un almacén de vectores nativo

Las implementaciones de Python nativas están disponibles para la búsqueda en memoria, Búsqueda de Azure AI, PostgreSQL con pgvector, Qdrant y Redis. Sus modos de búsqueda, ciclo de vida del paquete, comandos de instalación y limitaciones difieren. Consulte Integraciones de almacén de vectores para seleccionar y configurar una implementación. Esa página también identifica las bases de datos que actualmente solo tienen un conector de Kernel semántico independiente.

Note

La compatibilidad con go para esta característica estará disponible próximamente. Consulte el repositorio de Agent Framework Go para obtener el estado más reciente.

Graph RAG

Para GraphRAG mediante la búsqueda enriquecida de grafos con consultas de Cypher, consulte el proveedor Neo4j GraphRAG.

Pasos siguientes

Agentes declarativos