代理中间件

代理框架中的中间件提供了一种在执行的各个阶段截获、修改和增强代理交互的强大方法。可以使用中间件实现交叉问题，例如日志记录、安全验证、错误处理和结果转换，而无需修改核心代理或函数逻辑。

可以使用三种不同类型的中间件自定义代理框架：

代理运行中间件：允许截获所有代理运行，以便根据需要检查和/或修改输入和输出。
函数调用中间件：允许截获代理执行的所有函数调用，以便根据需要检查和修改输入和输出。
IChatClient 中间件：允许截获对 IChatClient 实现的调用，其中代理用于 IChatClient 推理调用，例如，使用 ChatClientAgent时。

所有类型的中间件都通过函数回调实现，当注册同一类型的多个中间件实例时，它们会形成一个链，其中每个中间件实例应通过提供的 nextFunc链调用下一个中间件实例。

代理运行和函数调用中间件类型可以在代理上注册，方法是将代理生成器与现有代理对象一起使用。

var middlewareEnabledAgent = originalAgent
    .AsBuilder()
        .Use(runFunc: CustomAgentRunMiddleware, runStreamingFunc: CustomAgentRunStreamingMiddleware)
        .Use(CustomFunctionCallingMiddleware)
    .Build();

重要

理想情况下，应同时 runFunc 提供并 runStreamingFunc 应提供。仅提供非流式处理中间件时，代理将使用它进行流式处理和非流式处理调用。流式处理仅在非流式处理模式下运行，以满足中间件预期。

注释

有一个额外的重载， Use(sharedFunc: ...)使你可以为非流式处理和流式处理提供相同的中间件，而不会阻止流式处理。但是，共享中间件无法截获或替代输出。此重载应用于仅在到达代理之前检查或修改输入的情况。

IChatClient中间件可以在与聊天客户端生成器模式一起使用IChatClient之前先在中间ChatClientAgent件上注册。

var chatClient = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

var middlewareEnabledChatClient = chatClient
    .AsBuilder()
        .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
    .Build();

var agent = new ChatClientAgent(middlewareEnabledChatClient, instructions: "You are a helpful assistant.");

警告

DefaultAzureCredential 对于开发来说很方便，但在生产中需要仔细考虑。在生产环境中，请考虑使用特定凭据（例如）， ManagedIdentityCredential以避免延迟问题、意外凭据探测以及回退机制的潜在安全风险。

IChatClient 当通过 SDK 客户端上的某个帮助程序方法构造代理时，还可以使用工厂方法注册中间件。

var agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
        .AsBuilder()
            .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
        .Build());

代理运行中间件

下面是代理运行中间件的示例，可以检查和/或修改代理运行的输入和输出。

async Task<AgentResponse> CustomAgentRunMiddleware(
    IEnumerable<ChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    CancellationToken cancellationToken)
{
    Console.WriteLine(messages.Count());
    var response = await innerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
    Console.WriteLine(response.Messages.Count);
    return response;
}

代理运行流式处理中间件

下面是代理运行流式处理中间件的示例，它可以检查和/或修改代理流式处理运行的输入和输出。

    async IAsyncEnumerable<AgentResponseUpdate> CustomAgentRunStreamingMiddleware(
    IEnumerable<ChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    Console.WriteLine(messages.Count());
    List<AgentResponseUpdate> updates = [];
    await foreach (var update in innerAgent.RunStreamingAsync(messages, session, options, cancellationToken))
    {
        updates.Add(update);
        yield return update;
    }

    Console.WriteLine(updates.ToAgentResponse().Messages.Count);
}

函数调用中间件

注释

函数调用中间件目前仅支持使用 AIAgent 的 FunctionInvokingChatClient ，例如 ChatClientAgent。

下面是函数调用中间件的示例，可以检查和/或修改所调用的函数，以及函数调用的结果。

async ValueTask<object?> CustomFunctionCallingMiddleware(
    AIAgent agent,
    FunctionInvocationContext context,
    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
    CancellationToken cancellationToken)
{
    Console.WriteLine($"Function Name: {context!.Function.Name}");
    var result = await next(context, cancellationToken);
    Console.WriteLine($"Function Call Result: {result}");

    return result;
}

通过将提供的 FunctionInvocationContext.Terminate 设置为 true，可以使用函数调用中间件终止函数调用循环。这将阻止函数调用循环向推理服务发出请求，其中包含函数调用后函数调用结果。如果在此迭代期间有多个可用于调用的函数，则它还可能会阻止执行任何剩余函数。

警告

终止函数调用循环可能会导致聊天历史记录处于不一致状态，例如，包含没有函数结果内容的函数调用内容。这可能会导致聊天历史记录无法进一步运行。

IChatClient 中间件

下面是聊天客户端中间件的示例，可以检查和/或修改聊天客户端提供的推理服务请求的输入和输出。

async Task<ChatResponse> CustomChatClientMiddleware(
    IEnumerable<ChatMessage> messages,
    ChatOptions? options,
    IChatClient innerChatClient,
    CancellationToken cancellationToken)
{
    Console.WriteLine(messages.Count());
    var response = await innerChatClient.GetResponseAsync(messages, options, cancellationToken);
    Console.WriteLine(response.Messages.Count);

    return response;
}

小窍门

有关完整的可运行示例，请参阅 .NET 示例。

注释

有关中间件的详细信息 IChatClient ，请参阅自定义 IChatClient 中间件。

可以使用三种不同类型的中间件自定义代理框架：

代理中间件：截获代理运行执行，允许检查和修改输入、输出和控制流。
函数中间件：在代理执行期间截获函数（工具）调用，启用输入验证、结果转换和执行控制。
聊天中间件：截获发送到 AI 模型的基础聊天请求，提供对原始消息、选项和响应的访问权限。

所有类型都支持基于函数的实现和基于类的实现。注册同一类型的多个中间件时，它们会形成一个链，其中每个中间件调用 next 可调用方以继续处理。