Suggestions for Tutorials/Agents (#729)

* Suggestions for Tutorials/Agents

* More suggestions

Author: jozkee

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

@@ -17,7 +17,7 @@ This tutorial shows you how to expose an agent as a tool over the Model Context
 
 ## Prerequisites
 
-For prerequisites see the [Create and run a simple agent](./run-agent.md) step in this tutorial.
+For prerequisites see the [Create and run a simple agent](./run-agent.md#prerequisites) step in this tutorial.
 
 ## Install NuGet packages
 
@@ -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), add the following NuGet packages
+To also add support for hosting a tool over the Model Context Protocol (MCP), add the following NuGet packages
 
 ```dotnetcli
 dotnet add package Microsoft.Extensions.Hosting --prerelease
@@ -69,6 +69,7 @@ Setup the MCP server to listen for incoming requests over standard input/output
 ```csharp
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
+using ModelContextProtocol.Server;
 
 HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(settings: null);
 builder.Services

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

@@ -21,11 +21,11 @@ In this tutorial, output is written to the console using the OpenTelemetry conso
 
 ## Prerequisites
 
-For prerequisites, see the [Create and run a simple agent](./run-agent.md) step in this tutorial.
+For prerequisites, see the [Create and run a simple agent](./run-agent.md#prerequisites) step in this tutorial.
 
 ## Install NuGet packages
 
-To use Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
+To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
 dotnet add package Azure.Identity
@@ -98,20 +98,24 @@ Activity.Kind:               Client
 Activity.StartTime:          2025-09-18T11:00:48.6636883Z
 Activity.Duration:           00:00:08.6077009
 Activity.Tags:
-    gen_ai.operation.name: invoke_agent
-    gen_ai.system: openai
-    gen_ai.agent.id: e1370f89-3ca8-4278-bce0-3a3a2b22f407
+    gen_ai.operation.name: chat
+    gen_ai.request.model: gpt-4o-mini
+    gen_ai.provider.name: openai
+    server.address: <myresource>.openai.azure.com
+    server.port: 443
+    gen_ai.agent.id: 19e310a72fba4cc0b257b4bb8921f0c7
     gen_ai.agent.name: Joker
-    gen_ai.request.instructions: You are good at telling jokes.
+    gen_ai.response.finish_reasons: ["stop"]
     gen_ai.response.id: chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5
+    gen_ai.response.model: gpt-4o-mini-2024-07-18
     gen_ai.usage.input_tokens: 26
     gen_ai.usage.output_tokens: 29
 Instrumentation scope (ActivitySource):
-    Name: c8aeb104-0ce7-49b3-bf45-d71e5bf782d1
+    Name: agent-telemetry-source
 Resource associated with Activity:
     telemetry.sdk.name: opentelemetry
     telemetry.sdk.language: dotnet
-    telemetry.sdk.version: 1.12.0
+    telemetry.sdk.version: 1.13.1
     service.name: unknown_service:Agent_Step08_Telemetry
 
 Why did the pirate go to school?

agent-framework/tutorials/agents/memory.md

@@ -27,9 +27,9 @@ For prerequisites and installing NuGet packages, see the [Create and run a simpl
 `AIContextProvider` is an abstract class that you can inherit from, and which can be associated with the `AgentThread` for a `ChatClientAgent`.
 It allows you to:
 
-1. run custom logic before and after the agent invokes the underlying inference service
-1. provide additional context to the agent before it invokes the underlying inference service
-1. inspect all messages provided to and produced by the agent
+1. Run custom logic before and after the agent invokes the underlying inference service.
+1. Provide additional context to the agent before it invokes the underlying inference service.
+1. Inspect all messages provided to and produced by the agent.
 
 ### Pre and post invocation events
 
@@ -63,12 +63,20 @@ internal sealed class UserInfo
 Then you can implement the `AIContextProvider` to manage the memories.
 The `UserInfoMemory` class below contains the following behavior:
 
-1. It uses a `IChatClient` to look for the user's name and age in user messages when new messages are added to the thread at the end of each run.
+1. It uses an `IChatClient` to look for the user's name and age in user messages when new messages are added to the thread at the end of each run.
 1. It provides any current memories to the agent before each invocation.
-1. If not memories are available, it instructs the agent to ask the user for the missing information, and not to answer any questions until the information is provided.
+1. If no memories are available, it instructs the agent to ask the user for the missing information, and not to answer any questions until the information is provided.
 1. It also implements serialization to allow persisting the memories as part of the thread state.
 
 ```csharp
+using System.Linq;
+using System.Text;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
 internal sealed class UserInfoMemory : AIContextProvider
 {
     private readonly IChatClient _chatClient;
@@ -140,6 +148,12 @@ To use the custom `AIContextProvider`, you need to provide an `AIContextProvider
 When creating a `ChatClientAgent` it is possible to provide a `ChatClientAgentOptions` object that allows providing the `AIContextProviderFactory` in addition to all other agent options.
 
 ```csharp
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using OpenAI.Chat;
+using OpenAI;
+
 ChatClient chatClient = new AzureOpenAIClient(
     new Uri("https://<myresource>.openai.azure.com"),
     new AzureCliCredential())
@@ -189,9 +203,9 @@ For prerequisites and installing packages, see the [Create and run a simple agen
 `ContextProvider` is an abstract class that you can inherit from, and which can be associated with an `AgentThread` for a `ChatAgent`.
 It allows you to:
 
-1. run custom logic before and after the agent invokes the underlying inference service
-1. provide additional context to the agent before it invokes the underlying inference service
-1. inspect all messages provided to and produced by the agent
+1. Run custom logic before and after the agent invokes the underlying inference service.
+1. Provide additional context to the agent before it invokes the underlying inference service.
+1. Inspect all messages provided to and produced by the agent.
 
 ### Pre and post invocation events
 

agent-framework/tutorials/agents/middleware.md

@@ -25,6 +25,7 @@ First, create a basic agent with a function tool.
 
 ```csharp
 using System;
+using System.ComponentModel;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
@@ -56,16 +57,21 @@ 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
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+
 async Task<AgentRunResponse> CustomAgentRunMiddleware(
     IEnumerable<ChatMessage> messages,
     AgentThread? thread,
     AgentRunOptions? options,
     AIAgent innerAgent,
     CancellationToken cancellationToken)
 {
-    Console.WriteLine(messages.Count());
+    Console.WriteLine($"Input: {messages.Count()}");
     var response = await innerAgent.RunAsync(messages, thread, options, cancellationToken).ConfigureAwait(false);
-    Console.WriteLine(response.Messages.Count);
+    Console.WriteLine($"Output: {response.Messages.Count}");
     return response;
 }
 ```
@@ -79,10 +85,17 @@ The original `baseAgent` is not modified.
 ```csharp
 var middlewareEnabledAgent = baseAgent
     .AsBuilder()
-        .Use(CustomAgentRunMiddleware)
+        .Use(runFunc: CustomAgentRunMiddleware, runStreamingFunc: null)
     .Build();
 ```
 
+Now, when executing the agent with a query, the middleware should get invoked,
+outputting the number of input messages and the number of response messages.
+
+```csharp
+Console.WriteLine(await middlewareEnabledAgent.RunAsync("What's the current time?"));
+```
+
 ## Step 4: Create Function calling Middleware
 
 > [!NOTE]
@@ -94,6 +107,9 @@ Here's an example of function-calling middleware that can inspect and/or modify
 Unless the intention is to use the middleware to not execute the function tool, the middleware should call the provided `next` `Func`.
 
 ```csharp
+using System.Threading;
+using System.Threading.Tasks;
+
 async ValueTask<object?> CustomFunctionCallingMiddleware(
     AIAgent agent,
     FunctionInvocationContext context,
@@ -123,7 +139,7 @@ Now, when executing the agent with a query that invokes a function, the middlewa
 outputting the function name and call result.
 
 ```csharp
-await middlewareEnabledAgent.RunAsync("What's the current time?");
+Console.WriteLine(await middlewareEnabledAgent.RunAsync("What's the current time?"));
 ```
 
 ## Step 6: Create Chat Client Middleware
@@ -134,15 +150,20 @@ In this case, it's 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
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+
 async Task<ChatResponse> CustomChatClientMiddleware(
     IEnumerable<ChatMessage> messages,
     ChatOptions? options,
     IChatClient innerChatClient,
     CancellationToken cancellationToken)
 {
-    Console.WriteLine(messages.Count());
+    Console.WriteLine($"Input: {messages.Count()}");
     var response = await innerChatClient.GetResponseAsync(messages, options, cancellationToken);
-    Console.WriteLine(response.Messages.Count);
+    Console.WriteLine($"Output: {response.Messages.Count}");
 
     return response;
 }
@@ -158,7 +179,7 @@ After adding the middleware, you can use the `IChatClient` with your agent as us
 
 ```csharp
 var chatClient = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new AzureCliCredential())
-    .GetChatClient(deploymentName)
+    .GetChatClient("gpt-4o-mini")
     .AsIChatClient();
 
 var middlewareEnabledChatClient = chatClient
@@ -173,8 +194,8 @@ var agent = new ChatClientAgent(middlewareEnabledChatClient, instructions: "You
  an agent via one of the helper methods on SDK clients.
 
 ```csharp
-var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetChatClient(deploymentName)
+var agent = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new AzureCliCredential())
+    .GetChatClient("gpt-4o-mini")
     .CreateAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
         .AsBuilder()
             .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)

agent-framework/tutorials/agents/persisted-conversation.md

@@ -48,16 +48,15 @@ Run the agent, passing in the thread, so that the `AgentThread` includes this ex
 Console.WriteLine(await agent.RunAsync("Tell me a short pirate joke.", thread));
 ```
 
-Call the SerializeAsync method on the thread to serialize it to a JsonElement.
+Call the `Serialize` method on the thread to serialize it to a JsonElement.
 It can then be converted to a string for storage and saved to a database, blob storage, or file.
 
 ```csharp
 using System.IO;
 using System.Text.Json;
 
 // Serialize the thread state
-JsonElement serializedThread = thread.Serialize();
-string serializedJson = JsonSerializer.Serialize(serializedThread, JsonSerializerOptions.Web);
+string serializedJson = thread.Serialize(JsonSerializerOptions.Web).GetRawText();
 
 // Example: save to a local file (replace with DB or blob storage in production)
 string filePath = Path.Combine(Path.GetTempPath(), "agent_thread.json");
@@ -73,10 +72,10 @@ additional functionality that is specific to that agent type.
 ```csharp
 // Read persisted JSON
 string loadedJson = await File.ReadAllTextAsync(filePath);
-JsonElement reloaded = JsonSerializer.Deserialize<JsonElement>(loadedJson);
+JsonElement reloaded = JsonSerializer.Deserialize<JsonElement>(loadedJson, JsonSerializerOptions.Web);
 
 // Deserialize the thread into an AgentThread tied to the same agent type
-AgentThread resumedThread = agent.DeserializeThread(reloaded);
+AgentThread resumedThread = agent.DeserializeThread(reloaded, JsonSerializerOptions.Web);
 ```
 
 Use the resumed thread to continue the conversation.

agent-framework/tutorials/agents/run-agent.md

@@ -22,7 +22,7 @@ This tutorial shows you how to create and run an agent with Agent Framework, bas
 
 Before you begin, ensure you have the following prerequisites:
 
-- [.NET 8.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
+- [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
 - [Azure OpenAI service endpoint and deployment configured](/azure/ai-foundry/openai/how-to/create-resource)
 - [Azure CLI installed](/cli/azure/install-azure-cli) and [authenticated (for Azure credential authentication)](/cli/azure/authenticate-azure-cli)
 - [User has the `Cognitive Services OpenAI User` or `Cognitive Services OpenAI Contributor` roles for the Azure OpenAI resource.](/azure/ai-foundry/openai/how-to/role-based-access-control)

agent-framework/tutorials/agents/third-party-chat-history-storage.md

@@ -33,11 +33,10 @@ dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 
-In addition, you'll use the in-memory vector store to store chat messages and a utility package for async LINQ operations.
+In addition, you'll use the in-memory vector store to store chat messages.
 
 ```dotnetcli
 dotnet add package Microsoft.SemanticKernel.Connectors.InMemory --prerelease
-dotnet add package System.Linq.Async
 ```
 
 ## Create a custom ChatMessage Store
@@ -83,6 +82,7 @@ using System.Linq;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
 using Microsoft.SemanticKernel.Connectors.InMemory;
@@ -127,13 +127,18 @@ internal sealed class VectorChatMessageStore : ChatMessageStore
     {
         var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
         await collection.EnsureCollectionExistsAsync(cancellationToken);
-        var records = await collection
+        var records = collection
             .GetAsync(
                 x => x.ThreadId == this.ThreadDbKey, 10,
                 new() { OrderBy = x => x.Descending(y => y.Timestamp) },
-                cancellationToken)
-            .ToListAsync(cancellationToken);
-        var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!);
+                cancellationToken);
+
+        List<ChatMessage> messages = [];
+        await foreach (var record in records)
+        {
+            messages.Add(JsonSerializer.Deserialize<ChatMessage>(record.SerializedMessage!)!);
+        }
+        
         messages.Reverse();
         return messages;
     }
@@ -165,6 +170,10 @@ To use the custom `ChatMessageStore`, you need to provide a `ChatMessageStoreFac
 When creating a `ChatClientAgent` it is possible to provide a `ChatClientAgentOptions` object that allows providing the `ChatMessageStoreFactory` in addition to all other agent options.
 
 ```csharp
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using OpenAI;
+
 AIAgent agent = new AzureOpenAIClient(
     new Uri("https://<myresource>.openai.azure.com"),
     new AzureCliCredential())