Merge pull request #740 from MicrosoftDocs/main

Merge latest doc updates from main to live

Author: SergeyMenshykh

agent-framework/migration-guide/from-autogen/index.md

@@ -974,9 +974,9 @@ async def join_any(msg: str, ctx: WorkflowContext[Never, str]) -> None:
 
 @executor(id="join_all")
 async def join_all(msg: str, ctx: WorkflowContext[str, str]) -> None:
-    state = await ctx.get_state() or {"items": []}
+    state = await ctx.get_executor_state() or {"items": []}
     state["items"].append(msg)
-    await ctx.set_state(state)
+    await ctx.set_executor_state(state)
     if len(state["items"]) >= 2:
         await ctx.yield_output(" | ".join(state["items"]))  # ALL join
 
@@ -1404,7 +1404,7 @@ AutoGen's `Team` abstraction does not provide built-in checkpointing capabilitie
 
 Agent Framework provides comprehensive checkpointing through `FileCheckpointStorage` and the `with_checkpointing()` method on `WorkflowBuilder`. Checkpoints capture:
 
-- **Executor state**: Local state for each executor using `ctx.set_state()`
+- **Executor state**: Local state for each executor using `ctx.set_executor_state()`
 - **Shared state**: Cross-executor state using `ctx.set_shared_state()`
 - **Message queues**: Pending messages between executors
 - **Workflow position**: Current execution progress and next steps
@@ -1424,9 +1424,9 @@ class ProcessingExecutor(Executor):
         print(f"Processing: '{data}' -> '{result}'")
 
         # Persist executor-local state
-        prev_state = await ctx.get_state() or {}
+        prev_state = await ctx.get_executor_state() or {}
         count = prev_state.get("count", 0) + 1
-        await ctx.set_state({
+        await ctx.set_executor_state({
             "count": count,
             "last_input": data,
             "last_output": result

agent-framework/migration-guide/from-semantic-kernel/samples.md

@@ -13,7 +13,7 @@ ms.service: agent-framework
 
 ::: zone pivot="programming-language-csharp"
 
-See the [Agent Framework repository](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/SemanticKernelMigration) for detailed per agent type code samples showing the the Agent Framework equivalent code for Semantic Kernel features.
+See the [Semantic Kernel repository](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/samples/AgentFrameworkMigration) for detailed per agent type code samples showing the the Agent Framework equivalent code for Semantic Kernel features.
 
 ::: zone-end
 ::: zone pivot="programming-language-python"

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

@@ -17,19 +17,19 @@ 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
 
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-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,15 +21,15 @@ 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.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 
@@ -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)
@@ -38,8 +38,8 @@ Before you begin, ensure you have the following prerequisites:
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 

agent-framework/tutorials/agents/structured-output.md

@@ -30,15 +30,15 @@ The `ChatClientAgent` uses the support for structured output that's provided by
 When creating the agent, you have the option to provide the default <xref:Microsoft.Extensions.AI.ChatOptions> instance to use for the underlying chat client.
 This `ChatOptions` instance allows you to pick a preferred <xref:Microsoft.Extensions.AI.ChatResponseFormat>.
 
-Various options are supported:
+Various options for `ResponseFormat` are available:
 
-- <xref:Microsoft.Extensions.AI.ChatResponseFormat.Text?displayProperty=nameWithType>: The response will be plain text.
-- <xref:Microsoft.Extensions.AI.ChatResponseFormat.Json?displayProperty=nameWithType>: The response will be a JSON object without any particular schema.
-- <xref:Microsoft.Extensions.AI.ChatResponseFormatJson>: The response will be a JSON object that conforms to the provided schema.
+- A built-in <xref:Microsoft.Extensions.AI.ChatResponseFormat.Text?displayProperty=nameWithType> property: The response will be plain text.
+- A built-in <xref:Microsoft.Extensions.AI.ChatResponseFormat.Json?displayProperty=nameWithType> property: The response will be a JSON object without any particular schema.
+- A custom <xref:Microsoft.Extensions.AI.ChatResponseFormatJson> instance: The response will be a JSON object that conforms to a specific schema.
 
 This example creates an agent that produces structured output in the form of a JSON object that conforms to a specific schema.
 
-The easiest way to produce the schema is to define a C# class that represents the structure of the output you want from the agent, and then use the `AIJsonUtilities.CreateJsonSchema` method to create a schema from the type.
+The easiest way to produce the schema is to define a type that represents the structure of the output you want from the agent, and then use the `AIJsonUtilities.CreateJsonSchema` method to create a schema from the type.
 
 ```csharp
 using System.Text.Json;
@@ -47,13 +47,8 @@ using Microsoft.Extensions.AI;
 
 public class PersonInfo
 {
-    [JsonPropertyName("name")]
     public string? Name { get; set; }
-
-    [JsonPropertyName("age")]
     public int? Age { get; set; }
-
-    [JsonPropertyName("occupation")]
     public string? Occupation { get; set; }
 }
 
@@ -67,7 +62,7 @@ using Microsoft.Extensions.AI;
 
 ChatOptions chatOptions = new()
 {
-    ResponseFormat = ChatResponseFormatJson.ForJsonSchema(
+    ResponseFormat = ChatResponseFormat.ForJsonSchema(
         schema: schema,
         schemaName: "PersonInfo",
         schemaDescription: "Information about a person including their name, age, and occupation")