代理中介軟體

Agent Framework 中的中介軟體提供了一種強大的方式，能攔截、修改及增強執行各階段的代理互動。您可以使用中介軟體來實作跨領域關注點，例如日誌記錄、安全驗證、錯誤處理和結果轉換，而無需修改核心代理程式或函數邏輯。

代理框架可透過三種不同類型的中介軟體進行客製化：

代理程式執行中介件：允許攔截所有代理程式執行，以便可以根據需要檢查和/或修改輸入和輸出。
函數呼叫中間件：允許攔截代理執行的所有函數調用，以便根據需要檢查和修改輸入和輸出。
IChatClient中介軟體：允許攔截執行執行IChatClientIChatClient者進行推論呼叫時的呼叫，例如當使用 ChatClientAgent。

所有類型的中間件都是透過函數回呼實現的，當註冊多個相同類型的中間件實例時，它們會形成一個鏈，其中每個中間件實例都期望透過提供的 nextFunc.

代理程式執行及函數呼叫中介軟體類型可以在代理程式上登錄，方法是將代理程式建置器與現有代理程式物件搭配使用。

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

這很重要

理想狀況下runFuncrunStreamingFunc兩者都應該提供。當只提供非串流中介軟體時，代理程式會同時使用它來執行串流與非串流的呼叫。串流只會在非串流模式下運行，以符合中介軟體的預期。

備註

還有一個額外的過載， 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。

以下是函數呼叫中介軟體的範例，它可以檢查和/或修改正在呼叫的函數，以及函數呼叫的結果。

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 呼叫物件以繼續處理。

備註

中介軟體順序與混合註冊範圍：

代理層級中介軟體會包裝執行層級的中介軟體。
對於代理中介軟體 [A1, A2] 與執行中介軟體 [R1, R2]，執行順序為： A1 -> A2 -> R1 -> R2 -> Agent -> R2 -> R1 -> A2 -> A1。
功能/聊天中介軟體在工具/聊天呼叫時遵循相同的包裝原則。