Add middleware tutorial and more bug fixes (#706)

* Add middleware tutorial and more bug fixes

* Add prerequisites section

Author: westey-m

agent-framework/tutorials/agents/agent-as-mcp-tool.md

@@ -29,7 +29,7 @@ dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 
-To add support for hosting a tool over the Model Context Protocol (MCP), all add the following Nuget packages
+To add support for hosting a tool over the Model Context Protocol (MCP), add the following Nuget packages
 
 ```powershell
 dotnet add package Microsoft.Extensions.Hosting --prerelease

agent-framework/tutorials/agents/enable-observability.md

@@ -16,13 +16,16 @@ ms.service: semantic-kernel
 This tutorial shows how to enable OpenTelemetry on an agent so that interactions with the agent are automatically logged and exported.
 In this tutorial, output is written to the console using the OpenTelemetry console exporter.
 
+> [!NOTE]
+> See [Semantic Conventions for GenAI agent and framework spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/) from Open Telemetry for more information about the standards followed by the Microsoft Agent Framework.
+
 ## Prerequisites
 
 For prerequisites, see the [Create and run a simple agent](./run-agent.md) step in this tutorial.
 
 ## Installing Nuget packages
 
-To use the AgentFramework with Azure OpenAI, you need to install the following NuGet packages:
+To use the Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```powershell
 dotnet add package Azure.Identity
@@ -39,8 +42,8 @@ dotnet add package OpenTelemetry.Exporter.Console
 
 ## Enable OpenTelemetry in your app
 
-Enable the agent framework telemetry and create an OpenTelemetry TracerProvider that exports to the console.
-Note that the tracerProvider must remain alive while you run the agent so traces are exported.
+Enable the agent framework telemetry and create an OpenTelemetry `TracerProvider` that exports to the console.
+Note that the `TracerProvider` must remain alive while you run the agent so traces are exported.
 
 ```csharp
 using System;
@@ -56,7 +59,7 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder()
 
 ## Create and instrument the agent
 
-Create an agent, then call `WithOpenTelemetry` to provide a source name.
+Create an agent, and using the builder pattern, call `UseOpenTelemetry` to provide a source name.
 Note that the string literal "agent-telemetry-source" is the OpenTelemetry source name
 that we used above, when we created the tracer provider.
 

agent-framework/tutorials/agents/middleware.md

@@ -15,7 +15,174 @@ Learn how to add middleware to your agents in a few simple steps. Middleware all
 
 ::: zone pivot="programming-language-csharp"
 
-Tutorial coming soon.
+## Prerequisites
+
+For prerequisites and installing nuget packages, see the [Create and run a simple agent](./run-agent.md) step in this tutorial.
+
+## Step 1: Create a Simple Agent
+
+First, let's create a basic agent with a function tool.
+
+```csharp
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+[Description("The current datetime offset.")]
+static string GetDateTime()
+    => DateTimeOffset.Now.ToString();
+
+AIAgent baseAgent = new AzureOpenAIClient(
+    new Uri("https://<myresource>.openai.azure.com"),
+    new AzureCliCredential())
+        .GetChatClient("gpt-4o-mini")
+        .CreateAIAgent(
+            instructions: "You are an AI assistant that helps people find information.",
+            tools: [AIFunctionFactory.Create(GetDateTime, name: nameof(GetDateTime))]);
+```
+
+## Step 2: Create Your Agent Run Middleware
+
+Next, we'll create a function that will get invoked for each agent run.
+It allows us to inspect the input and output from the agent.
+
+Unless the intention is to use the middleware to stop executing the run, the function
+should call `RunAsync` on the provided `innerAgent`.
+
+This sample middleware just inspects the input and output from the agent run and
+outputs the number of messages passed into and out of the agent.
+
+```csharp
+async Task<AgentRunResponse> CustomAgentRunMiddleware(
+    IEnumerable<ChatMessage> messages,
+    AgentThread? thread,
+    AgentRunOptions? options,
+    AIAgent innerAgent,
+    CancellationToken cancellationToken)
+{
+    Console.WriteLine(messages.Count());
+    var response = await innerAgent.RunAsync(messages, thread, options, cancellationToken).ConfigureAwait(false);
+    Console.WriteLine(response.Messages.Count);
+    return response;
+}
+```
+
+## Step 3: Add Agent Run Middleware to Your Agent
+
+To add this middleware function to the `baseAgent` we created in step 1,
+we should use the builder pattern.
+This creates a new agent that has the middleware applied.
+The original `baseAgent` is not modified.
+
+```csharp
+var middlewareEnabledAgent = baseAgent
+    .AsBuilder()
+        .Use(CustomAgentRunMiddleware)
+    .Build();
+```
+
+## Step 4: Create Function calling Middleware
+
+> [!NOTE]
+> Function calling middleware is currently only supported with an `AIAgent` that uses `Microsoft.Extensions.AI.FunctionInvokingChatClient`, e.g. `ChatClientAgent`.
+
+We can also create middleware that gets called for each function tool that is invoked.
+Here is an example of function calling middleware, that can inspect and/or modify the function being called, and the result from the function call.
+
+Unless the intention is to use the middleware to not execute the function tool, the middleware
+should call the provided `next` `Func`.
+
+```csharp
+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;
+}
+```
+
+## Step 5: Add Function calling Middleware to Your Agent
+
+Same as with adding agent run middleware, we can add function calling middleware as follows:
+
+```csharp
+var middlewareEnabledAgent = baseAgent
+    .AsBuilder()
+        .Use(CustomFunctionCallingMiddleware)
+    .Build();
+```
+
+Now, when executing the agent with a query that invokes a function, the middleware should get invoked,
+outputting the function name and call result.
+
+```csharp
+await middlewareEnabledAgent.RunAsync("What's the current time?");
+```
+
+## Step 6: Create Chat Client Middleware
+
+For agents that are built using `IChatClient` developers may want to intercept calls going from the agent to the `IChatClient`.
+In this case it is possible to use middleware for the `IChatClient`.
+
+Here is an example of chat client middleware, that can inspect and/or modify the input and output for the request to the inference service that the chat client provides.
+
+```csharp
+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;
+}
+```
+
+> [!NOTE]
+> For more information about `IChatClient` middleware, see [Custom IChatClient middleware](/dotnet/ai/microsoft-extensions-ai#custom-ichatclient-middleware)
+> in the Microsoft.Extensions.AI documentation.
+
+## Step 7: Add Chat client Middleware to an `IChatClient`
+
+To add middleware to your `IChatClient`, you can use the builder pattern.
+After adding the middleware, you can use the `IChatClient` with your agent as usual.
+
+```csharp
+var chatClient = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .AsIChatClient();
+
+var middlewareEnabledChatClient = chatClient
+    .AsBuilder()
+        .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
+    .Build();
+
+var agent = new ChatClientAgent(middlewareEnabledChatClient, instructions: "You are a helpful assistant.");
+```
+
+`IChatClient` middleware can also be registered using a factory method when constructing
+ an agent via one of the helper methods on SDK clients.
+
+```csharp
+var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .CreateAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
+        .AsBuilder()
+            .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
+        .Build());
+```
 
 ::: zone-end
 ::: zone pivot="programming-language-python"

agent-framework/user-guide/agents/agent-middleware.md

@@ -57,7 +57,7 @@ var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
     .GetChatClient(deploymentName)
     .CreateAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
         .AsBuilder()
-            .Use(getResponseFunc: ChatClientMiddleware, getStreamingResponseFunc: null)
+            .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
         .Build());
 ```
 
