代理检索扩充生成（RAG）

Microsoft Agent Framework 支持通过将 AI 上下文提供程序添加到代理，轻松地向代理添加检索增强生成（RAG）功能。

使用 TextSearchProvider

该 TextSearchProvider 类是 RAG 上下文提供程序的现用实现。

它可以轻松地附加到 ChatClientAgent 使用 AIContextProviderFactory 选项向代理提供 RAG 功能。

// Create the AI agent with the TextSearchProvider as the AI context provider.
AIAgent agent = azureOpenAIClient
    .GetChatClient(deploymentName)
    .CreateAIAgent(new ChatClientAgentOptions
    {
        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)
    });

需要 TextSearchProvider 一个提供给定查询的搜索结果的函数。这可以使用任何搜索技术（例如 Azure AI 搜索或 Web 搜索引擎）来实现。

下面是基于查询返回预定义结果的模拟搜索函数的示例。 SourceName 并且 SourceLink 是可选的，但是如果代理将在回答用户的问题时引用信息的来源，则为可选。

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

TextSearchProvider 选项

TextSearchProvider可以通过类自定义TextSearchProviderOptions该类。下面是创建选项以在每个模型调用之前运行搜索的选项，并保留对话上下文的简短滚动窗口的示例。

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

该 TextSearchProvider 类通过 TextSearchProviderOptions 类支持以下选项。

选项	类型	Description	违约
SearchTime	`TextSearchProviderOptions.TextSearchBehavior`	指示何时应执行搜索。每次调用代理或通过函数调用按需时，都有两个选项。	`TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke`
FunctionToolName	`string`	在按需模式下运行时公开的搜索工具的名称。	“搜索”
FunctionToolDescription	`string`	在按需模式下运行时公开的搜索工具的说明。	“允许搜索其他信息来帮助回答用户问题。
ContextPrompt	`string`	在模式下运行时 `BeforeAIInvoke` ，上下文提示前缀为结果。	“## 其他上下文\n响应用户时，请考虑源文档中的以下信息：
CitationsPrompt	`string`	在模式下运行时 `BeforeAIInvoke` ，在结果后面追加指令以请求引文。	“如果文档名称和链接可用，请包含指向源文档的引文和链接。
ContextFormatter	`Func<IList<TextSearchProvider.TextSearchResult>, string>`	可选委托，用于在模式下运行时 `BeforeAIInvoke` 完全自定义结果列表的格式。如果提供， `ContextPrompt` 则 `CitationsPrompt` 忽略。	`null`
RecentMessageMemoryLimit	`int`	要保留在内存中的最近聊天消息（用户和助手）的数量，并在构造搜索输入 `BeforeAIInvoke` 时包括。	`0` （已禁用）
RecentMessageRolesIncluded	`List<ChatRole>`	在决定构造搜索输入时要包含哪些最近消息时筛选最近消息的类型列表 `ChatRole` 。	`ChatRole.User`

将语义内核 VectorStore 与代理框架配合使用

代理框架支持使用语义内核的 VectorStore 集合向代理提供 RAG 功能。这是通过将语义内核搜索函数转换为 Agent Framework 工具的网桥功能实现的。

重要

此功能需要 semantic-kernel 版本 1.38 或更高版本。

从 VectorStore 创建搜索工具

语义内核 VectorStore 集合中的方法返回一个可以使用 /a0> 转换为 Agent Framework 工具的方法。使用矢量存储连接器文档了解如何设置不同的向量存储集合。

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)

自定义搜索行为

可以使用各种选项自定义搜索函数：

# 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}",
)

有关可用 create_search_function参数的完整详细信息，请参阅语义内核文档。

使用多个搜索函数

可以为不同知识域的代理提供多个搜索工具：

# 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]
)

还可以使用不同的说明和参数从同一集合创建多个搜索函数，以提供专用搜索功能：

# 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]
)

此方法允许代理根据用户的查询选择最合适的搜索策略。

支持的 VectorStore 连接器

此模式适用于任何语义内核 VectorStore 连接器，包括：

Azure AI 搜索（AzureAISearchCollection）
Qdrant （QdrantCollection）
派恩康（PineconeCollection）
Redis （RedisCollection）
Weaviate （WeaviateCollection）
In-Memory （InMemoryVectorStoreCollection）
更多

每个连接器提供可以桥接到 Agent Framework 工具的相同 create_search_function 方法，使你能够选择最符合需求的向量数据库。请参阅此处的完整列表。

后续步骤

代理聊天历史记录和内存

反馈

此页面是否有帮助？

Last updated on 2025-11-11