Merge pull request #809 from MicrosoftDocs/main

Merge main to live

Author: markwallace-microsoft

agent-framework/docfx.json

@@ -21,6 +21,23 @@
         ]
       }
     ],
+    "ms.update-cycle": {
+      "agent-framework/api-docs/*.md": "180-days",
+      "agent-framework/api-docs/*.yml": "180-days",
+      "agent-framework/tutorials/**/*.md": "180-days",
+      "agent-framework/tutorials/**/*.yml": "180-days",
+      "agent-framework/migration-guide/**/*.md": "180-days",
+      "agent-framework/migration-guide/**/*.yml": "180-days",
+      "agent-framework/overview/*.md": "180-days",
+      "agent-framework/overview/*.yml": "180-days",
+      "agent-framework/user-guide/**/*.md": "180-days",
+      "agent-framework/user-guide/**/*.yml": "180-days",
+      "agent-framework/integrations/*.md": "180-days",
+      "agent-framework/integrations/*.yml": "180-days",
+      "agent-framework/support/**/*.md": "180-days",
+      "agent-framework/support/**/*.yml": "180-days"
+    },
+  
     "resource": [
       {
         "files": [
@@ -49,7 +66,42 @@
       "feedback_system": "Standard",
       "permissioned-type": "public"
     },
-    "fileMetadata": {},
+    "fileMetadata": {
+      "ms.collection": {
+        "api-docs/**/*.md": "ce-skilling-ai-copilot",
+        "api-docs/**/*.yml": "ce-skilling-ai-copilot",
+        "integrations/**/*.md": "ce-skilling-ai-copilot",
+        "integrations/**/*.yml": "ce-skilling-ai-copilot",
+        "migration-guide/**/*.md": "ce-skilling-ai-copilot",
+        "migration-guide/**/*.yml": "ce-skilling-ai-copilot",
+        "overview/**/*.md": "ce-skilling-ai-copilot",
+        "overview/**/*.yml": "ce-skilling-ai-copilot",
+        "support/**/*.md": "ce-skilling-ai-copilot",
+        "support/**/*.yml": "ce-skilling-ai-copilot",
+        "tutorials/**/*.md": "ce-skilling-ai-copilot",
+        "tutorials/**/*.yml": "ce-skilling-ai-copilot",
+        "user-guide/**/*.md": "ce-skilling-ai-copilot",
+        "user-guide/**/*.yml": "ce-skilling-ai-copilot",
+        "index.yml": "ce-skilling-ai-copilot"        
+      },
+      "ms.update-cycle": {
+        "api-docs/**/*.md": "180-days",
+        "api-docs/**/*.yml": "180-days",
+        "integrations/**/*.md": "180-days",
+        "integrations/**/*.yml": "180-days",
+        "migration-guide/**/*.md": "180-days",
+        "migration-guide/**/*.yml": "180-days",
+        "overview/**/*.md": "180-days",
+        "overview/**/*.yml": "180-days",
+        "support/**/*.md": "180-days",
+        "support/**/*.yml": "180-days",
+        "tutorials/**/*.md": "180-days",
+        "tutorials/**/*.yml": "180-days",
+        "user-guide/**/*.md": "180-days",
+        "user-guide/**/*.yml": "180-days",
+        "index.yml": "180-days"
+      }
+    },
     "template": [],
     "dest": "agent-framework"
   }

agent-framework/overview/agent-framework-overview.md

@@ -54,13 +54,13 @@ and the same is expected for Agent Framework. Microsoft Agent Framework welcomes
 
 ## Installation
 
-Python:
+:::no-loc text="Python:":::
 
 ```bash
 pip install agent-framework --pre
 ```
 
-.NET:
+:::no-loc text=".NET:":::
 
 ```dotnetcli
 dotnet add package Microsoft.Agents.AI

agent-framework/tutorials/agents/memory.md

@@ -17,7 +17,6 @@ This tutorial shows how to add memory to an agent by implementing an `AIContextP
 > [!IMPORTANT]
 > Not all agent types support `AIContextProvider`. This step uses a `ChatClientAgent`, which does support `AIContextProvider`.
 
-
 ## Prerequisites
 
 For prerequisites and installing NuGet packages, see the [Create and run a simple agent](./run-agent.md) step in this tutorial.
@@ -161,7 +160,7 @@ ChatClient chatClient = new AzureOpenAIClient(
 
 AIAgent agent = chatClient.CreateAIAgent(new ChatClientAgentOptions()
 {
-    Instructions = "You are a friendly assistant. Always address the user by their name.",
+    ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
     AIContextProviderFactory = ctx => new UserInfoMemory(
         chatClient.AsIChatClient(),
         ctx.SerializedState,

agent-framework/tutorials/agents/orchestrate-durable-agents.md

@@ -235,31 +235,31 @@ def agent_orchestration_workflow(context: df.DurableOrchestrationContext):
     Returns a dictionary with the original response and translations.
     """
     input_text = context.get_input()
-    
+
     # Step 1: Get the main agent's response
     main_agent = app.get_agent(context, "MyDurableAgent")
     main_response = yield main_agent.run(input_text)
-    agent_response = main_response.get("response", "")
-    
+    agent_response = main_response.text
+
     # Step 2: Fan out - get the translation agents and run them concurrently
     french_agent = app.get_agent(context, "FrenchTranslator")
     spanish_agent = app.get_agent(context, "SpanishTranslator")
-    
+
     parallel_tasks = [
         french_agent.run(agent_response),
         spanish_agent.run(agent_response)
     ]
-    
+
     # Step 3: Wait for both translation tasks to complete (fan-in)
-    translations = yield context.task_all(parallel_tasks)
-    
+    translations = yield context.task_all(parallel_tasks) # type: ignore
+
     # Step 4: Combine results into a dictionary
     result = {
         "original": agent_response,
-        "french": translations[0].get("response", ""),
-        "spanish": translations[1].get("response", "")
+        "french": translations[0].text,
+        "spanish": translations[1].text
     }
-    
+
     return result
 ```
 

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

@@ -177,20 +177,20 @@ using OpenAI;
 AIAgent agent = new AzureOpenAIClient(
     new Uri("https://<myresource>.openai.azure.com"),
     new AzureCliCredential())
-     .GetChatClient("gpt-4o-mini")
-     .CreateAIAgent(new ChatClientAgentOptions
-     {
-         Name = "Joker",
-         Instructions = "You are good at telling jokes.",
-         ChatMessageStoreFactory = ctx =>
-         {
-             // Create a new chat message store for this agent that stores the messages in a vector store.
-             return new VectorChatMessageStore(
+    .GetChatClient("gpt-4o-mini")
+    .CreateAIAgent(new ChatClientAgentOptions
+    {
+        Name = "Joker",
+        ChatOptions = new() { Instructions = "You are good at telling jokes." },
+        ChatMessageStoreFactory = ctx =>
+        {
+            // Create a new chat message store for this agent that stores the messages in a vector store.
+            return new VectorChatMessageStore(
                 new InMemoryVectorStore(),
                 ctx.SerializedState,
                 ctx.JsonSerializerOptions);
-         }
-     });
+        }
+    });
 ```
 
 ::: zone-end

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

@@ -17,18 +17,18 @@ Agent chat history and memory are crucial capabilities that allow agents to main
 
 ## Chat History
 
-Various chat history storage options are supported by the Agent Framework. The available options vary by agent type and the underlying service(s) used to build the agent.
+Various chat history storage options are supported by Agent Framework. The available options vary by agent type and the underlying service(s) used to build the agent.
 
-Here are the two main scenarios supported:
+The two main supported scenarios are:
 
-1. **In-memory storage**: Agent is built on a service that does not support in-service storage of chat history (e.g. OpenAI Chat Completion). The Agent Framework will by default store the full chat history in-memory in the `AgentThread` object, but developers can provide a custom `ChatMessageStore` implementation to store chat history in a 3rd party store if required.
-1. **In-service storage**: Agent is built on a service that requires in-service storage of chat history (e.g. Azure AI Foundry Persistent Agents). The Agent Framework will store the id of the remote chat history in the `AgentThread` object and no other chat history storage options are supported.
+- **In-memory storage**: Agent is built on a service that doesn't support in-service storage of chat history (for example, OpenAI Chat Completion). By default, Agent Framework stores the full chat history in-memory in the `AgentThread` object, but developers can provide a custom `ChatMessageStore` implementation to store chat history in a third-party store if required.
+- **In-service storage**: Agent is built on a service that requires in-service storage of chat history (for example, Azure AI Foundry Persistent Agents). Agent Framework stores the ID of the remote chat history in the `AgentThread` object, and no other chat history storage options are supported.
 
 ### In-memory chat history storage
 
-When using a service that does not support in-service storage of chat history, the Agent Framework will default to storing chat history in-memory in the `AgentThread` object. In this case, the full chat history that is stored in the thread object, plus any new messages, will be provided to the underlying service on each agent run. This allows for a natural conversational experience with the agent, where the caller only provides the new user message, and the agent only returns new answers, but the agent has access to the full conversation history and will use it when generating its response.
+When using a service that doesn't support in-service storage of chat history, Agent Framework defaults to storing chat history in-memory in the `AgentThread` object. In this case, the full chat history that's stored in the thread object, plus any new messages, will be provided to the underlying service on each agent run. This design allows for a natural conversational experience with the agent. The caller only provides the new user message, and the agent only returns new answers. But the agent has access to the full conversation history and will use it when generating its response.
 
-When using OpenAI Chat Completion as the underlying service for agents, the following code will result in the thread object containing the chat history from the agent run.
+When using OpenAI Chat Completion as the underlying service for agents, the following code results in the thread object containing the chat history from the agent run.
 
 ```csharp
 AIAgent agent = new OpenAIClient("<your_api_key>")
@@ -38,18 +38,18 @@ AgentThread thread = agent.GetNewThread();
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", thread));
 ```
 
-Where messages are stored in memory, it is possible to retrieve the list of messages from the thread and manipulate the mesages directly if required.
+Where messages are stored in memory, it's possible to retrieve the list of messages from the thread and manipulate the messages directly if required.
 
 ```csharp
 IList<ChatMessage>? messages = thread.GetService<IList<ChatMessage>>();
 ```
 
 > [!NOTE]
-> Retrieving messages from the `AgentThread` object in this way will only work if in-memory storage is being used.
+> Retrieving messages from the `AgentThread` object in this way only works if in-memory storage is being used.
 
-#### Chat History reduction with In-Memory storage
+#### Chat history reduction with in-memory storage
 
-The built-in `InMemoryChatMessageStore` that is used by default when the underlying service does not support in-service storage,
+The built-in `InMemoryChatMessageStore` that's used by default when the underlying service does not support in-service storage,
 can be configured with a reducer to manage the size of the chat history.
 This is useful to avoid exceeding the context size limits of the underlying service.
 
@@ -67,7 +67,7 @@ AIAgent agent = new OpenAIClient("<your_api_key>")
     .CreateAIAgent(new ChatClientAgentOptions
     {
         Name = JokerName,
-        Instructions = JokerInstructions,
+        ChatOptions = new() { Instructions = JokerInstructions },
         ChatMessageStoreFactory = ctx => new InMemoryChatMessageStore(
             new MessageCountingChatReducer(2),
             ctx.SerializedState,
@@ -81,9 +81,9 @@ AIAgent agent = new OpenAIClient("<your_api_key>")
 
 ### Inference service chat history storage
 
-When using a service that requires in-service storage of chat history, the Agent Framework will store the id of the remote chat history in the `AgentThread` object.
+When using a service that requires in-service storage of chat history, Agent Framework stores the ID of the remote chat history in the `AgentThread` object.
 
-E.g, when using OpenAI Responses with store=true as the underlying service for agents, the following code will result in the thread object containing the last response id returned by the service.
+For example, when using OpenAI Responses with store=true as the underlying service for agents, the following code will result in the thread object containing the last response ID returned by the service.
 
 ```csharp
 AIAgent agent = new OpenAIClient("<your_api_key>")
@@ -94,19 +94,18 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", thread)
 ```
 
 > [!NOTE]
-> Some services, e.g. OpenAI Responses support either in-service storage of chat history (store=true), or providing the full chat history on each invocation (store=false).
-> Therefore, depending on the mode that the service is used in, the Agent Framework will either default to storing the full chat history in memory, or storing an id reference
-> to the service stored chat history.
+> Some services, for example, OpenAI Responses support either in-service storage of chat history (store=true), or providing the full chat history on each invocation (store=false).
+> Therefore, depending on the mode that the service is used in, Agent Framework will either default to storing the full chat history in memory, or storing an ID reference to the service stored chat history.
 
-### 3rd party chat history storage
+### Third-party chat history storage
 
-When using a service that does not support in-service storage of chat history, the Agent Framework allows developers to replace the default in-memory storage of chat history with 3rd party chat history storage. The developer is required to provide a subclass of the base abstract `ChatMessageStore` class.
+When using a service that does not support in-service storage of chat history, Agent Framework allows developers to replace the default in-memory storage of chat history with third-party chat history storage. The developer is required to provide a subclass of the base abstract `ChatMessageStore` class.
 
 The `ChatMessageStore` class defines the interface for storing and retrieving chat messages. Developers must implement the `AddMessagesAsync` and `GetMessagesAsync` methods to add messages to the remote store as they are generated, and retrieve messages from the remote store before invoking the underlying service.
 
 The agent will use all messages returned by `GetMessagesAsync` when processing a user query. It is up to the implementer of `ChatMessageStore` to ensure that the size of the chat history does not exceed the context window of the underlying service.
 
-When implementing a custom `ChatMessageStore` which stores chat history in a remote store, the chat history for that thread should be stored under a key that is unique to that thread. The `ChatMessageStore` implementation should generate this key and keep it in its state. `ChatMessageStore` has a `Serialize` method that can be overridden to serialize its state when the thread is serialized. The `ChatMessageStore` should also provide a constructor that takes a `JsonElement` as input to support deserialization of its state.
+When implementing a custom `ChatMessageStore` which stores chat history in a remote store, the chat history for that thread should be stored under a key that is unique to that thread. The `ChatMessageStore` implementation should generate this key and keep it in its state. `ChatMessageStore` has a `Serialize` method that can be overridden to serialize its state when the thread is serialized. The `ChatMessageStore` should also provide a constructor that takes a <xref:System.Text.Json.JsonElement> as input to support deserialization of its state.
 
 To supply a custom `ChatMessageStore` to a `ChatClientAgent`, you can use the `ChatMessageStoreFactory` option when creating the agent.
 Here is an example showing how to pass the custom implementation of `ChatMessageStore` to a `ChatClientAgent` that is based on Azure OpenAI Chat Completion.
@@ -115,19 +114,19 @@ Here is an example showing how to pass the custom implementation of `ChatMessage
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
     new AzureCliCredential())
-     .GetChatClient(deploymentName)
-     .CreateAIAgent(new ChatClientAgentOptions
-     {
-         Name = JokerName,
-         Instructions = JokerInstructions,
-         ChatMessageStoreFactory = ctx =>
-         {
-             // Create a new chat message store for this agent that stores the messages in a custom store.
-             // Each thread must get its own copy of the CustomMessageStore, since the store
-             // also contains the id that the thread is stored under.
-             return new CustomMessageStore(vectorStore, ctx.SerializedState, ctx.JsonSerializerOptions);
-         }
-     });
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(new ChatClientAgentOptions
+    {
+        Name = JokerName,
+        ChatOptions = new() { Instructions = JokerInstructions },
+        ChatMessageStoreFactory = ctx =>
+        {
+            // Create a new chat message store for this agent that stores the messages in a custom store.
+            // Each thread must get its own copy of the CustomMessageStore, since the store
+            // also contains the ID that the thread is stored under.
+            return new CustomMessageStore(vectorStore, ctx.SerializedState, ctx.JsonSerializerOptions);
+        }
+    });
 ```
 
 > [!TIP]
@@ -144,9 +143,9 @@ To implement such a memory component, the developer needs to subclass the `AICon
 
 ## AgentThread Serialization
 
-It is important to be able to persist an `AgentThread` object between agent invocations. This allows for situations where a user may ask a question of the agent, and take a long time to ask follow up questions. This allows the `AgentThread` state to survive service or app restarts.
+It is important to be able to persist an `AgentThread` object between agent invocations. This allows for situations where a user might ask a question of the agent, and take a long time to ask follow up questions. This allows the `AgentThread` state to survive service or app restarts.
 
-Even if the chat history is stored in a remote store, the `AgentThread` object still contains an id referencing the remote chat history. Losing the `AgentThread` state will therefore result in also losing the id of the remote chat history.
+Even if the chat history is stored in a remote store, the `AgentThread` object still contains an ID referencing the remote chat history. Losing the `AgentThread` state will therefore result in also losing the ID of the remote chat history.
 
 The `AgentThread` as well as any objects attached to it, all therefore provide the `SerializeAsync` method to serialize their state. The `AIAgent` also provides a `DeserializeThread` method that re-creates a thread from the serialized state. The `DeserializeThread` method re-creates the thread with the `ChatMessageStore` and `AIContextProvider` configured on the agent.
 
@@ -163,7 +162,7 @@ AgentThread resumedThread = AIAgent.DeserializeThread(serializedThreadState);
 > [!IMPORTANT]
 > Always treat `AgentThread` objects as opaque objects, unless you are very sure of the internals. The contents may vary not just by agent type, but also by service type and configuration.
 > [!WARNING]
-> Deserializing a thread with a different agent than that which originally created it, or with an agent that has a different configuration than the original agent, may result in errors or unexpected behavior.
+> Deserializing a thread with a different agent than that which originally created it, or with an agent that has a different configuration than the original agent, might result in errors or unexpected behavior.
 
 ::: zone-end
 ::: zone pivot="programming-language-python"