@@ -66,14 +66,16 @@ var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
 Here is an example of agent run middleware, that can inspect and/or modify the input and output from the agent run.
 
 ```csharp
-async Task<AgentRunResponse> PIIMiddleware(IEnumerable<ChatMessage> messages, AgentThread? thread, AgentRunOptions? options, AIAgent innerAgent, CancellationToken cancellationToken)
+async Task<AgentRunResponse> CustomAgentRunMiddleware(
+    IEnumerable<ChatMessage> messages,
+    AgentThread? thread,
+    AgentRunOptions? options,
+    AIAgent innerAgent,
+    CancellationToken cancellationToken)
 {
     Console.WriteLine(messages.Count());
-
     var response = await innerAgent.RunAsync(messages, thread, options, cancellationToken).ConfigureAwait(false);
-
     Console.WriteLine(response.Messages.Count);
-
     return response;
 }
 ```
@@ -113,7 +115,11 @@ If there were more than one function available for invocation during this iterat
 Here is an example of chat client middleware, that can inspect and/or modify the input and output for the request to the inference service that the chat client provides.
 
 ```csharp
-async Task<ChatResponse> CustomChatClientMiddleware(IEnumerable<ChatMessage> messages, ChatOptions? options, IChatClient innerChatClient, CancellationToken cancellationToken)
+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);