test: WIP

There is a timeout-wait for messages in the inner loop driving the running of the workflow. When it gets cleared, an attempt to run a superstep is made. Currently we set the state to running as soon as the wait clears, even if we have no work to do, and clear it upon discovering this.

The fix is to only set the Running state when actual Workflow execution is happening when running Super-Steps, and not until the loop confirms there is work to do.

A broader-term fix would be to remove the Semaphore and timeout-wait in it, since it is working around the inability to atomicaly insert and release the Semaphore,

.github/workflows/python-check-coverage.py

@@ -33,9 +33,9 @@ ENFORCED_MODULES: set[str] = {
     "packages.core.agent_framework",
     "packages.core.agent_framework._workflows",
     "packages.purview.agent_framework_purview",
-    # Add more modules here as coverage improves:
-    # "packages.azure-ai-search.agent_framework_azure_ai_search",
-    # "packages.anthropic.agent_framework_anthropic",
+    "packages.anthropic.agent_framework_anthropic",
+    "packages.azure-ai-search.agent_framework_azure_ai_search",
+    # Add more modules here as coverage improves
 }
 
 
@@ -62,7 +62,9 @@ class PackageCoverage:
         return self.branch_rate * 100
 
 
-def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float, float]:
+def parse_coverage_xml(
+    xml_path: str,
+) -> tuple[dict[str, PackageCoverage], float, float]:
     """Parse Cobertura XML and extract per-package coverage data.
 
     Args:
@@ -103,7 +105,9 @@ def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float
                     if condition_coverage:
                         # Parse "X% (covered/total)" format
                         try:
-                            coverage_parts = condition_coverage.split("(")[1].rstrip(")").split("/")
+                            coverage_parts = (
+                                condition_coverage.split("(")[1].rstrip(")").split("/")
+                            )
                             branches_covered += int(coverage_parts[0])
                             branches_valid += int(coverage_parts[1])
                         except (IndexError, ValueError):
@@ -114,7 +118,9 @@ def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float
         packages[package_path] = PackageCoverage(
             name=package_path,
             line_rate=line_rate if lines_valid == 0 else lines_covered / lines_valid,
-            branch_rate=branch_rate if branches_valid == 0 else branches_covered / branches_valid,
+            branch_rate=branch_rate
+            if branches_valid == 0
+            else branches_covered / branches_valid,
             lines_valid=lines_valid,
             lines_covered=lines_covered,
             branches_valid=branches_valid,
@@ -179,7 +185,9 @@ def print_coverage_table(
     for pkg in sorted_packages:
         is_enforced = pkg.name in ENFORCED_MODULES
         enforced_marker = "[ENFORCED] " if is_enforced else ""
-        line_cov = format_coverage_value(pkg.line_coverage_percent, threshold, is_enforced)
+        line_cov = format_coverage_value(
+            pkg.line_coverage_percent, threshold, is_enforced
+        )
         lines_info = f"{pkg.lines_covered}/{pkg.lines_valid}"
         package_label = f"{enforced_marker}{pkg.name}"
 
@@ -217,11 +225,15 @@ def check_coverage(xml_path: str, threshold: float) -> bool:
 
     # Report results
     if missing_modules:
-        print(f"\n❌ FAILED: Enforced modules not found in coverage report: {', '.join(missing_modules)}")
+        print(
+            f"\n❌ FAILED: Enforced modules not found in coverage report: {', '.join(missing_modules)}"
+        )
         return False
 
     if failed_modules:
-        print(f"\n❌ FAILED: The following enforced modules are below {threshold}% coverage threshold:")
+        print(
+            f"\n❌ FAILED: The following enforced modules are below {threshold}% coverage threshold:"
+        )
         for module in failed_modules:
             print(f"   - {module}")
         print("\nTo fix: Add more tests to improve coverage for the failing modules.")
@@ -230,7 +242,9 @@ def check_coverage(xml_path: str, threshold: float) -> bool:
     if ENFORCED_MODULES:
         found_enforced = [m for m in ENFORCED_MODULES if m in packages]
         if found_enforced:
-            print(f"\n✅ PASSED: All enforced modules meet the {threshold}% coverage threshold.")
+            print(
+                f"\n✅ PASSED: All enforced modules meet the {threshold}% coverage threshold."
+            )
 
     return True
 

docs/decisions/0016-python-context-middleware.md

@@ -1072,6 +1072,50 @@ Rationale for B1 over B2: Simpler is better. The whole state dict is passed to e
 > **Note on trust:** Since all `ContextProvider` instances reason over conversation messages (which may contain sensitive user data), they should be **trusted by default**. This is also why we allow all plugins to see all state - if a plugin is untrusted, it shouldn't be in the pipeline at all. The whole state dict is passed rather than isolated slices because plugins that handle messages already have access to the full conversation context.
 
 
+### Addendum (2026-02-17): Provider-scoped hook state and default source IDs
+
+This addendum introduces a **breaking change** that supersedes earlier references in this ADR where hooks received the
+entire `session.state` object as their `state` parameter.
+
+#### Hook state contract
+
+- `before_run` and `after_run` now receive a **provider-scoped** mutable state dict.
+- The framework passes `session.state.setdefault(provider.source_id, {})` to hook `state`.
+- Cross-provider/global inspection remains available through `session.state` on `AgentSession`.
+
+#### Session requirement and fallback behavior
+
+- Provider hooks must use session-backed scoped state; there is no ad-hoc `{}` fallback state.
+- If providers run without a caller-supplied session, the framework creates an internal run-scoped `AgentSession` and
+  passes provider-scoped state from that session.
+
+#### Migration guidance
+
+Migrate provider implementations and samples from nested access to scoped access:
+
+- `state[self.source_id]["key"]` → `state["key"]`
+- `state.setdefault(self.source_id, {})["key"]` → `state["key"]`
+
+#### DEFAULT_SOURCE_ID standardization
+
+Aligned with and extending [PR #3944](https://github.com/microsoft/agent-framework/pull/3944), all built-in/connector
+providers in this surface now define a `DEFAULT_SOURCE_ID` and allow constructor override via `source_id`.
+
+Naming convention:
+
+- snake_case
+- close to the provider class name
+- history providers may use `*_memory` where differentiation is useful
+
+Defaults introduced by this change:
+
+- `InMemoryHistoryProvider.DEFAULT_SOURCE_ID = "in_memory"`
+- `Mem0ContextProvider.DEFAULT_SOURCE_ID = "mem0"`
+- `RedisContextProvider.DEFAULT_SOURCE_ID = "redis"`
+- `RedisHistoryProvider.DEFAULT_SOURCE_ID = "redis_memory"`
+- `AzureAISearchContextProvider.DEFAULT_SOURCE_ID = "azure_ai_search"`
+
+
 ## Comparison to .NET Implementation
 
 The .NET Agent Framework provides equivalent functionality through a different structure. Both implementations achieve the same goals using idioms natural to their respective languages.

docs/decisions/0016-structured-output.md

@@ -0,0 +1,658 @@
+---
+status: proposed
+contact: sergeymenshykh
+date: 2026-01-22
+deciders: rbarreto, westey-m, stephentoub
+informed: {}
+---
+
+# Structured Output
+
+Structured output is a valuable aspect of any agent system, since it forces an agent to produce output in a required format that may include required fields.
+This allows easily turning unstructured data into structured data using a general-purpose language model.
+
+## Context and Problem Statement
+
+Structured output is currently supported only by `ChatClientAgent` and can be configured in two ways:
+
+**Approach 1: ResponseFormat + Deserialize**
+
+Specify the SO type schema via the `ChatClientAgent{Run}Options.ChatOptions.ResponseFormat` property at agent creation or invocation time, then use `JsonSerializer.Deserialize<T>` to extract the structured data from the response text.
+
+	```csharp
+	// SO type can be provided at agent creation time
+	ChatClientAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+	{
+		Name = "...",
+		ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
+	});
+
+	AgentResponse response = await agent.RunAsync("...");
+
+	PersonInfo personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
+
+	Console.WriteLine($"Name: {personInfo.Name}");
+	Console.WriteLine($"Age: {personInfo.Age}");
+	Console.WriteLine($"Occupation: {personInfo.Occupation}");
+
+	// Alternatively, SO type can be provided at agent invocation time
+	response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
+	{
+		ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
+	});
+
+	personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
+
+	Console.WriteLine($"Name: {personInfo.Name}");
+	Console.WriteLine($"Age: {personInfo.Age}");
+	Console.WriteLine($"Occupation: {personInfo.Occupation}");
+	```
+
+**Approach 2: Generic RunAsync<T>**
+
+Supply the SO type as a generic parameter to `RunAsync<T>` and access the parsed result directly via the `Result` property.
+
+	```csharp
+	ChatClientAgent agent = ...;
+	
+	AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("...");
+
+	Console.WriteLine($"Name: {response.Result.Name}");
+	Console.WriteLine($"Age: {response.Result.Age}");
+	Console.WriteLine($"Occupation: {response.Result.Occupation}");
+	```
+	Note: `RunAsync<T>` is an instance method of `ChatClientAgent` and not part of the `AIAgent` base class since not all agents support structured output.
+
+Approach 1 is perceived as cumbersome by the community, as it requires additional effort when using primitive or collection types - the SO schema may need to be wrapped in an artificial JSON object. Otherwise, the caller will encounter an error like _Invalid schema for response_format 'Movie': schema must be a JSON Schema of 'type: "object"', got 'type: "array"'_. 
+This occurs because OpenAI and compatible APIs require a JSON object as the root schema.
+
+Approach 1 is also necessary in scenarios where (a) agents can only be configured with SO at creation time (such as with `AIProjectClient`), (b) the SO type is not known at compile time, or (c) the JSON schema is represented as text (for declarative agents) or as a `JsonElement`.
+
+Approach 2 is more convenient and works seamlessly with primitives and collections. However, it requires the SO type to be known at compile time, making it less flexible.
+
+Additionally, since the `RunAsync<T>` methods are instance methods of `ChatClientAgent` and are not part of the `AIAgent` base class, applying decorators like `OpenTelemetryAgent` on top of `ChatClientAgent` prevents users from accessing `RunAsync<T>`, meaning structured output is not available with decorated agents.
+
+Given the different scenarios above in which structured output can be used, there is no one-size-fits-all solution. Each approach has its own advantages and limitations,
+and the two can complement each other to provide a comprehensive structured output experience across various use cases.
+
+## Approaches Overview
+
+1. SO usage via `ResponseFormat` property
+2. SO usage via `RunAsync<T>` generic method
+
+## 1. SO usage via `ResponseFormat` property
+
+This approach should be used in the following scenarios:
+ - 1.1 SO result as text is sufficient as is, and deserialization is not required
+ - 1.2 SO for inter-agent collaboration
+ - 1.3 SO can only be configured at agent creation time (such as with `AIProjectClient`)
+ - 1.4 SO type is not known at compile time and represented by System.Type
+ - 1.5 SO is represented by JSON schema and there's no corresponding .NET type either at compile time or at runtime
+ - 1.6 SO in streaming scenarios, where the SO response is produced in parts
+
+**Note: Primitives and arrays are not supported by this approach.**
+
+When a caller provides a schema via `ResponseFormat`, they are explicitly telling the framework what schema to use. The framework passes that schema through as-is and
+is not responsible for transforming it. Because the framework does not own the schema, it cannot wrap primitives or arrays into a JSON object to satisfy API requirements,
+nor can it unwrap the response afterward - the caller controls the schema and is responsible for ensuring it is compatible with the underlying API.
+
+This is in contrast to the `RunAsync<T>` approach (section 2), where the caller provides a type `T` and says "make it work." In that case, the caller does not
+dictate the schema - the framework infers the schema from `T`, owns the end-to-end pipeline (schema generation, API invocation, and deserialization), and can
+therefore wrap and unwrap primitives and arrays transparently.
+
+Additionally, in streaming scenarios (1.6), the framework cannot reliably unwrap a response it did not wrap, since it has no way of knowing whether the caller wrapped the schema.Wrapping and unwrapping can only be done safely when the framework owns the entire lifecycle - from schema creation through deserialization — which is only the case with `RunAsync<T>`.
+
+If a caller needs to work with primitives or arrays via the `ResponseFormat` approach, they can easily create a wrapper type around them:
+
+```csharp
+public class MovieListWrapper
+{
+    public List<string> Movies { get; set; }
+}
+```
+
+### 1.1 SO result as text is sufficient as is, and deserialization is not required
+
+In this scenario, the caller only needs the raw JSON text returned by the model and does not need to deserialize it into a .NET type.
+The SO schema is specified via `ResponseFormat` at agent creation or invocation time, and the response text is consumed directly from the `AgentResponse`.
+
+```csharp
+AIAgent agent = chatClient.AsAIAgent();
+
+AgentRunOptions runOptions = new()
+{
+        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
+};
+
+AgentResponse response = await agent.RunAsync("...", options: runOptions);
+
+Console.WriteLine(response.Text);
+```
+
+### 1.2 SO for inter-agent collaboration
+
+This scenario assumes a multi-agent setup where agents collaborate by passing messages to each other.
+One agent produces structured output as text that is then passed directly as input to the next agent, without intermediate deserialization.
+
+```csharp
+// First agent extracts structured data from unstructured input
+AIAgent extractionAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+{
+    Name = "ExtractionAgent",
+    ChatOptions = new() 
+    { 
+        Instructions = "Extract person information from the provided text.",
+        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() 
+    }
+});
+
+AgentResponse extractionResponse = await extractionAgent.RunAsync("John Smith is a 35-year-old software engineer.");
+
+// Pass the message with structured output text directly to the next agent
+ChatMessage soMessage = extractionResponse.Messages.Last();
+
+AIAgent summaryAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+{
+    Name = "SummaryAgent",
+    ChatOptions = new() { Instructions = "Given the following structured person data, write a short professional bio." }
+});
+
+AgentResponse summaryResponse = await summaryAgent.RunAsync(soMessage);
+
+Console.WriteLine(summaryResponse);
+```
+
+### 1.3 SO configured at agent creation time
+
+In this scenario, the SO schema can only be configured at agent creation time (such as with `AIProjectClient`) and cannot be changed on a per-run basis.
+The caller specifies the `ResponseFormat` when creating the agent, and all subsequent invocations use the same schema.
+
+```csharp
+AIProjectClient client = ...;
+
+AIAgent agent = await client.CreateAIAgentAsync(model: "<model>", new ChatClientAgentOptions()
+{
+    Name = "...",
+    ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
+});
+
+AgentResponse response = await agent.RunAsync("Please provide information about John Smith.");
+
+PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text, JsonSerializerOptions.Web)!;
+
+Console.WriteLine($"Name: {personInfo.Name}");
+Console.WriteLine($"Age: {personInfo.Age}");
+Console.WriteLine($"Occupation: {personInfo.Occupation}");
+```
+
+### 1.4 SO type not known at compile time and represented by System.Type
+
+In this scenario, the SO type is not known at compile time and is provided as a `System.Type` at runtime. This is useful for dynamic scenarios where the schema is determined programmatically, 
+such as when building tooling or frameworks that work with user-defined types.
+
+```csharp
+Type soType = GetStructuredOutputTypeFromConfiguration(); // e.g., typeof(PersonInfo)
+
+ChatResponseFormat responseFormat = ChatResponseFormat.ForJsonSchema(soType);
+
+AgentResponse response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
+{
+    ChatOptions = new() { ResponseFormat = responseFormat }
+});
+
+PersonInfo personInfo = (PersonInfo)JsonSerializer.Deserialize(response.Text, soType, JsonSerializerOptions.Web)!;
+```
+
+### 1.5 SO represented by JSON schema with no corresponding .NET type
+
+In this scenario, the SO schema is represented as raw JSON schema text or a `JsonElement`, and there is no corresponding .NET type available at compile time or runtime.
+This is typical for declarative agents or scenarios where schemas are loaded from external configuration.
+
+```csharp
+// JSON schema provided as a string, e.g., loaded from a configuration file
+string jsonSchema = """
+{
+    "type": "object",
+    "properties": {
+        "name": { "type": "string" },
+        "age": { "type": "integer" },
+        "occupation": { "type": "string" }
+    },
+    "required": ["name", "age", "occupation"]
+}
+""";
+
+ChatResponseFormat responseFormat = ChatResponseFormat.ForJsonSchema(
+    jsonSchemaName: "PersonInfo",
+    jsonSchema: BinaryData.FromString(jsonSchema));
+
+AgentResponse response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
+{
+    ChatOptions = new() { ResponseFormat = responseFormat }
+});
+
+// Consume the SO result as text since there's no .NET type to deserialize into
+Console.WriteLine(response.Text);
+```
+
+### 1.6 SO in streaming scenarios
+
+In this scenario, the SO response is produced incrementally in parts via streaming. The caller specifies the `ResponseFormat` and consumes the response chunks as they arrive.
+Deserialization is performed after all chunks have been received.
+
+```csharp
+AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+{
+    Name = "HelpfulAssistant",
+    ChatOptions = new()
+    {
+        Instructions = "You are a helpful assistant.",
+        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
+    }
+});
+
+IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
+
+AgentResponse response = await updates.ToAgentResponseAsync();
+
+// Deserialize the complete SO result after streaming is finished
+PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text)!;
+```
+
+## 2. SO usage via `RunAsync<T>` generic method
+
+This approach provides a convenient way to work with structured output on a per-run basis when the target type is known at compile time and a typed instance of the result
+is required.
+
+### Decision Drivers
+
+1. Support arrays and primitives as SO types
+2. Support complex types as SO types
+3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
+4. Enable SO for all AI agents, regardless of whether they natively support it
+
+### Considered Options
+
+1. `RunAsync<T>` as an instance method of `AIAgent` class delegating to virtual `RunCoreAsync<T>`
+2. `RunAsync<T>` as an extension method using feature collection
+3. `RunAsync<T>` as a method of the new `ITypedAIAgent` interface
+4. `RunAsync<T>` as an instance method of `AIAgent` class working via the new `AgentRunOptions.ResponseFormat` property
+
+### 1. `RunAsync<T>` as an instance method of `AIAgent` class delegating to virtual `RunCoreAsync<T>`
+
+This option adds the `RunAsync<T>` method directly to the `AIAgent` base class.
+
+```csharp
+public abstract class AIAgent
+{
+	public Task<AgentResponse<T>> RunAsync<T>(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+		=> this.RunCoreAsync<T>(messages, session, serializerOptions, options, cancellationToken);
+
+    protected virtual Task<AgentResponse<T>> RunCoreAsync<T>(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        throw new NotSupportedException($"The agent of type '{this.GetType().FullName}' does not support typed responses.");
+    }
+}
+```
+
+Agents with native SO support override the `RunCoreAsync<T>` method to provide their implementation. If not overridden, the method throws a `NotSupportedException`.
+
+Users will call the generic `RunAsync<T>` method directly on the agent:
+
+```csharp
+AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+
+AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
+```
+
+Decision drivers satisfied:
+1. Support arrays and primitives as SO types
+2. Support complex types as SO types
+3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
+4. Enable SO for all AI agents, regardless of whether they natively support it
+
+Pros:
+- The `AIAgent.RunAsync<T>` method is easily discoverable.
+- Both the SO decorator and `ChatClientAgent` have compile-time access to the type `T`, allowing them to use the native `IChatClient.GetResponseAsync<T>` API, which handles primitives and collections seamlessly.
+
+Cons:
+- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
+- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
+- All `AIAgent` decorators must override `RunCoreAsync<T>` to properly handle `RunAsync<T>` calls.
+
+### 2. `RunAsync<T>` as an extension method using feature collection
+
+This option uses the Agent Framework feature collection (implemented via `AgentRunOptions.AdditionalProperties`) to pass a `StructuredOutputFeature` to agents, signaling that SO is requested.
+
+Agents with native SO support check for this feature. If present, they read the target type, build the schema, invoke the underlying API, and store the response back in the feature.
+```csharp
+public class StructuredOutputFeature
+{
+    public StructuredOutputFeature(Type outputType)
+    {
+        this.OutputType = outputType;
+    }
+
+    [JsonIgnore]
+    public Type OutputType { get; set; }
+
+    public JsonSerializerOptions? SerializerOptions { get; set; }
+
+    public AgentResponse? Response { get; set; }
+}
+```
+
+The `RunAsync<T>` extension method for `AIAgent` adds this feature to the collection.
+```csharp
+public static async Task<AgentResponse<T>> RunAsync<T>(
+    this AIAgent agent,
+    IEnumerable<ChatMessage> messages,
+    AgentSession? session = null,
+    JsonSerializerOptions? serializerOptions = null,
+    AgentRunOptions? options = null,
+    CancellationToken cancellationToken = default)
+{
+    // Create the structured output feature.
+    StructuredOutputFeature structuredOutputFeature = new(typeof(T))
+    {
+        SerializerOptions = serializerOptions,
+    };
+
+    // Register it in the feature collection.
+    ((options ??= new AgentRunOptions()).AdditionalProperties ??= []).Add(typeof(StructuredOutputFeature).FullName!, structuredOutputFeature);
+
+    var response = await agent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+
+    if (structuredOutputFeature.Response is not null)
+    {
+        return new StructuredOutputResponse<T>(structuredOutputFeature.Response, response, serializerOptions);
+    }
+
+    throw new InvalidOperationException("No structured output response was generated by the agent.");
+}
+```
+
+Users will call the `RunAsync<T>` extension method directly on the agent:
+
+```csharp
+AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+
+AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
+```
+
+Decision drivers satisfied:
+1. Support arrays and primitives as SO types
+2. Support complex types as SO types
+3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
+4. Enable SO for all AI agents, regardless of whether they natively support it
+
+Pros:
+- The `RunAsync<T>` extension method is easily discoverable.
+- The `AIAgent` public API surface remains unchanged.
+- No changes required to `AIAgent` decorators.
+
+Cons:
+- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
+- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
+
+### 3. `RunAsync<T>` as a method of the new `ITypedAIAgent` interface
+
+This option defines a new `ITypedAIAgent` interface that agents with SO support implement. Agents without SO support do not implement it, allowing users to check for SO capability via interface detection.
+
+The interface:
+```csharp
+public interface ITypedAIAgent
+{
+    Task<AgentResponse<T>> RunAsync<T>(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default);
+
+    ...
+}
+```
+
+Agents with SO support implement this interface:
+```csharp
+public sealed partial class ChatClientAgent : AIAgent, ITypedAIAgent
+{
+    public async Task<AgentResponse<T>> RunAsync<T>(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        ...
+    }
+}
+```
+
+However, `ChatClientAgent` presents a challenge: it can work with chat clients that either support or do not support SO. Implementing the interface does not guarantee 
+the underlying chat client supports SO, which undermines the core idea of using interface detection to determine SO capability.
+
+Additionally, to allow users to access interface methods on decorated agents, all decorators must implement `ITypedAIAgent`. This makes it difficult for users to 
+determine whether the underlying agent actually supports SO, further weakening the purpose of this approach.
+
+Furthermore, users would have to probe the agent type to check if it implements the `ITypedAIAgent` interface and cast it accordingly to access the `RunAsync<T>` methods.
+This adds friction to the user experience. A `RunAsync<T>` extension method for `AIAgent` could be provided to alleviate that.
+
+Given these drawbacks, this option is more complex to implement than the others without providing clear benefits.
+
+Decision drivers satisfied:
+1. Support arrays and primitives as SO types
+2. Support complex types as SO types
+3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
+4. Enable SO for all AI agents, regardless of whether they natively support it
+
+Pros:
+- Both the SO decorator and `ChatClientAgent` have compile-time access to the type `T`, allowing them to use the native `IChatClient.GetResponseAsync<T>` API, which handles primitives and collections seamlessly.
+
+Cons:
+- `ChatClientAgent` implementing `ITypedAIAgent` may be misleading when the underlying chat client does not support SO.
+- All `AIAgent` decorators must implement `ITypedAIAgent` to handle `RunAsync<T>` calls.
+- Decorators implementing the interface may mislead users into thinking the underlying agent natively supports SO.
+- Agents must implement all members of `ITypedAIAgent`, not just a core method.
+- Users must check the agent type and cast to `ITypedAIAgent` to access `RunAsync<T>`.
+
+### 4. `RunAsync<T>` as an instance method of `AIAgent` class working via the new `AgentRunOptions.ResponseFormat` property
+
+This option adds a `ResponseFormat` property of type `ChatResponseFormat` to `AgentRunOptions`. Agents that support SO check for the presence of 
+this property in the options passed to `RunAsync` to determine whether structured output is requested. If present, they use the schema from `ResponseFormat` 
+to invoke the underlying API and obtain the SO response.
+
+```csharp
+public class AgentRunOptions
+{
+    public ChatResponseFormat? ResponseFormat { get; set; }
+}
+```
+
+Additionally, a generic `RunAsync<T>` method is added to `AIAgent` that initializes the `ResponseFormat` based on the type `T` and delegates to the non-generic `RunAsync`.
+
+```csharp
+public abstract class AIAgent
+{
+	public async Task<AgentResponse<T>> RunAsync<T>(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;
+
+        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
+
+        options = options?.Clone() ?? new AgentRunOptions();
+        options.ResponseFormat = responseFormat;
+
+        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+
+        return new AgentResponse<T>(response, serializerOptions);
+    }
+}
+```
+
+Users call the generic `RunAsync<T>` method directly on the agent:
+
+```csharp
+AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+
+AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
+```
+
+Decision drivers satisfied:
+1. Support arrays and primitives as SO types
+2. Support complex types as SO types
+3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
+4. Enable SO for all AI agents, regardless of whether they natively support it
+
+Pros:
+- The `AIAgent.RunAsync<T>` method is easily discoverable.
+- No changes required to `AIAgent` decorators
+
+Cons:
+- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
+- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
+
+### Decision Table
+
+|  | Option 1: Instance method + RunCoreAsync<T> | Option 2: Extension method + feature collection | Option 3: ITypedAIAgent Interface | Option 4: Instance method + AgentRunOptions.ResponseFormat |
+|---|---|---|---|---|
+| Discoverability | ✅ `RunAsync<T>` easily discoverable | ✅ `RunAsync<T>` easily discoverable | ❌ Requires type check and cast | ✅ `RunAsync<T>` easily discoverable |
+| Decorator changes | ❌ All decorators must override `RunCoreAsync<T>` | ✅ No changes required | ❌ All decorators must implement `ITypedAIAgent` | ✅ No changes required to decorators |
+| Primitives/collections handling | ✅ Native support via `IChatClient.GetResponseAsync<T>` | ❌ Must wrap/unwrap internally | ✅ Native support via `IChatClient.GetResponseAsync<T>` | ❌ Must wrap/unwrap internally |
+| Misleading API exposure | ❌ Agents without SO still expose `RunAsync<T>` | ❌ Agents without SO still expose `RunAsync<T>` | ❌ Interface on `ChatClientAgent` may be misleading | ❌ Agents without SO still expose `RunAsync<T>` |
+| Implementation burden | ❌ Decorators must override method | ❌ Must handle schema wrapping | ❌ Agents must implement all interface members | ✅ Delegates to existing `RunAsync` via `ResponseFormat` |
+
+## Cross-Cutting Aspects
+
+1. **The `useJsonSchemaResponseFormat` parameter**: The `ChatClientAgent.RunAsync<T>` method has this parameter to enable structured output on LLMs that do not natively support it.
+  It works by adding a user message like "Respond with a JSON value conforming to the following schema:" along with the JSON schema. However, this approach has not been reliable historically. The recommendation is not to carry this parameter forward, regardless of which option is chosen.
+
+2. **Primitives and array types handling**: There are a few options for how primitive and array types can be handled in the Agent Framework:
+
+   1. **Never wrap**, regardless of whether the schema is provided via `ResponseFormat` or `RunAsync<T>`.
+       - Pro: No changes needed; user has full control.
+       - Pro: No issues with unwrapping in streaming scenarios.
+       - Con: User must wrap manually.
+
+   2. **Always wrap**, regardless of whether the schema is provided via `ResponseFormat` or `RunAsync<T>`.
+       - Pro: Consistent wrapping behavior; no manual wrapping needed.
+       - Con: Inconsistent unwrapping behavior; it may be unexpected to have SO result wrapped when schema is provided via `ResponseFormat`.
+       - Con: Impossible to know if SO result is wrapped to unwrap it in streaming scenarios.
+
+   3. **Wrap only for `RunAsync<T>`** and do not wrap the schema provided via `ResponseFormat`.
+       - Pro: No unexpectedly wrapped result when schema is provided via `ResponseFormat`.
+       - Pro: Solves the problem with unwrapping in streaming scenarios.
+
+   4. **User decides** whether to wrap schema provided via `ResponseFormat` using a new `wrapPrimitivesAndArrays` property of `ChatResponseFormatJson`. For SO provided via `RunAsync<T>`, AF always wraps.
+       - Pro: No manual wrapping needed; just flip a switch.
+       - Pro: Solves the problem with unwrapping in streaming scenarios.
+       - Con: Extends the public API surface.
+
+3. **Structured output for agents without native SO support**: Some AI agents in AF do not support structured output natively. This is either because it is not part of the protocol (e.g., A2A agent) or because the agents use LLMs without structured output capabilities.
+   To address this gap, AF can provide the `StructuredOutputAgent` decorator. This decorator wraps any `AIAgent` and adds structured output support by obtaining the text response from the decorated agent and delegating it to a configured chat client for JSON transformation.
+   
+   ```csharp
+   public class StructuredOutputAgent : DelegatingAIAgent
+   {
+        private readonly IChatClient _chatClient;
+
+        public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient)
+            : base(innerAgent)
+        {
+            this._chatClient = Throw.IfNull(chatClient);
+        }
+
+        protected override async Task<AgentResponse<T>> RunCoreAsync<T>(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session = null,
+            JsonSerializerOptions? serializerOptions = null,
+            AgentRunOptions? options = null,
+            CancellationToken cancellationToken = default)
+        {
+            // Run the inner agent first, to get back the text response we want to convert.
+            var textResponse = await this.InnerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+
+            // Invoke the chat client to transform the text output into structured data.
+            ChatResponse<T> soResponse = await this._chatClient.GetResponseAsync<T>(
+                messages:
+                [
+                    new ChatMessage(ChatRole.System, "You are a json expert and when provided with any text, will convert it to the requested json format."),
+                    new ChatMessage(ChatRole.User, textResponse.Text)
+                ],
+                serializerOptions: serializerOptions ?? AgentJsonUtilities.DefaultOptions,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+
+            return new StructuredOutputAgentResponse(soResponse, textResponse);
+        }
+   }
+   ```
+
+   The decorator preserves the original response from the decorated agent and surfaces it via the `OriginalResponse` property on the returned `StructuredOutputAgentResponse`.
+   This allows users to access both the original unstructured response and the new structured response when using this decorator.
+   ```csharp
+   public class StructuredOutputAgentResponse : AgentResponse
+   {
+       internal StructuredOutputAgentResponse(ChatResponse chatResponse, AgentResponse agentResponse) : base(chatResponse)
+       {
+           this.OriginalResponse = agentResponse;
+       }
+       
+       public AgentResponse OriginalResponse { get; }
+    }
+   ```
+   
+   The decorator can be registered during the agent configuration step using the `UseStructuredOutput` extension method on `AIAgentBuilder`.
+
+   ```csharp
+   IChatClient meaiChatClient = chatClient.AsIChatClient();
+
+   AIAgent baseAgent = meaiChatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+
+   // Register the StructuredOutputAgent decorator during agent building
+   AIAgent agent = baseAgent
+       .AsBuilder()
+       .UseStructuredOutput(meaiChatClient)
+       .Build();
+
+   AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
+
+   Console.WriteLine($"Name: {response.Result.Name}");
+   Console.WriteLine($"Age: {response.Result.Age}");
+   Console.WriteLine($"Occupation: {response.Result.Occupation}");
+   
+   var originalResponse = ((StructuredOutputAgentResponse)response.RawRepresentation!).OriginalResponse;
+   Console.WriteLine($"Original unstructured response: {originalResponse.Text}");
+
+   ```
+
+## Decision Outcome
+
+It was decided to keep both approaches for structured output - via `ResponseFormat` and via `RunAsync<T>` since they serve different scenarios and use cases.
+
+For the `RunAsync<T>` approach, option 4 was selected, which adds a generic `RunAsync<T>` method to `AIAgent` that works via the new `AgentRunOptions.ResponseFormat` property.
+This was chosen for its simplicity and because no changes are required to existing `AIAgent` decorators.
+
+For cross-cutting aspects, the `useJsonSchemaResponseFormat` parameter will not be carried forward due to reliability issues.
+
+For handling primitives and array types, option 3 was selected: wrap only for `RunAsync<T>` and do not wrap the schema provided via `ResponseFormat`.
+This avoids the issues described in the Approach 1 section note.
+
+Finally, it was decided not to include the `StructuredOutputAgent` decorator in the framework, since the reliability of producing structured output via an additional
+LLM call may not be sufficient for all scenarios. Instead, this pattern is provided as a sample to demonstrate how structured output can be achieved for agents without native support,
+giving users a reference implementation they can adapt to their own requirements.

docs/features/durable-agents/AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on durable agents documentation.
+
+## Scope
+
+This directory contains feature documentation for the durable agents integration. The source code and samples live elsewhere:
+
+- .NET implementation: `dotnet/src/Microsoft.Agents.AI.DurableTask/` and `dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/`
+- Python implementation: `python/packages/durabletask/` and `python/packages/azurefunctions/` (package `agent-framework-azurefunctions`)
+- .NET samples: `dotnet/samples/Durable/Agents/`
+- Python samples: `python/samples/04-hosting/durabletask/`
+- Official docs (Microsoft Learn): <https://learn.microsoft.com/agent-framework/integrations/azure-functions>
+
+## Document structure
+
+| File | Purpose |
+| --- | --- |
+| `README.md` | Main technical overview: architecture, hosting models, orchestration patterns, and links to samples. |
+| `durable-agents-ttl.md` | Deep-dive on session Time-To-Live (TTL) configuration and behavior. |
+
+Add new sibling documents when a topic is too detailed for the README (e.g., a new feature like reliable streaming or MCP tool exposure). Keep the README focused on orientation and link out to siblings for depth.
+
+## Writing guidelines
+
+- **Audience**: Developers already familiar with the Microsoft Agent Framework who want to understand what durability adds and how to use it.
+- **Host-agnostic first**: Durable agents work in console apps, Azure Functions, and any Durable Task–compatible host. Show host-agnostic patterns (plain orchestration functions, `IServiceCollection` registration) before Azure Functions–specific patterns. Avoid giving the impression that Azure Functions is the only hosting option.
+- **Both languages**: Always include C# and Python examples side by side. Keep them equivalent in functionality.
+- **Callout syntax**: Use GitHub-flavored callouts (`> [!NOTE]`, `> [!IMPORTANT]`, `> [!WARNING]`) rather than bold-text callouts (`> **Note:** ...`).
+- **Line length**: Do not wrap long lines. Rely on text viewers / renderers for line wrapping.
+- **Tables**: Use spaces around pipes in separator rows (`| --- |` not `|---|`).
+- **Code snippets**: Keep them minimal and self-contained. Omit boilerplate (using statements, environment variable reads) unless the snippet is specifically about setup.
+- **Cross-references**: Link to Microsoft Learn for conceptual background (Durable Entities, Durable Task Scheduler, Azure Functions). Link to sibling docs within this directory for feature deep-dives.
+
+## Linting
+
+Run markdownlint on all documents before committing, with line-length checks disabled:
+
+```bash
+markdownlint docs/features/durable-agents/ --disable MD013
+```
+
+## When to update these docs
+
+- A new durable agent feature is added (e.g., a new orchestration pattern, hosting model, or configuration option).
+- The public API surface changes in a way that affects how developers use durable agents.
+- New sample directories are added — update the sample links in README.md.
+- The official Microsoft Learn documentation is restructured — update external links.

docs/features/durable-agents/README.md

@@ -0,0 +1,239 @@
+# Durable agents
+
+## Overview
+
+Durable agents extend the standard Microsoft Agent Framework with **durable state management** powered by the Durable Task framework. An ordinary Agent Framework agent runs in-process: its conversation history lives in memory and is lost when the process ends. A durable agent persists conversation history and execution state in external storage so that sessions survive process restarts, failures, and scale-out events.
+
+| Capability | Ordinary agent | Durable agent |
+| --- | --- | --- |
+| Conversation history | In-memory only | Durably persisted |
+| Failure recovery | State lost on crash | Automatically resumed |
+| Multi-instance scale-out | Not supported | Any worker can resume a session |
+| Multi-agent orchestrations | Manual coordination | Deterministic, checkpointed workflows |
+| Human-in-the-loop | Must keep process alive | Can wait days/weeks with zero compute |
+| Hosting | Any process | Console app, Azure Functions, or any Durable Task–compatible host |
+
+> [!NOTE]
+> For a step-by-step tutorial and deployment guidance, see [Azure Functions (Durable)](https://learn.microsoft.com/agent-framework/integrations/azure-functions) on Microsoft Learn.
+
+## How durable agents work
+
+Durable agents are implemented on top of [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities) (also called "virtual actors"). Each **agent session** maps to one entity instance whose state contains the full conversation history. When you send a message to a durable agent, the following happens:
+
+1. The message is dispatched to the entity identified by an `AgentSessionId` (a composite of the agent name and a unique session key).
+2. The entity loads its persisted `DurableAgentState`, which includes the complete conversation history.
+3. The entity invokes the underlying `AIAgent` with the full conversation history, collects the response, and appends both the request and the response to the state.
+4. The updated state is persisted back to durable storage automatically.
+
+Because the entity framework serializes access to each entity instance, concurrent messages to the same session are processed one at a time, eliminating race conditions.
+
+### Agent session identity
+
+Every durable agent session is identified by an `AgentSessionId`, which has two components:
+
+- **Name** – the registered name of the agent (case-insensitive).
+- **Key** – a unique session key (case-sensitive), typically a GUID.
+
+The session ID is mapped to an underlying Durable Task entity ID with a `dafx-` prefix (e.g., `dafx-joker`). This naming convention is consistent across both .NET and Python implementations.
+
+## Architecture
+
+### .NET
+
+The .NET implementation consists of two NuGet packages:
+
+| Package | Purpose |
+| --- | --- |
+| `Microsoft.Agents.AI.DurableTask` | Core durable agent types: `DurableAIAgent`, `AgentEntity`, `DurableAgentSession`, `AgentSessionId`, `DurableAgentsOptions`, and the state model. |
+| `Microsoft.Agents.AI.Hosting.AzureFunctions` | Azure Functions hosting integration: auto-generated HTTP endpoints, MCP tool triggers, entity function triggers, and the `ConfigureDurableAgents` extension method on `FunctionsApplicationBuilder`. |
+
+Key types:
+
+- **`DurableAIAgent`** – A subclass of `AIAgent` used *inside orchestrations*. Obtained via `context.GetAgent("agentName")`, it routes `RunAsync` calls through the orchestration's entity APIs so that each call is checkpointed.
+- **`DurableAIAgentProxy`** – A subclass of `AIAgent` used *outside orchestrations* (e.g., from HTTP triggers or console apps). It signals the entity via `DurableTaskClient` and polls for the response.
+- **`AgentEntity`** – The `TaskEntity<DurableAgentState>` that hosts the real agent. It loads the registered `AIAgent` by name, wraps it in an `EntityAgentWrapper`, feeds it the full conversation history, and persists the result.
+- **`DurableAgentSession`** – An `AgentSession` subclass that carries the `AgentSessionId`.
+- **`DurableAgentsOptions`** – Builder for registering agents and configuring TTL.
+
+### Python
+
+The core Python implementation is in the `agent-framework-durabletask` package (`python/packages/durabletask`). Azure Functions hosting (including `AgentFunctionApp`) is in the separate `agent-framework-azurefunctions` package (`python/packages/azurefunctions`).
+
+Key types:
+
+- **`DurableAIAgent`** – A generic proxy (`DurableAIAgent[TaskT]`) implementing `SupportsAgentRun`. Returns a `TaskT` from `run()` — either an `AgentResponse` (client context) or a `DurableAgentTask` (orchestration context, must be `yield`ed).
+- **`DurableAIAgentWorker`** – Wraps a `TaskHubGrpcWorker` and registers agents as durable entities via `add_agent()`.
+- **`DurableAIAgentClient`** – Wraps a `TaskHubGrpcClient` for external callers. `get_agent()` returns a `DurableAIAgent[AgentResponse]`.
+- **`DurableAIAgentOrchestrationContext`** – Wraps an `OrchestrationContext` for use inside orchestrations. `get_agent()` returns a `DurableAIAgent[DurableAgentTask]`.
+- **`AgentEntity`** – Platform-agnostic agent execution logic that manages state, invokes the agent, handles streaming, and calls response callbacks.
+
+## Hosting models
+
+### Azure Functions
+
+The recommended production hosting model. A single call to `ConfigureDurableAgents` (C#) or `AgentFunctionApp` (Python) automatically:
+
+- Registers agent entities with the Durable Task worker.
+- Generates HTTP endpoints at `/api/agents/{agentName}/run` for each registered agent.
+- Supports `thread_id` query parameter / JSON field and the `x-ms-thread-id` response header for session continuity.
+- Supports fire-and-forget via the `x-ms-wait-for-response: false` header (returns HTTP 202).
+- Optionally exposes agents as MCP tools.
+
+**C# example:**
+
+```csharp
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
+    .Build();
+app.Run();
+```
+
+**Python example:**
+
+```python
+app = AgentFunctionApp(agents=[agent])
+```
+
+### Console apps / generic hosts
+
+For self-hosted or non-serverless scenarios, register durable agents via `IServiceCollection.ConfigureDurableAgents` (.NET) or `DurableAIAgentWorker` (Python) with explicit Durable Task worker and client configuration.
+
+**C# example:**
+
+```csharp
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureServices(services =>
+    {
+        services.ConfigureDurableAgents(
+            options => options.AddAIAgent(agent),
+            workerBuilder: b => b.UseDurableTaskScheduler(connectionString),
+            clientBuilder: b => b.UseDurableTaskScheduler(connectionString));
+    })
+    .Build();
+```
+
+**Python example:**
+
+```python
+worker = DurableAIAgentWorker(TaskHubGrpcWorker(host_address="localhost:4001"))
+worker.add_agent(agent)
+worker.start()
+```
+
+## Deterministic multi-agent orchestrations
+
+Durable agents can be composed into deterministic, checkpointed workflows using Durable Task orchestrations. The orchestration framework replays orchestrator code on failure, so completed agent calls are not re-executed.
+
+### Patterns
+
+| Pattern | Description |
+| --- | --- |
+| **Sequential (chaining)** | Call agents one after another, passing outputs forward. |
+| **Parallel (fan-out/fan-in)** | Run multiple agents concurrently and aggregate results. |
+| **Conditional** | Branch orchestration logic based on structured agent output. |
+| **Human-in-the-loop** | Pause for external events (approvals, feedback) with optional timeouts. |
+
+### Using agents in orchestrations
+
+Inside an orchestration function, obtain a `DurableAIAgent` via the orchestration context. Each agent gets its own session (created with `CreateSessionAsync` / `create_session`), and you can call the same agent multiple times on the same session to maintain conversation context across sequential invocations.
+
+**C#:**
+
+```csharp
+static async Task<string> WritingOrchestration(TaskOrchestrationContext context)
+{
+    // Get a durable agent reference — works in any host (console app, Azure Functions, etc.)
+    DurableAIAgent writer = context.GetAgent("WriterAgent");
+
+    // Create a session to maintain conversation context across multiple calls
+    AgentSession session = await writer.CreateSessionAsync();
+
+    // First call: generate an initial draft
+    AgentResponse<TextResponse> draft = await writer.RunAsync<TextResponse>(
+        message: "Write a concise inspirational sentence about learning.",
+        session: session);
+
+    // Second call: refine the draft — the agent sees the full conversation history
+    AgentResponse<TextResponse> refined = await writer.RunAsync<TextResponse>(
+        message: $"Improve this further while keeping it under 25 words: {draft.Result.Text}",
+        session: session);
+
+    return refined.Result.Text;
+}
+```
+
+**Python:**
+
+```python
+def writing_orchestration(context, _):
+    agent_ctx = DurableAIAgentOrchestrationContext(context)
+
+    # Get a durable agent reference — works in any host (standalone worker, Azure Functions, etc.)
+    writer = agent_ctx.get_agent("WriterAgent")
+
+    # Create a session to maintain conversation context across multiple calls
+    session = writer.create_session()
+
+    # First call: generate an initial draft
+    draft = yield writer.run(
+        messages="Write a concise inspirational sentence about learning.",
+        session=session,
+    )
+
+    # Second call: refine the draft — the agent sees the full conversation history
+    refined = yield writer.run(
+        messages=f"Improve this further while keeping it under 25 words: {draft.text}",
+        session=session,
+    )
+
+    return refined.text
+```
+
+> [!IMPORTANT]
+> In .NET, `DurableAIAgent.RunAsync<T>` deliberately avoids `ConfigureAwait(false)` because the Durable Task Framework uses a custom synchronization context — all continuations must run on the orchestration thread.
+
+## Streaming and response callbacks
+
+Durable agents do not support true end-to-end streaming because entity operations are request/response. However, **reliable streaming** is supported via response callbacks:
+
+- **`IAgentResponseHandler`** (.NET) or **`AgentResponseCallbackProtocol`** (Python) – Implement this interface to receive streaming updates as the underlying agent generates them (e.g., push tokens to a Redis Stream for client consumption).
+- The entity still returns the complete `AgentResponse` after the stream is fully consumed.
+- Clients can reconnect and resume reading from a cursor-based stream (e.g., Redis Streams) without losing messages.
+
+See the **Reliable Streaming** samples for a complete implementation using Redis Streams.
+
+## Session TTL (Time-To-Live)
+
+Durable agent sessions support automatic cleanup via configurable TTL. See [Session TTL](durable-agents-ttl.md) for details on configuration, behavior, and best practices.
+
+## Observability
+
+When using the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) as the durable backend, you get built-in observability through its dashboard:
+
+- **Conversation history** – View complete chat history for each agent session.
+- **Orchestration visualization** – See multi-agent execution flows, including parallel branches and conditional logic.
+- **Performance metrics** – Monitor agent response times, token usage, and orchestration duration.
+- **Debugging** – Trace tool invocations and external event handling.
+
+## Samples
+
+- **.NET** – [Console app samples](../../../dotnet/samples/Durable/Agents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/Durable/Agents/AzureFunctions/) covering single-agent, chaining, concurrency, conditionals, human-in-the-loop, long-running tools, MCP tool exposure, and reliable streaming.
+- **Python** – [Durable Task samples](../../../python/samples/04-hosting/durabletask/) covering single-agent, multi-agent, streaming, chaining, concurrency, conditionals, and human-in-the-loop.
+
+## Packages
+
+| Language | Package | Source |
+| --- | --- | --- |
+| .NET | `Microsoft.Agents.AI.DurableTask` | [`dotnet/src/Microsoft.Agents.AI.DurableTask`](../../../dotnet/src/Microsoft.Agents.AI.DurableTask) |
+| .NET | `Microsoft.Agents.AI.Hosting.AzureFunctions` | [`dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions`](../../../dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions) |
+| Python | `agent-framework-durabletask` | [`python/packages/durabletask`](../../../python/packages/durabletask) |
+| Python | `agent-framework-azurefunctions` | [`python/packages/azurefunctions`](../../../python/packages/azurefunctions) |
+
+## Further reading
+
+- [Azure Functions (Durable) — Microsoft Learn](https://learn.microsoft.com/agent-framework/integrations/azure-functions)
+- [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler)
+- [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities)
+- [Session TTL](durable-agents-ttl.md)

dotnet/.github/skills/build-and-test/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: build-and-test
+description: How to build and test .NET projects in the Agent Framework repository. Use this when verifying or testing changes.
+---
+
+- Only **UnitTest** projects need to be run locally; IntegrationTests require external dependencies.
+- See `../project-structure/SKILL.md` for project structure details.
+
+## Build, Test, and Lint Commands
+
+```bash
+# From dotnet/ directory
+dotnet restore --tl:off   # Restore dependencies for all projects
+dotnet build --tl:off     # Build all projects
+dotnet test               # Run all tests
+dotnet format             # Auto-fix formatting for all projects
+
+# Build/test/format a specific project (preferred for isolated/internal changes)
+dotnet build src/Microsoft.Agents.AI.<Package> --tl:off
+dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
+dotnet format src/Microsoft.Agents.AI.<Package>
+
+# Run a single test
+dotnet test --filter "FullyQualifiedName~Namespace.TestClassName.TestMethodName"
+
+# Run unit tests only
+dotnet test --filter FullyQualifiedName\~UnitTests
+```
+
+Use `--tl:off` when building to avoid flickering when running commands in the agent.
+
+## Speeding Up Builds and Testing
+
+The full solution is large. Use these shortcuts:
+
+| Change type | What to do |
+|-------------|------------|
+| Isolated/Internal logic | Build only the affected project and its `*.UnitTests` project. Fix issues, then build the full solution and run all unit tests. |
+| Public API surface | Build the full solution and run all unit tests immediately. |
+
+Example: Building a single code project for all target frameworks
+
+```bash
+# From dotnet/ directory
+dotnet build ./src/Microsoft.Agents.AI.Abstractions
+```
+
+Example: Building a single code project for just .NET 10.
+
+```bash
+# From dotnet/ directory
+dotnet build ./src/Microsoft.Agents.AI.Abstractions -f net10.0
+```
+
+Example: Running tests for a single project using .NET 10.
+
+```bash
+# From dotnet/ directory
+dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0
+```
+
+Example: Running a single test in a specific project using .NET 10.
+Provide the full namespace, class name, and method name for the test you want to run:
+
+```bash
+# From dotnet/ directory
+dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0 --filter "FullyQualifiedName~Microsoft.Agents.AI.Abstractions.UnitTests.AgentRunOptionsTests.CloningConstructorCopiesProperties"
+```
+
+### Multi-target framework tip
+
+Most projects target multiple .NET frameworks. If the affected code does **not** use `#if` directives for framework-specific logic, pass `-f net10.0` to speed up building and testing.
+
+### Package Restore tip
+
+`dotnet build` will try and restore packages for all projects on each build, which can be slow.
+Unless packages have been changed, or it's the first time building the solution, add `--no-restore` to the build command to skip this step and speed up builds.
+
+Just remember to run `dotnet restore` after pulling changes, making changes to project references, or when building for the first time.
+
+### Testing on Linux tip
+
+Unit tests target both .NET Framework as well as .NET Core. When running on Linux, only the .NET Core tests can be run, as .NET Framework is not supported on Linux.
+
+To run only the .NET Core tests, use the `-f net10.0` option with `dotnet test`.

dotnet/.github/skills/project-structure/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: project-structure
+description: Explains the project structure of the agent-framework .NET solution
+---
+
+# Agent Framework .NET Project Structure
+
+```
+dotnet/
+├── src/
+│   ├── Microsoft.Agents.AI/                      # Core AI agent implementations
+│   ├── Microsoft.Agents.AI.Abstractions/         # Core AI agent abstractions
+│   ├── Microsoft.Agents.AI.A2A/                  # Agent-to-Agent (A2A) provider
+│   ├── Microsoft.Agents.AI.OpenAI/               # OpenAI provider
+│   ├── Microsoft.Agents.AI.AzureAI/              # Azure AI Foundry Agents (v2) provider
+│   ├── Microsoft.Agents.AI.AzureAI.Persistent/   # Legacy Azure AI Foundry Agents (v1) provider
+│   ├── Microsoft.Agents.AI.Anthropic/            # Anthropic provider
+│   ├── Microsoft.Agents.AI.Workflows/            # Workflow orchestration
+│   └── ...                                       # Other packages
+├── samples/                                      # Sample applications
+└── tests/                                        # Unit and integration tests
+```
+
+## Main Folders
+
+| Folder | Contents |
+|--------|----------|
+| `src/` | Source code projects |
+| `tests/` | Test projects — named `<Source-Code-Project>.UnitTests` or `<Source-Code-Project>.IntegrationTests` |
+| `samples/` | Sample projects |
+| `src/Shared`, `src/LegacySupport` | Shared code files included by multiple source code projects (see README.md files in these folders or their subdirectories for instructions on how to include them in a project) |

dotnet/.github/skills/verify-dotnet-samples/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: verify-dotnet-samples
+description: How to build, run and verify the .NET sample projects in the Agent Framework repository. Use this when a user wants to verify that the samples still function as expected.
+---
+
+# Verifying .NET Sample Projects
+
+## Sample Pre-requisites
+
+We should only support verifying samples that:
+1. Use environment variables for configuration.
+2. Have no complex setup requirements, e.g., where multiple applications need to be run together, or where we need to launch a browser, etc.
+
+Always report to the user which samples were run and which were not, and why.
+
+## Verifying a sample
+
+Samples should be verified to ensure that they actually work as intended and that their output matches what is expected.
+For each sample that is run, output should be produced that shows the result and explains the reasoning about what output
+was expected, what was produced, and why it didn't match what the sample was expected to produce.
+
+Steps to verify a sample:
+1. Read the code for the sample
+1. Check what environment variables are required for the sample
+1. Check if each environment variable has been set
+1. If there are any missing, give the user a list of missing environment variables to set and terminate
+1. Summarize what the expected output of the sample should be
+1. Run the sample
+1. Show the user any output from the sample run as it gets produced, so that they can see the run progress
+1. Check the output of the run against expectations
+1. After running all requested samples, produce output for each sample that was verified:
+  1. If expectations were matched, output the following:
+     ```text
+     [Sample Name] Succeeded
+     ```
+  1. If expectations were not matched, output the following:
+     ```text
+     [Sample Name] Failed
+     Actual Output:
+     [What the sample produced]
+     Expected Output:
+     [Explanation of what was expected and why the actual output didn't match expectations]
+     ```
+
+## Environment Variables
+
+Most samples use environment variables to configure settings.
+
+```csharp
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+```
+
+To run a sample, the environment variables should be set first.
+Before running a sample, check whether each environment variable in the sample has a value and
+then give the user a list of environment variables to set.
+
+You can provide the user some examples of how to set the variables like this:
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://my-openai-instance.openai.azure.com/"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+To check if a variable has a value use e.g.:
+
+```bash
+echo $AZURE_OPENAI_ENDPOINT
+```
+
+## How to Run a Sample (General Pattern)
+
+```bash
+cd dotnet/samples/<category>/<sample-dir>
+dotnet run
+```
+
+For multi-targeted projects (e.g., Durable console apps), specify the framework:
+
+```bash
+dotnet run --framework net10.0
+```

dotnet/.vscode/settings.json

@@ -1,5 +1,6 @@
 {
     "dotnet.defaultSolution": "agent-framework-dotnet.slnx",
     "git.openRepositoryInParentFolders": "always",
-    "chat.agent.enabled": true
+    "chat.agent.enabled": true,
+    "dotnet.automaticallySyncWithActiveItem": true
 }

dotnet/AGENTS.md

@@ -4,41 +4,28 @@ Instructions for AI coding agents working in the .NET codebase.
 
 ## Build, Test, and Lint Commands
 
-```bash
-# From dotnet/ directory
-dotnet build              # Build all projects
-dotnet test               # Run all tests
-dotnet format             # Auto-fix formatting
-
-# Build/test a specific project (preferred for isolated changes)
-dotnet build src/Microsoft.Agents.AI.<Package>
-dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
-
-# Run a single test
-dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"
-```
-
-**Note**: Changes to core packages (`Microsoft.Agents.AI`, `Microsoft.Agents.AI.Abstractions`) affect dependent projects - run checks across the entire solution. For isolated changes, build/test only the affected project to save time.
+See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects.
 
 ## Project Structure
 
-```
-dotnet/
-├── src/
-│   ├── Microsoft.Agents.AI/              # Core AI agent abstractions
-│   ├── Microsoft.Agents.AI.Abstractions/ # Shared abstractions and interfaces
-│   ├── Microsoft.Agents.AI.OpenAI/       # OpenAI provider
-│   ├── Microsoft.Agents.AI.AzureAI/      # Azure AI provider
-│   ├── Microsoft.Agents.AI.Anthropic/    # Anthropic provider
-│   ├── Microsoft.Agents.AI.Workflows/    # Workflow orchestration
-│   └── ...                               # Other packages
-├── samples/                              # Sample applications
-└── tests/                                # Unit and integration tests
-```
+See `./.github/skills/project-structure/SKILL.md` for an overview of the project structure.
+
+### Core types
+
+- `AIAgent`: The abstract base class that all agents derive from, providing common methods for interacting with an agent.
+- `AgentSession`: The abstract base class that all agent sessions derive from, representing a conversation with an agent.
+- `ChatClientAgent`: An `AIAgent` implementation that uses an `IChatClient` to send messages to an AI provider and receive responses.
+- `IChatClient`: Interface for sending messages to an AI provider and receiving responses. Used by `ChatClientAgent` and implemented by provider-specific packages.
+- `FunctionInvokingChatClient`: Decorator for `IChatClient` that adds function invocation capabilities.
+- `AITool`: Represents a tool that an agent/AI provider can use, with metadata and an execution delegate.
+- `AIFunction`: A specific type of `AITool` that represents a local function the agent/AI provider can call, with parameters and return types defined.
+- `ChatMessage`: Represents a message in a conversation.
+- `AIContent`: Represents content in a message, which can be text, a function call, tool output and more.
 
 ### External Dependencies
 
-The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages) using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, and `AIContent`.
+The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages)
+using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, `AIFunction`, `ChatMessage`, and `AIContent`.
 
 ## Key Conventions
 
@@ -49,8 +36,19 @@ The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extension
 - **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
 - **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
 
+## Key Design Principles
+
+When developing or reviewing code, verify adherence to these key design principles:
+
+- **DRY**: Avoid code duplication by moving common logic into helper methods or helper classes.
+- **Single Responsibility**: Each class should have one clear responsibility.
+- **Encapsulation**: Keep implementation details private and expose only necessary public APIs.
+- **Strong Typing**: Use strong typing to ensure that code is self-documenting and to catch errors at compile time.
+
 ## Sample Structure
 
+Samples (in `./samples/` folder) should follow this structure:
+
 1. Copyright header: `// Copyright (c) Microsoft. All rights reserved.`
 2. Description comment explaining what the sample demonstrates
 3. Using statements
@@ -60,6 +58,7 @@ The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extension
 Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.
 
 When adding a new sample:
+
 - Create a standalone project in `samples/` with matching directory and project names
 - Include a README.md explaining what the sample does and how to run it
 - Add the project to the solution file

dotnet/Directory.Packages.props

@@ -42,7 +42,7 @@
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.3" />
     <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.1" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.3" />
     <PackageVersion Include="System.Text.Json" Version="10.0.3" />
     <PackageVersion Include="System.Threading.Channels" Version="10.0.3" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
@@ -63,6 +63,9 @@
     <!-- Microsoft.Extensions.* -->
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.3.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.3.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
@@ -99,7 +102,7 @@
     <PackageVersion Include="A2A" Version="0.3.3-preview" />
     <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
     <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.8.0-preview.1" />
     <!-- Inference SDKs -->
     <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5.1" />
     <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
@@ -108,10 +111,10 @@
     <!-- Identity -->
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
     <!-- Workflows -->
-    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.1.2.3" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.1.2.3" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.1.2.3" />
-    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.5.0-build.20251008-1002" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.8.1" />
     <!-- Durable Task -->
     <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.18.0" />
     <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.18.0" />

dotnet/agent-framework-dotnet.slnx

@@ -176,6 +176,10 @@
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
     <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step19_OpenAPITools/FoundryAgents_Step19_OpenAPITools.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step18_FileSearch/FoundryAgents_Step18_FileSearch.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
     <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
@@ -213,6 +217,7 @@
     <Project Path="samples/GettingStarted/Workflows/Declarative/Marketing/Marketing.csproj" />
     <Project Path="samples/GettingStarted/Workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
     <Project Path="samples/GettingStarted/Workflows/Declarative/ToolApproval/ToolApproval.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
     <File Path="../workflow-samples/CustomerSupport.yaml" />
@@ -371,6 +376,10 @@
     <File Path="src/Shared/Demos/README.md" />
     <File Path="src/Shared/Demos/SampleEnvironment.cs" />
   </Folder>
+  <Folder Name="/Solution Items/src/Shared/DiagnosticIds/">
+    <File Path="src/Shared/DiagnosticIds/DiagnosticsIds.cs" />
+    <File Path="src/Shared/DiagnosticIds/README.md" />
+  </Folder>
   <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
     <File Path="src/Shared/IntegrationTests/AnthropicConfiguration.cs" />
     <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
@@ -389,6 +398,9 @@
     <File Path="src/Shared/Throw/README.md" />
     <File Path="src/Shared/Throw/Throw.cs" />
   </Folder>
+  <Folder Name="/Solution Items/src/Shared/StructuredOutput/">
+    <File Path="src/Shared/StructuredOutput/StructuredOutputSchemaUtilities.cs" />
+  </Folder>
   <Folder Name="/Solution Items/tests/">
     <File Path="tests/.editorconfig" />
     <File Path="tests/Directory.Build.props" />
@@ -398,7 +410,6 @@
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
@@ -406,6 +417,7 @@
     <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
@@ -417,8 +429,8 @@
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
     <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
   </Folder>
   <Folder Name="/Tests/" />
@@ -428,8 +440,8 @@
     <Project Path="tests/AzureAI.IntegrationTests/AzureAI.IntegrationTests.csproj" />
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
@@ -443,13 +455,13 @@
     <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />

dotnet/eng/MSBuild/Shared.props

@@ -20,4 +20,10 @@
   <ItemGroup Condition="'$(InjectSharedFoundryAgents)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Foundry\Agents\*.cs" LinkBase="Shared\Foundry" />
   </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedStructuredOutput)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\StructuredOutput\*.cs" LinkBase="Shared\StructuredOutput" />
+  </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedDiagnosticIds)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\DiagnosticIds\*.cs" LinkBase="Shared\DiagnosticIds" />
+  </ItemGroup>
 </Project>

dotnet/nuget/nuget-package.props

@@ -2,9 +2,11 @@
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
     <VersionPrefix>1.0.0</VersionPrefix>
-    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260212.1</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260212.1</PackageVersion>
-    <GitTag>1.0.0-preview.260212.1</GitTag>
+    <RCNumber>1</RCNumber>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260219.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260219.1</PackageVersion>
+    <GitTag>1.0.0-rc1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/AGUIClientServer/AGUIDojoServer/SharedState/SharedStateAgent.cs

@@ -78,7 +78,7 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
 
         var response = allUpdates.ToAgentResponse();
 
-        if (response.TryDeserialize(this._jsonSerializerOptions, out JsonElement stateSnapshot))
+        if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
         {
             byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
                 stateSnapshot,
@@ -103,4 +103,25 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
             yield return update;
         }
     }
+
+    private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
+    {
+        try
+        {
+            T? result = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
+            if (result is null)
+            {
+                structuredOutput = default!;
+                return false;
+            }
+
+            structuredOutput = result;
+            return true;
+        }
+        catch
+        {
+            structuredOutput = default!;
+            return false;
+        }
+    }
 }

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs

@@ -107,7 +107,7 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
         var response = allUpdates.ToAgentResponse();
 
         // Try to deserialize the structured state response
-        if (response.TryDeserialize(this._jsonSerializerOptions, out JsonElement stateSnapshot))
+        if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
         {
             // Serialize and emit as STATE_SNAPSHOT via DataContent
             byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
@@ -134,4 +134,25 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
             yield return update;
         }
     }
+
+    private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
+    {
+        try
+        {
+            T? deserialized = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
+            if (deserialized is null)
+            {
+                structuredOutput = default!;
+                return false;
+            }
+
+            structuredOutput = deserialized;
+            return true;
+        }
+        catch
+        {
+            structuredOutput = default!;
+            return false;
+        }
+    }
 }

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/Program.cs

@@ -88,25 +88,29 @@ namespace SampleApp
     /// </summary>
     internal sealed class UserInfoMemory : AIContextProvider
     {
+        private readonly ProviderSessionState<UserInfo> _sessionState;
         private readonly IChatClient _chatClient;
-        private readonly Func<AgentSession?, UserInfo> _stateInitializer;
 
         public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = null)
+            : base(null, null)
         {
+            this._sessionState = new ProviderSessionState<UserInfo>(
+                stateInitializer ?? (_ => new UserInfo()),
+                this.GetType().Name);
             this._chatClient = chatClient;
-            this._stateInitializer = stateInitializer ?? (_ => new UserInfo());
         }
 
+        public override string StateKey => this._sessionState.StateKey;
+
         public UserInfo GetUserInfo(AgentSession session)
-            => session.StateBag.GetValue<UserInfo>(nameof(UserInfoMemory)) ?? new UserInfo();
+            => this._sessionState.GetOrInitializeState(session);
 
         public void SetUserInfo(AgentSession session, UserInfo userInfo)
-            => session.StateBag.SetValue(nameof(UserInfoMemory), userInfo);
+            => this._sessionState.SaveState(session, userInfo);
 
-        protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default)
         {
-            var userInfo = context.Session?.StateBag.GetValue<UserInfo>(nameof(UserInfoMemory))
-                ?? this._stateInitializer.Invoke(context.Session);
+            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
 
             // Try and extract the user name and age from the message if we don't have it already and it's a user message.
             if ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
@@ -123,20 +127,14 @@ namespace SampleApp
                 userInfo.UserAge ??= result.Result.UserAge;
             }
 
-            context.Session?.StateBag.SetValue(nameof(UserInfoMemory), userInfo);
+            this._sessionState.SaveState(context.Session, userInfo);
         }
 
-        protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
-            var inputContext = context.AIContext;
-            var userInfo = context.Session?.StateBag.GetValue<UserInfo>(nameof(UserInfoMemory))
-                ?? this._stateInitializer.Invoke(context.Session);
+            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
 
             StringBuilder instructions = new();
-            if (!string.IsNullOrEmpty(inputContext.Instructions))
-            {
-                instructions.AppendLine(inputContext.Instructions);
-            }
 
             // If we don't already know the user's name and age, add instructions to ask for them, otherwise just provide what we have to the context.
             instructions
@@ -151,9 +149,7 @@ namespace SampleApp
 
             return new ValueTask<AIContext>(new AIContext
             {
-                Instructions = instructions.ToString(),
-                Messages = inputContext.Messages,
-                Tools = inputContext.Tools
+                Instructions = instructions.ToString()
             });
         }
     }

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs

@@ -62,7 +62,7 @@ TextSearchProviderOptions textSearchOptions = new()
 {
     // Run the search prior to every model invocation.
     SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
-    // Use up to 4 recent messages when searching so that searches
+    // Use up to 5 recent messages when searching so that searches
     // still produce valuable results even when the user is referring
     // back to previous messages in their request.
     RecentMessageMemoryLimit = 5
@@ -74,7 +74,14 @@ AIAgent agent = azureOpenAIClient
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
-        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)]
+        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        // Configure a filter on the InMemoryChatHistoryProvider so that we don't persist the messages produced by the TextSearchProvider in chat history.
+        // The default is to persist all messages except those that came from chat history in the first place.
+        // You may choose to persist the TextSearchProvider messages, if you want the search output to be provided to the model in future interactions as well.
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions()
+        {
+            StorageInputMessageFilter = msgs => msgs.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider)
+        })
     });
 
 AgentSession session = await agent.CreateSessionAsync();

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/AIAgentBuilderExtensions.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace SampleApp;
+
+/// <summary>
+/// Provides extension methods for adding structured output capabilities to <see cref="AIAgentBuilder"/> instances.
+/// </summary>
+internal static class AIAgentBuilderExtensions
+{
+    /// <summary>
+    /// Adds structured output capabilities to the agent pipeline, enabling conversion of text responses to structured JSON format.
+    /// </summary>
+    /// <param name="builder">The <see cref="AIAgentBuilder"/> to which structured output support will be added.</param>
+    /// <param name="chatClient">
+    /// The chat client used to transform text responses into structured JSON format.
+    /// If <see langword="null"/>, the chat client will be resolved from the service provider.
+    /// </param>
+    /// <param name="optionsFactory">
+    /// An optional factory function that returns the <see cref="StructuredOutputAgentOptions"/> instance to use.
+    /// This allows for fine-tuning the structured output behavior such as setting the response format or system message.
+    /// </param>
+    /// <returns>The <see cref="AIAgentBuilder"/> with structured output capabilities added, enabling method chaining.</returns>
+    /// <remarks>
+    /// <para>
+    /// A <see cref="ChatResponseFormatJson"/> must be specified either through the
+    /// <see cref="AgentRunOptions.ResponseFormat"/> at runtime or the <see cref="StructuredOutputAgentOptions.ChatOptions"/>
+    /// provided during configuration.
+    /// </para>
+    /// </remarks>
+    public static AIAgentBuilder UseStructuredOutput(
+        this AIAgentBuilder builder,
+        IChatClient? chatClient = null,
+        Func<StructuredOutputAgentOptions>? optionsFactory = null)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        return builder.Use((innerAgent, services) =>
+        {
+            chatClient ??= services?.GetService<IChatClient>()
+                ?? throw new InvalidOperationException($"No {nameof(IChatClient)} was provided and none could be resolved from the service provider. Either provide an {nameof(IChatClient)} explicitly or register one in the dependency injection container.");
+
+            return new StructuredOutputAgent(innerAgent, chatClient, optionsFactory?.Invoke());
+        });
+    }
+}

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs

@@ -8,11 +8,13 @@ using System.Text.Json.Serialization;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
 using OpenAI.Chat;
 using SampleApp;
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create chat client to be used by chat client agents.
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
@@ -23,52 +25,159 @@ ChatClient chatClient = new AzureOpenAIClient(
     new DefaultAzureCredential())
         .GetChatClient(deploymentName);
 
-// Create the ChatClientAgent with the specified name and instructions.
-ChatClientAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+// Demonstrates how to work with structured output via ResponseFormat with the non-generic RunAsync method.
+// This approach is useful when:
+// a. Structured output is used for inter-agent communication, where one agent produces structured output
+//    and passes it as text to another agent as input, without the need for the caller to directly work with the structured output.
+// b. The type of the structured output is not known at compile time, so the generic RunAsync<T> method cannot be used.
+// c. The type of the structured output is represented by JSON schema only, without a corresponding class or type in the code.
+await UseStructuredOutputWithResponseFormatAsync(chatClient);
 
-// Set PersonInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke the agent with some unstructured input.
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
+// Demonstrates how to work with structured output via the generic RunAsync<T> method.
+// This approach is useful when the caller needs to directly work with the structured output in the code
+// via an instance of the corresponding class or type and the type is known at compile time.
+await UseStructuredOutputWithRunAsync(chatClient);
 
-// Access the structured output via the Result property of the agent response.
-Console.WriteLine("Assistant Output:");
-Console.WriteLine($"Name: {response.Result.Name}");
-Console.WriteLine($"Age: {response.Result.Age}");
-Console.WriteLine($"Occupation: {response.Result.Occupation}");
+// Demonstrates how to work with structured output when streaming using the RunStreamingAsync method.
+await UseStructuredOutputWithRunStreamingAsync(chatClient);
 
-// Create the ChatClientAgent with the specified name, instructions, and expected structured output the agent should produce.
-ChatClientAgent agentWithPersonInfo = chatClient.AsAIAgent(new ChatClientAgentOptions()
+// Demonstrates how to add structured output support to agents that don't natively support it using the structured output middleware.
+// This approach is useful when working with agents that don't support structured output natively, or agents using models
+// that don't have the capability to produce structured output, allowing you to still leverage structured output features by transforming
+// the text output from the agent into structured data using a chat client.
+await UseStructuredOutputWithMiddlewareAsync(chatClient);
+
+static async Task UseStructuredOutputWithResponseFormatAsync(ChatClient chatClient)
 {
-    Name = "HelpfulAssistant",
-    ChatOptions = new() { Instructions = "You are a helpful assistant.", ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-});
+    Console.WriteLine("=== Structured Output with ResponseFormat ===");
 
-// Invoke the agent with some unstructured input while streaming, to extract the structured information from.
-var updates = agentWithPersonInfo.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
+    // Create the agent
+    AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+    {
+        Name = "HelpfulAssistant",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant.",
+            // Specify CityInfo as the type parameter of ForJsonSchema to indicate the expected structured output from the agent.
+            ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<CityInfo>()
+        }
+    });
 
-// Assemble all the parts of the streamed output, since we can only deserialize once we have the full json,
-// then deserialize the response into the PersonInfo class.
-PersonInfo personInfo = (await updates.ToAgentResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);
+    // Invoke the agent with some unstructured input to extract the structured information from.
+    AgentResponse response = await agent.RunAsync("Provide information about the capital of France.");
 
-Console.WriteLine("Assistant Output:");
-Console.WriteLine($"Name: {personInfo.Name}");
-Console.WriteLine($"Age: {personInfo.Age}");
-Console.WriteLine($"Occupation: {personInfo.Occupation}");
+    // Access the structured output via the Text property of the agent response as JSON in scenarios when JSON as text is required
+    // and no object instance is needed (e.g., for logging, forwarding to another service, or storing in a database).
+    Console.WriteLine("Assistant Output (JSON):");
+    Console.WriteLine(response.Text);
+    Console.WriteLine();
+
+    // Deserialize the JSON text to work with the structured object in scenarios when you need to access properties,
+    // perform operations, or pass the data to methods that require the typed object instance.
+    CityInfo cityInfo = JsonSerializer.Deserialize<CityInfo>(response.Text)!;
+
+    Console.WriteLine("Assistant Output (Deserialized):");
+    Console.WriteLine($"Name: {cityInfo.Name}");
+    Console.WriteLine();
+}
+
+static async Task UseStructuredOutputWithRunAsync(ChatClient chatClient)
+{
+    Console.WriteLine("=== Structured Output with RunAsync<T> ===");
+
+    // Create the agent
+    AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+
+    // Set CityInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke it with some unstructured input.
+    AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about the capital of France.");
+
+    // Access the structured output via the Result property of the agent response.
+    CityInfo cityInfo = response.Result;
+
+    Console.WriteLine("Assistant Output:");
+    Console.WriteLine($"Name: {cityInfo.Name}");
+    Console.WriteLine();
+}
+
+static async Task UseStructuredOutputWithRunStreamingAsync(ChatClient chatClient)
+{
+    Console.WriteLine("=== Structured Output with RunStreamingAsync ===");
+
+    // Create the agent
+    AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+    {
+        Name = "HelpfulAssistant",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant.",
+            // Specify CityInfo as the type parameter of ForJsonSchema to indicate the expected structured output from the agent.
+            ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<CityInfo>()
+        }
+    });
+
+    // Invoke the agent with some unstructured input while streaming, to extract the structured information from.
+    IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Provide information about the capital of France.");
+
+    // Assemble all the parts of the streamed output.
+    AgentResponse nonGenericResponse = await updates.ToAgentResponseAsync();
+
+    // Access the structured output by deserializing JSON in the Text property.
+    CityInfo cityInfo = JsonSerializer.Deserialize<CityInfo>(nonGenericResponse.Text)!;
+
+    Console.WriteLine("Assistant Output:");
+    Console.WriteLine($"Name: {cityInfo.Name}");
+    Console.WriteLine();
+}
+
+static async Task UseStructuredOutputWithMiddlewareAsync(ChatClient chatClient)
+{
+    Console.WriteLine("=== Structured Output with UseStructuredOutput Middleware ===");
+
+    // Create chat client that will transform the agent text response into structured output.
+    IChatClient meaiChatClient = chatClient.AsIChatClient();
+
+    // Create the agent
+    AIAgent agent = meaiChatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
+
+    // Add structured output middleware via UseStructuredOutput method to add structured output support to the agent.
+    // This middleware transforms the agent's text response into structured data using a chat client.
+    // Since our agent does support structured output natively, we will add a middleware that removes ResponseFormat
+    //  from the AgentRunOptions to emulate an agent that doesn't support structured output natively
+    agent = agent
+        .AsBuilder()
+        .UseStructuredOutput(meaiChatClient)
+        .Use(ResponseFormatRemovalMiddleware, null)
+        .Build();
+
+    // Set CityInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke it with some unstructured input.
+    AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about the capital of France.");
+
+    // Access the structured output via the Result property of the agent response.
+    CityInfo cityInfo = response.Result;
+
+    Console.WriteLine("Assistant Output:");
+    Console.WriteLine($"Name: {cityInfo.Name}");
+    Console.WriteLine();
+}
+
+static Task<AgentResponse> ResponseFormatRemovalMiddleware(IEnumerable<ChatMessage> messages, AgentSession? session, AgentRunOptions? options, AIAgent innerAgent, CancellationToken cancellationToken)
+{
+    // Remove any ResponseFormat from the options to emulate an agent that doesn't support structured output natively.
+    options = options?.Clone();
+    options?.ResponseFormat = null;
+
+    return innerAgent.RunAsync(messages, session, options, cancellationToken);
+}
 
 namespace SampleApp
 {
     /// <summary>
-    /// Represents information about a person, including their name, age, and occupation, matched to the JSON schema used in the agent.
+    /// Represents information about a city, including its name.
     /// </summary>
-    [Description("Information about a person including their name, age, and occupation")]
-    public class PersonInfo
+    [Description("Information about a city")]
+    public sealed class CityInfo
     {
         [JsonPropertyName("name")]
         public string? Name { get; set; }
-
-        [JsonPropertyName("age")]
-        public int? Age { get; set; }
-
-        [JsonPropertyName("occupation")]
-        public string? Occupation { get; set; }
     }
 }

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/README.md

@@ -0,0 +1,52 @@
+# Structured Output with ChatClientAgent
+
+This sample demonstrates how to configure ChatClientAgent to produce structured output in JSON format using various approaches.
+
+## What this sample demonstrates
+
+- **ResponseFormat approach**: Configuring agents with JSON schema response format via `ChatResponseFormat.ForJsonSchema<T>()` for inter-agent communication or when the type is not known at compile time
+- **Generic RunAsync<T> method**: Using the generic `RunAsync<T>` method for structured output when the caller needs to work directly with typed objects
+- **Structured output with Streaming**: Using `RunStreamingAsync` to stream responses while still obtaining structured output by assembling and deserializing the streamed content
+- **StructuredOutput middleware**: Adding structured output support to agents that don't natively support it (like A2A agents or models without structured output capability) by transforming text output into structured data using a chat client
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
+
+**Note**: This sample uses Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+## Environment Variables
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+Navigate to the sample directory and run:
+
+```powershell
+cd dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput
+dotnet run
+```
+
+## Expected behavior
+
+The sample will demonstrate four different approaches to structured output:
+
+1. **Structured Output with ResponseFormat**: Creates an agent with `ResponseFormat` set to `ForJsonSchema<CityInfo>()`, invokes it with unstructured input, and accesses the structured output via the `Text` property
+2. **Structured Output with RunAsync<T>**: Creates an agent and uses the generic `RunAsync<CityInfo>()` method to get a typed `AgentResponse<CityInfo>` with the result accessible via the `Result` property
+3. **Structured Output with RunStreamingAsync**: Creates an agent with JSON schema response format, streams the response using `RunStreamingAsync`, assembles the updates using `ToAgentResponseAsync()`, and deserializes the JSON text into a typed object
+4. **Structured Output with StructuredOutput Middleware**: Uses the `UseStructuredOutput` method on `AIAgentBuilder` to add structured output support to agents that don't natively support it
+
+Each approach will output information about the capital of France (Paris) in a structured format.

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/StructuredOutputAgent.cs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// A delegating AI agent that converts text responses from an inner AI agent into structured output using a chat client.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="StructuredOutputAgent"/> wraps an inner agent and uses a chat client to transform
+/// the inner agent's text response into a structured JSON format based on the specified response format.
+/// </para>
+/// <para>
+/// This agent requires a <see cref="ChatResponseFormatJson"/> to be specified either through the
+/// <see cref="AgentRunOptions.ResponseFormat"/> or the <see cref="StructuredOutputAgentOptions.ChatOptions"/>
+/// provided during construction.
+/// </para>
+/// </remarks>
+internal sealed class StructuredOutputAgent : DelegatingAIAgent
+{
+    private readonly IChatClient _chatClient;
+    private readonly StructuredOutputAgentOptions? _agentOptions;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="StructuredOutputAgent"/> class.
+    /// </summary>
+    /// <param name="innerAgent">The underlying agent that generates text responses to be converted to structured output.</param>
+    /// <param name="chatClient">The chat client used to transform text responses into structured JSON format.</param>
+    /// <param name="options">Optional configuration options for the structured output agent.</param>
+    public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient, StructuredOutputAgentOptions? options = null)
+        : base(innerAgent)
+    {
+        this._chatClient = chatClient ?? throw new ArgumentNullException(nameof(chatClient));
+        this._agentOptions = options;
+    }
+
+    /// <inheritdoc />
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        // Run the inner agent first, to get back the text response we want to convert.
+        var textResponse = await this.InnerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+
+        // Invoke the chat client to transform the text output into structured data.
+        ChatResponse soResponse = await this._chatClient.GetResponseAsync(
+            messages: this.GetChatMessages(textResponse.Text),
+            options: this.GetChatOptions(options),
+            cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        return new StructuredOutputAgentResponse(soResponse, textResponse);
+    }
+
+    private List<ChatMessage> GetChatMessages(string? textResponseText)
+    {
+        List<ChatMessage> chatMessages = [];
+
+        if (this._agentOptions?.ChatClientSystemMessage is not null)
+        {
+            chatMessages.Add(new ChatMessage(ChatRole.System, this._agentOptions.ChatClientSystemMessage));
+        }
+
+        chatMessages.Add(new ChatMessage(ChatRole.User, textResponseText));
+
+        return chatMessages;
+    }
+
+    private ChatOptions GetChatOptions(AgentRunOptions? options)
+    {
+        ChatResponseFormat responseFormat = options?.ResponseFormat
+            ?? this._agentOptions?.ChatOptions?.ResponseFormat
+            ?? throw new InvalidOperationException($"A response format of type '{nameof(ChatResponseFormatJson)}' must be specified, but none was specified.");
+
+        if (responseFormat is not ChatResponseFormatJson jsonResponseFormat)
+        {
+            throw new NotSupportedException($"A response format of type '{nameof(ChatResponseFormatJson)}' must be specified, but was '{responseFormat.GetType().Name}'.");
+        }
+
+        var chatOptions = this._agentOptions?.ChatOptions?.Clone() ?? new ChatOptions();
+        chatOptions.ResponseFormat = jsonResponseFormat;
+        return chatOptions;
+    }
+}

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/StructuredOutputAgentOptions.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// Represents configuration options for a <see cref="StructuredOutputAgent"/>.
+/// </summary>
+#pragma warning disable CA1812 // Instantiated via AIAgentBuilderExtensions.UseStructuredOutput optionsFactory parameter
+internal sealed class StructuredOutputAgentOptions
+#pragma warning restore CA1812
+{
+    /// <summary>
+    /// Gets or sets the system message to use when invoking the chat client for structured output conversion.
+    /// </summary>
+    public string? ChatClientSystemMessage { get; set; }
+
+    /// <summary>
+    /// Gets or sets the chat options to use for the structured output conversion by the chat client
+    /// used by the agent.
+    /// </summary>
+    /// <remarks>
+    /// This property is optional. The <see cref="ChatOptions.ResponseFormat"/> should be set to a
+    /// <see cref="ChatResponseFormatJson"/> instance to specify the expected JSON schema for the structured output.
+    /// Note that if <see cref="AgentRunOptions.ResponseFormat"/> is provided when running the agent,
+    /// it will take precedence and override the <see cref="ChatOptions.ResponseFormat"/> specified here.
+    /// </remarks>
+    public ChatOptions? ChatOptions { get; set; }
+}

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/StructuredOutputAgentResponse.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// Represents an agent response that contains structured output and
+/// the original agent response from which the structured output was generated.
+/// </summary>
+internal sealed class StructuredOutputAgentResponse : AgentResponse
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="StructuredOutputAgentResponse"/> class.
+    /// </summary>
+    /// <param name="chatResponse">The <see cref="ChatResponse"/> containing the structured output.</param>
+    /// <param name="agentResponse">The original <see cref="AgentResponse"/> from the inner agent.</param>
+    public StructuredOutputAgentResponse(ChatResponse chatResponse, AgentResponse agentResponse) : base(chatResponse)
+    {
+        this.OriginalResponse = agentResponse;
+    }
+
+    /// <summary>
+    /// Gets the original non-structured response from the inner agent used by chat client to produce the structured output.
+    /// </summary>
+    public AgentResponse OriginalResponse { get; }
+}

dotnet/samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
+
 // This sample shows how to create and use a simple AI agent with a conversation that can be persisted to disk.
 
 using System.Text.Json;
@@ -30,15 +32,14 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session
 // Serialize the session state to a JsonElement, so it can be stored for later use.
 JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 
-// Save the serialized session to a temporary file (for demonstration purposes).
-string tempFilePath = Path.GetTempFileName();
-await File.WriteAllTextAsync(tempFilePath, JsonSerializer.Serialize(serializedSession));
-
-// Load the serialized session from the temporary file (for demonstration purposes).
-JsonElement reloadedSerializedSession = JsonElement.Parse(await File.ReadAllTextAsync(tempFilePath));
+// In a real application, you would typically write the serialized session to a file or
+// database for persistence, and read it back when resuming the conversation.
+// Here we'll just write the serialized session to console (for demonstration purposes).
+Console.WriteLine("\n--- Serialized session ---\n");
+Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }) + "\n");
 
 // Deserialize the session state after loading from storage.
-AgentSession resumedSession = await agent.DeserializeSessionAsync(reloadedSerializedSession);
+AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSession);
 
 // Run the agent again with the resumed session.
 Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));

dotnet/samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Program.cs

@@ -78,45 +78,29 @@ namespace SampleApp
     /// </summary>
     internal sealed class VectorChatHistoryProvider : ChatHistoryProvider
     {
+        private readonly ProviderSessionState<State> _sessionState;
         private readonly VectorStore _vectorStore;
-        private readonly Func<AgentSession?, State> _stateInitializer;
-        private readonly string _stateKey;
-
-        /// <inheritdoc />
-        public override string StateKey => this._stateKey;
 
         public VectorChatHistoryProvider(
             VectorStore vectorStore,
             Func<AgentSession?, State>? stateInitializer = null,
             string? stateKey = null)
+            : base(provideOutputMessageFilter: null, storeInputMessageFilter: null)
         {
+            this._sessionState = new ProviderSessionState<State>(
+                stateInitializer ?? (_ => new State(Guid.NewGuid().ToString("N"))),
+                stateKey ?? this.GetType().Name);
             this._vectorStore = vectorStore ?? throw new ArgumentNullException(nameof(vectorStore));
-            this._stateInitializer = stateInitializer ?? (_ => new State(Guid.NewGuid().ToString("N")));
-            this._stateKey = stateKey ?? base.StateKey;
         }
 
+        public override string StateKey => this._sessionState.StateKey;
+
         public string GetSessionDbKey(AgentSession session)
-            => this.GetOrInitializeState(session).SessionDbKey;
+            => this._sessionState.GetOrInitializeState(session).SessionDbKey;
 
-        private State GetOrInitializeState(AgentSession? session)
+        protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
-            if (session?.StateBag.TryGetValue<State>(this._stateKey, out var state) is true && state is not null)
-            {
-                return state;
-            }
-
-            state = this._stateInitializer(session);
-            if (session is not null)
-            {
-                session.StateBag.SetValue(this._stateKey, state);
-            }
-
-            return state;
-        }
-
-        protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        {
-            var state = this.GetOrInitializeState(context.Session);
+            var state = this._sessionState.GetOrInitializeState(context.Session);
             var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
             await collection.EnsureCollectionExistsAsync(cancellationToken);
 
@@ -129,29 +113,17 @@ namespace SampleApp
 
             var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!);
             messages.Reverse();
-            return messages
-                .Select(message => message.WithAgentRequestMessageSource(AgentRequestMessageSourceType.ChatHistory, this.GetType().FullName!))
-                .Concat(context.RequestMessages);
+            return messages;
         }
 
-        protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
         {
-            // Don't store messages if the request failed.
-            if (context.InvokeException is not null)
-            {
-                return;
-            }
-
-            var state = this.GetOrInitializeState(context.Session);
+            var state = this._sessionState.GetOrInitializeState(context.Session);
 
             var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
             await collection.EnsureCollectionExistsAsync(cancellationToken);
 
-            // Add both request and response messages to the store, excluding messages that came from chat history.
-            // Optionally messages produced by the AIContextProvider can also be persisted (not shown).
-            var allNewMessages = context.RequestMessages
-                .Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
-                .Concat(context.ResponseMessages ?? []);
+            var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
 
             await collection.UpsertAsync(allNewMessages.Select(x => new ChatHistoryItem()
             {

dotnet/samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/README.md

@@ -11,9 +11,9 @@ Alternatively, use the QuickstartClient sample from this repository: https://git
 To use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), follow these steps:
 
 1. Open a terminal in the Agent_Step10_AsMcpTool project directory.
-1. Run the `npx @modelcontextprotocol/inspector dotnet run` command to start the MCP Inspector. Make sure you have [node.js](https://nodejs.org/en/download/) and npm installed.
+1. Run the `npx @modelcontextprotocol/inspector dotnet run --framework net10.0` command to start the MCP Inspector. Make sure you have [node.js](https://nodejs.org/en/download/) and npm installed.
    ```bash
-   npx @modelcontextprotocol/inspector dotnet run
+   npx @modelcontextprotocol/inspector dotnet run --framework net10.0
    ```
 1. When the inspector is running, it will display a URL in the terminal, like this:
    ```

dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/Program.cs

@@ -2,8 +2,9 @@
 
 // This sample shows multiple middleware layers working together with Azure OpenAI:
 // chat client (global/per-request), agent run (PII filtering and guardrails),
-// function invocation (logging and result overrides), and human-in-the-loop
-// approval workflows for sensitive function calls.
+// function invocation (logging and result overrides), human-in-the-loop
+// approval workflows for sensitive function calls, and MessageAIContextProvider
+// middleware for injecting additional context messages into the agent pipeline.
 
 using System.ComponentModel;
 using System.Text.RegularExpressions;
@@ -96,6 +97,20 @@ var response = await originalAgent // Using per-request middleware pipeline with
 
 Console.WriteLine($"Per-request middleware response: {response}");
 
+// MessageAIContextProvider middleware that injects additional messages into the agent request.
+// This allows any AIAgent (not just ChatClientAgent) to benefit from MessageAIContextProvider-based
+// context enrichment. Multiple providers can be passed to Use and they are called in sequence,
+// each receiving the output of the previous one.
+Console.WriteLine("\n\n=== Example 5: MessageAIContextProvider middleware ===");
+
+var contextProviderAgent = originalAgent
+    .AsBuilder()
+    .Use([new DateTimeContextProvider()])
+    .Build();
+
+var contextResponse = await contextProviderAgent.RunAsync("Is it almost time for lunch?");
+Console.WriteLine($"Context-enriched response: {contextResponse}");
+
 // Function invocation middleware that logs before and after function calls.
 async ValueTask<object?> FunctionCallMiddleware(AIAgent agent, FunctionInvocationContext context, Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next, CancellationToken cancellationToken)
 {
@@ -259,3 +274,23 @@ async Task<ChatResponse> PerRequestChatClientMiddleware(IEnumerable<ChatMessage>
 
     return response;
 }
+
+/// <summary>
+/// A <see cref="MessageAIContextProvider"/> that injects the current date and time into the agent's context.
+/// This is a simple example of how to use a MessageAIContextProvider to enrich agent messages
+/// via the <see cref="AIAgentBuilder.Use(MessageAIContextProvider[])"/> extension method.
+/// </summary>
+internal sealed class DateTimeContextProvider : MessageAIContextProvider
+{
+    protected override ValueTask<IEnumerable<ChatMessage>> ProvideMessagesAsync(
+        InvokingContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine("DateTimeContextProvider - Injecting current date/time context");
+
+        return new ValueTask<IEnumerable<ChatMessage>>(
+            [
+                new ChatMessage(ChatRole.User, $"For reference, the current date and time is: {DateTimeOffset.Now}")
+            ]);
+    }
+}

dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/README.md

@@ -14,6 +14,7 @@ This sample demonstrates how to add middleware to intercept:
 5. Per‑request chat client middleware
 6. Per‑request function pipeline with approval
 7. Combining agent‑level and per‑request middleware
+8. MessageAIContextProvider middleware via `AIAgentBuilder.Use(...)` for injecting additional context messages
 
 ## Function Invocation Middleware
 

dotnet/samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Program.cs

@@ -38,18 +38,29 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session
 // Get the chat history to see how many messages are stored.
 // We can use the ChatHistoryProvider, that is also used by the agent, to read the
 // chat history from the session state, and see how the reducer is affecting the stored messages.
+// Here we expect to see 2 messages, the original user message and the agent response message.
 var provider = agent.GetService<InMemoryChatHistoryProvider>();
 List<ChatMessage>? chatHistory = provider?.GetMessages(session);
 Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
 
 // Invoke the agent a few more times.
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a robot.", session));
+
+// Now we expect to see 4 messages in the chat history, 2 input and 2 output.
+// While the target number of messages is 2, the default time for the InMemoryChatHistoryProvider
+// to trigger the reducer is just before messages are contributed to a new agent run.
+// So at this time, we have not yet triggered the reducer for the most recently added messages,
+// and they are still in the chat history.
+chatHistory = provider?.GetMessages(session);
 Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
+
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a lemur.", session));
+chatHistory = provider?.GetMessages(session);
 Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
 
 // At this point, the chat history has exceeded the limit and the original message will not exist anymore,
-// so asking a follow up question about it will not work as expected.
-Console.WriteLine(await agent.RunAsync("Tell me the joke about the pirate again, but add emojis and use the voice of a parrot.", session));
+// so asking a follow up question about it may not work as expected.
+Console.WriteLine(await agent.RunAsync("What was the first joke I asked you to tell again?", session));
 
+chatHistory = provider?.GetMessages(session);
 Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");

dotnet/samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Program.cs

@@ -92,9 +92,8 @@ namespace SampleApp
         private static void SetTodoItems(AgentSession? session, List<string> items)
             => session?.StateBag.SetValue(nameof(TodoListAIContextProvider), items);
 
-        protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
-            var inputContext = context.AIContext;
             var todoItems = GetTodoItems(context.Session);
 
             StringBuilder outputMessageBuilder = new();
@@ -114,18 +113,15 @@ namespace SampleApp
 
             return new ValueTask<AIContext>(new AIContext
             {
-                Instructions = inputContext.Instructions,
-                Tools = (inputContext.Tools ?? []).Concat(new AITool[]
-                {
+                Tools =
+                [
                     AIFunctionFactory.Create((string item) => AddTodoItem(context.Session, item), "AddTodoItem", "Adds an item to the todo list."),
                     AIFunctionFactory.Create((int index) => RemoveTodoItem(context.Session, index), "RemoveTodoItem", "Removes an item from the todo list. Index is zero based.")
-                }),
+                ],
                 Messages =
-                    (inputContext.Messages ?? [])
-                    .Concat(
-                    [
-                        new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
-                    ])
+                [
+                    new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())
+                ]
             });
         }
 
@@ -150,13 +146,12 @@ namespace SampleApp
     }
 
     /// <summary>
-    /// An <see cref="AIContextProvider"/> which searches for upcoming calendar events and adds them to the AI context.
+    /// A <see cref="MessageAIContextProvider"/> which searches for upcoming calendar events and adds them to the AI context.
     /// </summary>
-    internal sealed class CalendarSearchAIContextProvider(Func<Task<string[]>> loadNextThreeCalendarEvents) : AIContextProvider
+    internal sealed class CalendarSearchAIContextProvider(Func<Task<string[]>> loadNextThreeCalendarEvents) : MessageAIContextProvider
     {
-        protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask<IEnumerable<MEAI.ChatMessage>> ProvideMessagesAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
-            var inputContext = context.AIContext;
             var events = await loadNextThreeCalendarEvents();
 
             StringBuilder outputMessageBuilder = new();
@@ -166,18 +161,7 @@ namespace SampleApp
                 outputMessageBuilder.AppendLine($" - {calendarEvent}");
             }
 
-            return new()
-            {
-                Instructions = inputContext.Instructions,
-                Messages =
-                    (inputContext.Messages ?? [])
-                    .Concat(
-                    [
-                        new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
-                    ])
-                    .ToList(),
-                Tools = inputContext.Tools
-            };
+            return [new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())];
         }
     }
 }

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/Program.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Azure AI Foundry's Red Teaming service to assess
+// the safety and resilience of an AI model against adversarial attacks.
+//
+// It uses the RedTeam API from Azure.AI.Projects to run automated attack simulations
+// with various attack strategies (encoding, obfuscation, jailbreaks) across multiple
+// risk categories (Violence, HateUnfairness, Sexual, SelfHarm).
+//
+// For more details, see:
+// https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent
+
+using Azure.AI.Projects;
+using Azure.Identity;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+Console.WriteLine("=" + new string('=', 79));
+Console.WriteLine("RED TEAMING EVALUATION SAMPLE");
+Console.WriteLine("=" + new string('=', 79));
+Console.WriteLine();
+
+// Initialize Azure credentials and clients
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+DefaultAzureCredential credential = new();
+AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
+
+// Configure the target model for red teaming
+AzureOpenAIModelConfiguration targetConfig = new(deploymentName);
+
+// Create the red team run configuration
+RedTeam redTeamConfig = new(targetConfig)
+{
+    DisplayName = "FinancialAdvisor-RedTeam",
+    ApplicationScenario = "A financial advisor assistant that provides general financial advice and information.",
+    NumTurns = 3,
+    RiskCategories =
+    {
+        RiskCategory.Violence,
+        RiskCategory.HateUnfairness,
+        RiskCategory.Sexual,
+        RiskCategory.SelfHarm,
+    },
+    AttackStrategies =
+    {
+        AttackStrategy.Easy,
+        AttackStrategy.Moderate,
+        AttackStrategy.Jailbreak,
+    },
+};
+
+Console.WriteLine($"Target model: {deploymentName}");
+Console.WriteLine("Risk categories: Violence, HateUnfairness, Sexual, SelfHarm");
+Console.WriteLine("Attack strategies: Easy, Moderate, Jailbreak");
+Console.WriteLine($"Simulation turns: {redTeamConfig.NumTurns}");
+Console.WriteLine();
+
+// Submit the red team run to the service
+Console.WriteLine("Submitting red team run...");
+RedTeam redTeamRun = await aiProjectClient.RedTeams.CreateAsync(redTeamConfig);
+
+Console.WriteLine($"Red team run created: {redTeamRun.Name}");
+Console.WriteLine($"Status: {redTeamRun.Status}");
+Console.WriteLine();
+
+// Poll for completion
+Console.WriteLine("Waiting for red team run to complete (this may take several minutes)...");
+while (redTeamRun.Status != "Completed" && redTeamRun.Status != "Failed" && redTeamRun.Status != "Canceled")
+{
+    await Task.Delay(TimeSpan.FromSeconds(15));
+    redTeamRun = await aiProjectClient.RedTeams.GetAsync(redTeamRun.Name);
+    Console.WriteLine($"  Status: {redTeamRun.Status}");
+}
+
+Console.WriteLine();
+
+if (redTeamRun.Status == "Completed")
+{
+    Console.WriteLine("Red team run completed successfully!");
+    Console.WriteLine();
+    Console.WriteLine("Results:");
+    Console.WriteLine(new string('-', 80));
+    Console.WriteLine($"  Run name:    {redTeamRun.Name}");
+    Console.WriteLine($"  Display name: {redTeamRun.DisplayName}");
+    Console.WriteLine($"  Status:      {redTeamRun.Status}");
+
+    Console.WriteLine();
+    Console.WriteLine("Review the detailed results in the Azure AI Foundry portal:");
+    Console.WriteLine($"  {endpoint}");
+}
+else
+{
+    Console.WriteLine($"Red team run ended with status: {redTeamRun.Status}");
+}
+
+Console.WriteLine();
+Console.WriteLine(new string('=', 80));

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/README.md

@@ -0,0 +1,101 @@
+# Red Teaming with Azure AI Foundry (Classic)
+
+> [!IMPORTANT]
+> This sample uses the **classic Azure AI Foundry** red teaming API (`/redTeams/runs`) via `Azure.AI.Projects`. Results are viewable in the classic Foundry portal experience. The **new Foundry** portal's red teaming feature uses a different evaluation-based API that is not yet available in the .NET SDK.
+
+This sample demonstrates how to use Azure AI Foundry's Red Teaming service to assess the safety and resilience of an AI model against adversarial attacks.
+
+## What this sample demonstrates
+
+- Configuring a red team run targeting an Azure OpenAI model deployment
+- Using multiple `AttackStrategy` options (Easy, Moderate, Jailbreak)
+- Evaluating across `RiskCategory` categories (Violence, HateUnfairness, Sexual, SelfHarm)
+- Submitting a red team scan and polling for completion
+- Reviewing results in the Azure AI Foundry portal
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Azure AI Foundry project (hub and project created)
+- Azure OpenAI deployment (e.g., gpt-4o or gpt-4o-mini)
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+### Regional Requirements
+
+Red teaming is only available in regions that support risk and safety evaluators:
+- **East US 2**, **Sweden Central**, **US North Central**, **France Central**, **Switzerland West**
+
+### Environment Variables
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" # Replace with your Azure Foundry project endpoint
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+Navigate to the sample directory and run:
+
+```powershell
+cd dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming
+dotnet run
+```
+
+## Expected behavior
+
+The sample will:
+
+1. Configure a `RedTeam` run targeting the specified model deployment
+2. Define risk categories and attack strategies
+3. Submit the scan to Azure AI Foundry's Red Teaming service
+4. Poll for completion (this may take several minutes)
+5. Display the run status and direct you to the Azure AI Foundry portal for detailed results
+
+## Understanding Red Teaming
+
+### Attack Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| Easy | Simple encoding/obfuscation attacks (ROT13, Leetspeak, etc.) |
+| Moderate | Moderate complexity attacks requiring an LLM for orchestration |
+| Jailbreak | Crafted prompts designed to bypass AI safeguards (UPIA) |
+
+### Risk Categories
+
+| Category | Description |
+|----------|-------------|
+| Violence | Content related to violence |
+| HateUnfairness | Hate speech or unfair content |
+| Sexual | Sexual content |
+| SelfHarm | Self-harm related content |
+
+### Interpreting Results
+
+- Results are available in the Azure AI Foundry portal (**classic view** — toggle at top-right) under the red teaming section
+- Lower Attack Success Rate (ASR) is better — target ASR < 5% for production
+- Review individual attack conversations to understand vulnerabilities
+
+### Current Limitations
+
+> [!NOTE]
+> - The .NET Red Teaming API (`Azure.AI.Projects`) currently supports targeting **model deployments only** via `AzureOpenAIModelConfiguration`. The `AzureAIAgentTarget` type exists in the SDK but is consumed by the **Evaluation Taxonomy** API (`/evaluationtaxonomies`), not by the Red Teaming API (`/redTeams/runs`).
+> - Agent-targeted red teaming with agent-specific risk categories (Prohibited actions, Sensitive data leakage, Task adherence) is documented in the [concept docs](https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent) but is not yet available via the public REST API or .NET SDK.
+> - Results from this API appear in the **classic** Azure AI Foundry portal view. The new Foundry portal uses a separate evaluation-based system with `eval_*` identifiers.
+
+## Related Resources
+
+- [Azure AI Red Teaming Agent](https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent)
+- [RedTeam .NET API Reference](https://learn.microsoft.com/dotnet/api/azure.ai.projects.redteam?view=azure-dotnet-preview)
+- [Risk and Safety Evaluations](https://learn.microsoft.com/azure/ai-foundry/concepts/evaluation-metrics-built-in#risk-and-safety-evaluators)
+
+## Next Steps
+
+After running red teaming:
+1. Review attack results and strengthen agent guardrails
+2. Explore the Self-Reflection sample (FoundryAgents_Evaluations_Step02_SelfReflection) for quality assessment
+3. Set up continuous red teaming in your CI/CD pipeline

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.Evaluation" />
+    <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Quality" />
+    <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Safety" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/Program.cs

@@ -0,0 +1,292 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Microsoft.Extensions.AI.Evaluation.Quality to evaluate
+// an Agent Framework agent's response quality with a self-reflection loop.
+//
+// It uses GroundednessEvaluator, RelevanceEvaluator, and CoherenceEvaluator to score responses,
+// then iteratively asks the agent to improve based on evaluation feedback.
+//
+// Based on: Reflexion: Language Agents with Verbal Reinforcement Learning (NeurIPS 2023)
+// Reference: https://arxiv.org/abs/2303.11366
+//
+// For more details, see:
+// https://learn.microsoft.com/dotnet/ai/evaluation/libraries
+
+using Azure.AI.OpenAI;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Evaluation;
+using Microsoft.Extensions.AI.Evaluation.Quality;
+using Microsoft.Extensions.AI.Evaluation.Safety;
+
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
+using ChatRole = Microsoft.Extensions.AI.ChatRole;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string evaluatorDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? deploymentName;
+
+Console.WriteLine("=" + new string('=', 79));
+Console.WriteLine("SELF-REFLECTION EVALUATION SAMPLE");
+Console.WriteLine("=" + new string('=', 79));
+Console.WriteLine();
+
+// Initialize Azure credentials and client
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+DefaultAzureCredential credential = new();
+AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
+
+// Set up the LLM-based chat client for quality evaluators
+IChatClient chatClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential)
+    .GetChatClient(evaluatorDeploymentName)
+    .AsIChatClient();
+
+// Configure evaluation: quality evaluators use the LLM, safety evaluators use Azure AI Foundry
+ContentSafetyServiceConfiguration safetyConfig = new(
+    credential: credential,
+    endpoint: new Uri(endpoint));
+
+ChatConfiguration chatConfiguration = safetyConfig.ToChatConfiguration(
+    originalChatConfiguration: new ChatConfiguration(chatClient));
+
+// Create a test agent
+AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
+    name: "KnowledgeAgent",
+    model: deploymentName,
+    instructions: "You are a helpful assistant. Answer questions accurately based on the provided context.");
+Console.WriteLine($"Created agent: {agent.Name}");
+Console.WriteLine();
+
+// Example question and grounding context
+const string Question = """
+    What are the main benefits of using Azure AI Foundry for building AI applications?
+    """;
+
+const string Context = """
+    Azure AI Foundry is a comprehensive platform for building, deploying, and managing AI applications.
+    Key benefits include:
+    1. Unified development environment with support for multiple AI frameworks and models
+    2. Built-in safety and security features including content filtering and red teaming tools
+    3. Scalable infrastructure that handles deployment and monitoring automatically
+    4. Integration with Azure services like Azure OpenAI, Cognitive Services, and Machine Learning
+    5. Evaluation tools for assessing model quality, safety, and performance
+    6. Support for RAG (Retrieval-Augmented Generation) patterns with vector search
+    7. Enterprise-grade compliance and governance features
+    """;
+
+Console.WriteLine("Question:");
+Console.WriteLine(Question);
+Console.WriteLine();
+
+// Run evaluations
+try
+{
+    await RunSelfReflectionWithGroundedness(agent, Question, Context, chatConfiguration);
+    await RunQualityEvaluation(agent, Question, Context, chatConfiguration);
+    await RunCombinedQualityAndSafetyEvaluation(agent, Question, chatConfiguration);
+}
+finally
+{
+    // Cleanup
+    await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
+    Console.WriteLine();
+    Console.WriteLine("Cleanup: Agent deleted.");
+}
+
+// ============================================================================
+// Implementation Functions
+// ============================================================================
+
+static async Task RunSelfReflectionWithGroundedness(
+    AIAgent agent, string question, string context, ChatConfiguration chatConfiguration)
+{
+    Console.WriteLine("Running Self-Reflection with Groundedness Evaluation...");
+    Console.WriteLine();
+
+    GroundednessEvaluator groundednessEvaluator = new();
+    GroundednessEvaluatorContext groundingContext = new(context);
+
+    const int MaxReflections = 3;
+    double bestScore = 0;
+
+    string currentPrompt = $"Context: {context}\n\nQuestion: {question}";
+
+    for (int i = 0; i < MaxReflections; i++)
+    {
+        Console.WriteLine($"Iteration {i + 1}/{MaxReflections}:");
+        Console.WriteLine(new string('-', 40));
+
+        // Create a new session for each reflection iteration so that
+        // conversation context does not carry over between runs. This keeps
+        // each evaluation independent and avoids biasing groundedness scores.
+        AgentSession session = await agent.CreateSessionAsync();
+        AgentResponse agentResponse = await agent.RunAsync(currentPrompt, session);
+        string responseText = agentResponse.Text;
+
+        Console.WriteLine($"Response: {responseText[..Math.Min(150, responseText.Length)]}...");
+
+        List<ChatMessage> messages =
+        [
+            new(ChatRole.User, currentPrompt),
+        ];
+        ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, responseText));
+
+        EvaluationResult result = await groundednessEvaluator.EvaluateAsync(
+            messages,
+            chatResponse,
+            chatConfiguration,
+            additionalContext: [groundingContext]);
+
+        NumericMetric groundedness = result.Get<NumericMetric>(GroundednessEvaluator.GroundednessMetricName);
+        double score = groundedness.Value ?? 0;
+        string rating = groundedness.Interpretation?.Rating.ToString() ?? "N/A";
+
+        Console.WriteLine($"Groundedness score: {score:F1}/5 (Rating: {rating})");
+        Console.WriteLine();
+
+        if (score > bestScore)
+        {
+            bestScore = score;
+        }
+
+        if (score >= 4.0 || i == MaxReflections - 1)
+        {
+            if (score >= 4.0)
+            {
+                Console.WriteLine("Good groundedness achieved!");
+            }
+
+            break;
+        }
+
+        // Ask for improvement in the next iteration, including the previous response
+        // so the LLM knows what to improve on (each iteration uses a new session).
+        currentPrompt = $"""
+            Context: {context}
+
+            Your previous answer scored {score}/5 on groundedness.
+            Your previous answer was:
+            {responseText}
+
+            Please improve your answer to be more grounded in the provided context.
+            Only include information that is directly supported by the context.
+
+            Question: {question}
+            """;
+        Console.WriteLine("Requesting improvement...");
+        Console.WriteLine();
+    }
+
+    Console.WriteLine($"Best groundedness score: {bestScore:F1}/5");
+    Console.WriteLine(new string('=', 80));
+    Console.WriteLine();
+}
+
+static async Task RunQualityEvaluation(
+    AIAgent agent, string question, string context, ChatConfiguration chatConfiguration)
+{
+    Console.WriteLine("Running Quality Evaluation (Relevance, Coherence, Groundedness)...");
+    Console.WriteLine();
+
+    IEvaluator[] evaluators =
+    [
+        new RelevanceEvaluator(),
+        new CoherenceEvaluator(),
+        new GroundednessEvaluator(),
+    ];
+
+    CompositeEvaluator compositeEvaluator = new(evaluators);
+    GroundednessEvaluatorContext groundingContext = new(context);
+
+    string prompt = $"Context: {context}\n\nQuestion: {question}";
+
+    AgentSession session = await agent.CreateSessionAsync();
+    AgentResponse agentResponse = await agent.RunAsync(prompt, session);
+    string responseText = agentResponse.Text;
+
+    Console.WriteLine($"Response: {responseText[..Math.Min(150, responseText.Length)]}...");
+    Console.WriteLine();
+
+    List<ChatMessage> messages =
+    [
+        new(ChatRole.User, prompt),
+    ];
+    ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, responseText));
+
+    EvaluationResult result = await compositeEvaluator.EvaluateAsync(
+        messages,
+        chatResponse,
+        chatConfiguration,
+        additionalContext: [groundingContext]);
+
+    foreach (EvaluationMetric metric in result.Metrics.Values)
+    {
+        if (metric is NumericMetric n)
+        {
+            string rating = n.Interpretation?.Rating.ToString() ?? "N/A";
+            Console.WriteLine($"  {n.Name,-20} Score: {n.Value:F1}/5  Rating: {rating}");
+        }
+    }
+
+    Console.WriteLine(new string('=', 80));
+    Console.WriteLine();
+}
+
+static async Task RunCombinedQualityAndSafetyEvaluation(
+    AIAgent agent, string question, ChatConfiguration chatConfiguration)
+{
+    Console.WriteLine("Running Combined Quality + Safety Evaluation...");
+    Console.WriteLine();
+
+    IEvaluator[] evaluators =
+    [
+        new RelevanceEvaluator(),
+        new CoherenceEvaluator(),
+        new ContentHarmEvaluator(),
+        new ProtectedMaterialEvaluator(),
+    ];
+
+    CompositeEvaluator compositeEvaluator = new(evaluators);
+
+    AgentSession session = await agent.CreateSessionAsync();
+    AgentResponse agentResponse = await agent.RunAsync(question, session);
+    string responseText = agentResponse.Text;
+
+    Console.WriteLine($"Response: {responseText[..Math.Min(150, responseText.Length)]}...");
+    Console.WriteLine();
+
+    List<ChatMessage> messages =
+    [
+        new(ChatRole.User, question), // No context in this evaluation — testing quality and safety on raw question
+    ];
+    ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, responseText));
+
+    EvaluationResult result = await compositeEvaluator.EvaluateAsync(
+        messages,
+        chatResponse,
+        chatConfiguration);
+
+    Console.WriteLine("Quality Metrics:");
+    foreach (EvaluationMetric metric in result.Metrics.Values)
+    {
+        if (metric is NumericMetric n)
+        {
+            string rating = n.Interpretation?.Rating.ToString() ?? "N/A";
+            bool failed = n.Interpretation?.Failed ?? false;
+            Console.WriteLine($"  {n.Name,-25} Score: {n.Value:F1,-6} Rating: {rating,-15} Failed: {failed}");
+        }
+        else if (metric is BooleanMetric b)
+        {
+            string rating = b.Interpretation?.Rating.ToString() ?? "N/A";
+            bool failed = b.Interpretation?.Failed ?? false;
+            Console.WriteLine($"  {b.Name,-25} Value: {b.Value,-6} Rating: {rating,-15} Failed: {failed}");
+        }
+    }
+
+    Console.WriteLine(new string('=', 80));
+}

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/README.md

@@ -0,0 +1,118 @@
+# Self-Reflection Evaluation with Groundedness Assessment
+
+This sample demonstrates the self-reflection pattern using Agent Framework with `Microsoft.Extensions.AI.Evaluation.Quality` evaluators. The agent iteratively improves its responses based on real groundedness evaluation scores.
+
+For details on the self-reflection approach, see [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) (NeurIPS 2023).
+
+## What this sample demonstrates
+
+- Self-reflection loop that improves responses using real `GroundednessEvaluator` scores
+- Using `RelevanceEvaluator` and `CoherenceEvaluator` for multi-metric quality assessment
+- Combining quality and safety evaluators with `CompositeEvaluator`
+- Configuring `ContentSafetyServiceConfiguration` for safety evaluators alongside LLM-based quality evaluators
+- Tracking improvement across iterations
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Azure AI Foundry project (hub and project created)
+- Azure OpenAI deployment (e.g., gpt-4o or gpt-4o-mini)
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+### Azure Resources Required
+
+1. **Azure AI Hub and Project**: Create these in the Azure Portal
+   - Follow: https://learn.microsoft.com/azure/ai-foundry/how-to/create-projects
+2. **Azure OpenAI Deployment**: Deploy a model (e.g., gpt-4o or gpt-4o-mini)
+   - Agent model: Used to generate responses
+   - Evaluator model: Quality evaluators use an LLM; best results with GPT-4o
+3. **Azure CLI**: Install and authenticate with `az login`
+
+### Environment Variables
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-project.api.azureml.ms"  # Azure Foundry project endpoint
+$env:AZURE_OPENAI_ENDPOINT="https://your-openai.openai.azure.com/"         # Azure OpenAI endpoint (for quality evaluators)
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"                   # Model deployment name
+```
+
+**Note**: For best evaluation results, use GPT-4o or GPT-4o-mini as the evaluator model. The groundedness evaluator has been tested and tuned for these models.
+
+## Run the sample
+
+Navigate to the sample directory and run:
+
+```powershell
+cd dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection
+dotnet run
+```
+
+## Expected behavior
+
+The sample runs three evaluation scenarios:
+
+### 1. Self-Reflection with Groundedness
+- Asks a question with grounding context
+- Evaluates response groundedness using `GroundednessEvaluator`
+- If score is below 4/5, asks the agent to improve with feedback
+- Repeats up to 3 iterations
+- Tracks and reports the best score achieved
+
+### 2. Quality Evaluation
+- Evaluates a single response with multiple quality evaluators:
+  - `RelevanceEvaluator` — is the response relevant to the question?
+  - `CoherenceEvaluator` — is the response logically coherent?
+  - `GroundednessEvaluator` — is the response grounded in the provided context?
+
+### 3. Combined Quality + Safety Evaluation
+- Runs both quality and safety evaluators together:
+  - `RelevanceEvaluator`, `CoherenceEvaluator` (quality)
+  - `ContentHarmEvaluator` (safety — violence, hate, sexual, self-harm)
+  - `ProtectedMaterialEvaluator` (safety — copyrighted content detection)
+
+## Understanding the Evaluation
+
+### Groundedness Score (1-5 scale)
+
+The `GroundednessEvaluator` measures how well the agent's response is grounded in the provided context:
+
+- **5** = Excellent - Response is fully grounded in context
+- **4** = Good - Mostly grounded with minor deviations
+- **3** = Fair - Partially grounded but includes unsupported claims
+- **2** = Poor - Significant amount of ungrounded content
+- **1** = Very Poor - Response is largely unsupported by context
+
+### Self-Reflection Process
+
+1. **Initial Response**: Agent generates answer based on question + context
+2. **Evaluation**: `GroundednessEvaluator` scores the response (1-5)
+3. **Feedback**: If score < 4, agent receives the score and is asked to improve
+4. **Iteration**: Process repeats until good score or max iterations
+
+## Best Practices
+
+1. **Provide Complete Context**: Ensure grounding context contains all information needed to answer the question
+2. **Clear Instructions**: Give the agent clear instructions about staying grounded in context
+3. **Use Quality Models**: GPT-4o recommended for evaluation tasks
+4. **Multiple Evaluators**: Use combination of evaluators (groundedness + relevance + coherence)
+5. **Batch Processing**: For production, process multiple questions in batch
+
+## Related Resources
+
+- [Reflexion Paper (NeurIPS 2023)](https://arxiv.org/abs/2303.11366)
+- [Microsoft.Extensions.AI.Evaluation Libraries](https://learn.microsoft.com/dotnet/ai/evaluation/libraries)
+- [GroundednessEvaluator API Reference](https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.evaluation.quality.groundednessevaluator)
+- [Azure AI Foundry Evaluation Service](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/evaluate-sdk)
+
+## Next Steps
+
+After running self-reflection evaluation:
+1. Implement similar patterns for other quality metrics (relevance, coherence, fluency)
+2. Integrate into CI/CD pipeline for continuous quality assurance
+3. Explore the Safety Evaluation sample (FoundryAgents_Evaluations_Step01_RedTeaming) for content safety assessment

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/Program.cs

@@ -64,7 +64,8 @@ IAsyncEnumerable<AgentResponseUpdate> updates = agentWithPersonInfo.RunStreaming
 
 // Assemble all the parts of the streamed output, since we can only deserialize once we have the full json,
 // then deserialize the response into the PersonInfo class.
-PersonInfo personInfo = (await updates.ToAgentResponseAsync()).Deserialize<PersonInfo>(JsonSerializerOptions.Web);
+PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>((await updates.ToAgentResponseAsync()).Text, JsonSerializerOptions.Web)
+    ?? throw new InvalidOperationException("Failed to deserialize the streamed response into PersonInfo.");
 
 Console.WriteLine("Assistant Output:");
 Console.WriteLine($"Name: {personInfo.Name}");

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/Program.cs

@@ -86,8 +86,6 @@ internal sealed class Program
             AllowBackgroundResponses = true,
         };
 
-        AgentSession session = await agent.CreateSessionAsync();
-
         ChatMessage message = new(ChatRole.User, [
             new TextContent("I need you to help me search for 'OpenAI news'. Please type 'OpenAI news' and submit the search. Once you see search results, the task is complete."),
             new DataContent(new BinaryData(screenshots["browser_search"]), "image/png")
@@ -96,6 +94,11 @@ internal sealed class Program
         // Initial request with screenshot - start with Bing search page
         Console.WriteLine("Starting computer automation session (initial screenshot: cua_browser_search.png)...");
 
+        // IMPORTANT: Computer-use with the Azure Agents API differs from the vanilla OpenAI Responses API.
+        // The Azure Agents API rejects requests that include previous_response_id alongside
+        // computer_call_output items. To work around this, each call uses a fresh session (avoiding
+        // previous_response_id) and re-sends the full conversation context as input items instead.
+        AgentSession session = await agent.CreateSessionAsync();
         AgentResponse response = await agent.RunAsync(message, session: session, options: runOptions);
 
         // Main interaction loop
@@ -103,7 +106,6 @@ internal sealed class Program
         int iteration = 0;
         // Initialize state machine
         SearchState currentState = SearchState.Initial;
-        string initialCallId = string.Empty;
 
         while (true)
         {
@@ -119,6 +121,9 @@ internal sealed class Program
                 response = await agent.RunAsync(session, runOptions);
             }
 
+            // Clear the continuation token so the next RunAsync call is a fresh request.
+            runOptions.ContinuationToken = null;
+
             Console.WriteLine($"Agent response received (ID: {response.ResponseId})");
 
             if (iteration >= MaxIterations)
@@ -148,12 +153,6 @@ internal sealed class Program
             ComputerCallAction action = firstComputerCall.Action;
             string currentCallId = firstComputerCall.CallId;
 
-            // Set the initial computer call ID for tracking and subsequent responses.
-            if (string.IsNullOrEmpty(initialCallId))
-            {
-                initialCallId = currentCallId;
-            }
-
             Console.WriteLine($"Processing computer call (ID: {currentCallId})");
 
             // Simulate executing the action and taking a screenshot
@@ -162,16 +161,31 @@ internal sealed class Program
 
             Console.WriteLine("Sending action result back to agent...");
 
-            AIContent content = new()
+            // Build the follow-up messages with full conversation context.
+            // The Azure Agents API rejects previous_response_id when computer_call_output items are
+            // present, so we must re-send all prior output items (reasoning, computer_call, etc.)
+            // as input items alongside the computer_call_output to maintain conversation continuity.
+            List<ChatMessage> followUpMessages = [];
+
+            // Re-send all response output items as an assistant message so the API has full context
+            List<AIContent> priorOutputContents = response.Messages
+                .SelectMany(m => m.Contents)
+                .ToList();
+            followUpMessages.Add(new ChatMessage(ChatRole.Assistant, priorOutputContents));
+
+            // Add the computer_call_output as a user message
+            AIContent callOutput = new()
             {
                 RawRepresentation = new ComputerCallOutputResponseItem(
-                    initialCallId,
+                    currentCallId,
                     output: ComputerCallOutput.CreateScreenshotOutput(new BinaryData(screenInfo.ImageBytes), "image/png"))
             };
+            followUpMessages.Add(new ChatMessage(ChatRole.User, [callOutput]));
 
-            // Follow-up message with action result and new screenshot
-            message = new(ChatRole.User, [content]);
-            response = await agent.RunAsync(message, session: session, options: runOptions);
+            // Create a fresh session so ConversationId does not carry over a previous_response_id.
+            // Without this, the Azure Agents API returns an error when computer_call_output is present.
+            session = await agent.CreateSessionAsync();
+            response = await agent.RunAsync(followUpMessages, session: session, options: runOptions);
         }
     }
 }

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/README.md

@@ -2,6 +2,17 @@
 
 This sample demonstrates how to use the computer use tool with AI agents. The computer use tool allows agents to interact with a computer environment by viewing the screen, controlling the mouse and keyboard, and performing various actions to help complete tasks.
 
+> [!NOTE]
+> **Azure Agents API vs. vanilla OpenAI Responses API behavior:**
+> The Azure Agents API rejects requests that include `previous_response_id` alongside
+> `computer_call_output` items — unlike the vanilla OpenAI Responses API, which accepts them.
+> This sample works around the limitation by creating a **fresh session for each follow-up call**
+> (so no `previous_response_id` is carried over) and re-sending all prior response output items
+> (reasoning, computer_call, etc.) as input items to preserve full conversation context.
+> Additionally, the sample uses the **current** `CallId` from each computer call response
+> (not the initial one) and clears the `ContinuationToken` after polling completes to prevent
+> stale tokens from affecting subsequent requests.
+
 ## What this sample demonstrates
 
 - Creating agents with computer use capabilities

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step18_FileSearch/FoundryAgents_Step18_FileSearch.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.AI.Projects" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+  </ItemGroup>
+  
+</Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step18_FileSearch/Program.cs

@@ -0,0 +1,111 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use File Search Tool with AI Agents.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Assistants;
+using OpenAI.Files;
+using OpenAI.Responses;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+const string AgentInstructions = "You are a helpful assistant that can search through uploaded files to answer questions.";
+
+// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+var projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
+var filesClient = projectOpenAIClient.GetProjectFilesClient();
+var vectorStoresClient = projectOpenAIClient.GetProjectVectorStoresClient();
+
+// 1. Create a temp file with test content and upload it.
+string searchFilePath = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName() + "_lookup.txt");
+File.WriteAllText(
+    path: searchFilePath,
+    contents: """
+        Employee Directory:
+        - Alice Johnson, 28 years old, Software Engineer, Engineering Department
+        - Bob Smith, 35 years old, Sales Manager, Sales Department
+        - Carol Williams, 42 years old, HR Director, Human Resources Department
+        - David Brown, 31 years old, Customer Support Lead, Support Department
+        """
+);
+
+Console.WriteLine($"Uploading file: {searchFilePath}");
+OpenAIFile uploadedFile = filesClient.UploadFile(
+    filePath: searchFilePath,
+    purpose: FileUploadPurpose.Assistants
+);
+Console.WriteLine($"Uploaded file, file ID: {uploadedFile.Id}");
+
+// 2. Create a vector store with the uploaded file.
+var vectorStoreResult = await vectorStoresClient.CreateVectorStoreAsync(
+    options: new() { FileIds = { uploadedFile.Id }, Name = "EmployeeDirectory_VectorStore" }
+);
+string vectorStoreId = vectorStoreResult.Value.Id;
+Console.WriteLine($"Created vector store, vector store ID: {vectorStoreId}");
+
+AIAgent agent = await CreateAgentWithMEAI();
+// AIAgent agent = await CreateAgentWithNativeSDK();
+
+// Run the agent
+Console.WriteLine("\n--- Running File Search Agent ---");
+AgentResponse response = await agent.RunAsync("Who is the youngest employee?");
+Console.WriteLine($"Response: {response}");
+
+// Getting any file citation annotations generated by the tool
+foreach (AIAnnotation annotation in response.Messages.SelectMany(m => m.Contents).SelectMany(c => c.Annotations ?? []))
+{
+    if (annotation.RawRepresentation is TextAnnotationUpdate citationAnnotation)
+    {
+        Console.WriteLine($$"""
+            File Citation:
+              File Id: {{citationAnnotation.OutputFileId}}
+              Text to Replace: {{citationAnnotation.TextToReplace}}
+            """);
+    }
+}
+
+// Cleanup.
+Console.WriteLine("\n--- Cleanup ---");
+await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
+await vectorStoresClient.DeleteVectorStoreAsync(vectorStoreId);
+await filesClient.DeleteFileAsync(uploadedFile.Id);
+File.Delete(searchFilePath);
+Console.WriteLine("Cleanup completed successfully.");
+
+// --- Agent Creation Options ---
+
+#pragma warning disable CS8321 // Local function is declared but never used
+// Option 1 - Using HostedFileSearchTool (MEAI + AgentFramework)
+async Task<AIAgent> CreateAgentWithMEAI()
+{
+    return await aiProjectClient.CreateAIAgentAsync(
+        model: deploymentName,
+        name: "FileSearchAgent-MEAI",
+        instructions: AgentInstructions,
+        tools: [new HostedFileSearchTool() { Inputs = [new HostedVectorStoreContent(vectorStoreId)] }]);
+}
+
+// Option 2 - Using PromptAgentDefinition with ResponseTool.CreateFileSearchTool (Native SDK)
+async Task<AIAgent> CreateAgentWithNativeSDK()
+{
+    return await aiProjectClient.CreateAIAgentAsync(
+        name: "FileSearchAgent-NATIVE",
+        creationOptions: new AgentVersionCreationOptions(
+            new PromptAgentDefinition(model: deploymentName)
+            {
+                Instructions = AgentInstructions,
+                Tools = {
+                    ResponseTool.CreateFileSearchTool(vectorStoreIds: [vectorStoreId])
+                }
+            })
+    );
+}

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step18_FileSearch/README.md

@@ -0,0 +1,52 @@
+# Using File Search with AI Agents
+
+This sample demonstrates how to use the file search tool with AI agents. The file search tool allows agents to search through uploaded files stored in vector stores to answer user questions.
+
+## What this sample demonstrates
+
+- Uploading files and creating vector stores
+- Creating agents with file search capabilities
+- Using HostedFileSearchTool (MEAI abstraction)
+- Using native SDK file search tools (ResponseTool.CreateFileSearchTool)
+- Handling file citation annotations
+- Managing agent and resource lifecycle (creation and deletion)
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Azure Foundry service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+**Note**: This demo uses `DefaultAzureCredential` for authentication. For local development, make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure Identity documentation](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential).
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+Navigate to the FoundryAgents sample directory and run:
+
+```powershell
+cd dotnet/samples/GettingStarted/FoundryAgents
+dotnet run --project .\FoundryAgents_Step18_FileSearch
+```
+
+## Expected behavior
+
+The sample will:
+
+1. Create a temporary text file with employee directory information
+2. Upload the file to Azure Foundry
+3. Create a vector store with the uploaded file
+4. Create an agent with file search capabilities using one of:
+   - Option 1: Using HostedFileSearchTool (MEAI abstraction)
+   - Option 2: Using native SDK file search tools
+5. Run a query against the agent to search through the uploaded file
+6. Display file citation annotations from responses
+7. Clean up resources (agent, vector store, and uploaded file)

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step19_OpenAPITools/FoundryAgents_Step19_OpenAPITools.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);CA1812;CS8321</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.AI.Projects" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+  </ItemGroup>
+  
+</Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step19_OpenAPITools/Program.cs

@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use OpenAPI Tools with AI Agents.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+// Warning: DefaultAzureCredential is intended for simplicity in development. For production scenarios, consider using a more specific credential.
+string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+const string AgentInstructions = "You are a helpful assistant that can use the countries API to retrieve information about countries by their currency code.";
+
+// A simple OpenAPI specification for the REST Countries API
+const string CountriesOpenApiSpec = """
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "REST Countries API",
+    "description": "Retrieve information about countries by currency code",
+    "version": "v3.1"
+  },
+  "servers": [
+    {
+      "url": "https://restcountries.com/v3.1"
+    }
+  ],
+  "paths": {
+    "/currency/{currency}": {
+      "get": {
+        "description": "Get countries that use a specific currency code (e.g., USD, EUR, GBP)",
+        "operationId": "GetCountriesByCurrency",
+        "parameters": [
+          {
+            "name": "currency",
+            "in": "path",
+            "description": "Currency code (e.g., USD, EUR, GBP)",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with list of countries",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object"
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No countries found for the currency"
+          }
+        }
+      }
+    }
+  }
+}
+""";
+
+// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Create the OpenAPI function definition
+var openApiFunction = new OpenAPIFunctionDefinition(
+    "get_countries",
+    BinaryData.FromString(CountriesOpenApiSpec),
+    new OpenAPIAnonymousAuthenticationDetails())
+{
+    Description = "Retrieve information about countries by currency code"
+};
+
+AIAgent agent = await CreateAgentWithMEAI();
+// AIAgent agent = await CreateAgentWithNativeSDK();
+
+// Run the agent with a question about countries
+Console.WriteLine(await agent.RunAsync("What countries use the Euro (EUR) as their currency? Please list them."));
+
+// Cleanup by deleting the agent
+await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
+
+// --- Agent Creation Options ---
+
+// Option 1 - Using AsAITool wrapping for OpenApiTool (MEAI + AgentFramework)
+async Task<AIAgent> CreateAgentWithMEAI()
+{
+    return await aiProjectClient.CreateAIAgentAsync(
+        model: deploymentName,
+        name: "OpenAPIToolsAgent-MEAI",
+        instructions: AgentInstructions,
+        tools: [((ResponseTool)AgentTool.CreateOpenApiTool(openApiFunction)).AsAITool()]);
+}
+
+// Option 2 - Using PromptAgentDefinition with AgentTool.CreateOpenApiTool (Native SDK)
+async Task<AIAgent> CreateAgentWithNativeSDK()
+{
+    return await aiProjectClient.CreateAIAgentAsync(
+        name: "OpenAPIToolsAgent-NATIVE",
+        creationOptions: new AgentVersionCreationOptions(
+            new PromptAgentDefinition(model: deploymentName)
+            {
+                Instructions = AgentInstructions,
+                Tools = { (ResponseTool)AgentTool.CreateOpenApiTool(openApiFunction) }
+            })
+    );
+}

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step19_OpenAPITools/README.md

@@ -0,0 +1,47 @@
+# Using OpenAPI Tools with AI Agents
+
+This sample demonstrates how to use OpenAPI tools with AI agents. OpenAPI tools allow agents to call external REST APIs defined by OpenAPI specifications.
+
+## What this sample demonstrates
+
+- Creating agents with OpenAPI tool capabilities
+- Using AgentTool.CreateOpenApiTool with an embedded OpenAPI specification
+- Anonymous authentication for public APIs
+- Running an agent that can call external REST APIs
+- Managing agent lifecycle (creation and deletion)
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Azure Foundry service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+**Note**: This demo uses `DefaultAzureCredential` for authentication, which supports multiple authentication methods including Azure CLI, managed identity, and more. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure Identity documentation](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential).
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+Navigate to the FoundryAgents sample directory and run:
+
+```powershell
+cd dotnet/samples/GettingStarted/FoundryAgents
+dotnet run --project .\FoundryAgents_Step19_OpenAPITools
+```
+
+## Expected behavior
+
+The sample will:
+
+1. Create an agent with an OpenAPI tool configured to call the REST Countries API
+2. Ask the agent: "What countries use the Euro (EUR) as their currency?"
+3. The agent will use the OpenAPI tool to call the REST Countries API
+4. Display the response containing the list of countries that use EUR
+5. Clean up resources by deleting the agent

dotnet/samples/GettingStarted/FoundryAgents/README.md

@@ -58,8 +58,20 @@ Before you begin, ensure you have the following prerequisites:
 |[Using plugins](./FoundryAgents_Step13_Plugins/)|This sample demonstrates how to use plugins with a Foundry agent|
 |[Code interpreter](./FoundryAgents_Step14_CodeInterpreter/)|This sample demonstrates how to use the code interpreter tool with a Foundry agent|
 |[Computer use](./FoundryAgents_Step15_ComputerUse/)|This sample demonstrates how to use computer use capabilities with a Foundry agent|
+|[File search](./FoundryAgents_Step18_FileSearch/)|This sample demonstrates how to use the file search tool with a Foundry agent|
 |[Local MCP](./FoundryAgents_Step27_LocalMCP/)|This sample demonstrates how to use a local MCP client with a Foundry agent|
 
+## Evaluation Samples
+
+Evaluation is critical for building trustworthy and high-quality AI applications. The evaluation samples demonstrate how to assess agent safety, quality, and performance using Azure AI Foundry's evaluation capabilities.
+
+|Sample|Description|
+|---|---|
+|[Red Team Evaluation](./FoundryAgents_Evaluations_Step01_RedTeaming/)|This sample demonstrates how to use Azure AI Foundry's Red Teaming service to assess model safety against adversarial attacks|
+|[Self-Reflection with Groundedness](./FoundryAgents_Evaluations_Step02_SelfReflection/)|This sample demonstrates the self-reflection pattern where agents iteratively improve responses based on groundedness evaluation|
+
+For details on safety evaluation, see the [Red Team Evaluation README](./FoundryAgents_Evaluations_Step01_RedTeaming/README.md).
+
 ## Running the samples from the console
 
 To run the samples, navigate to the desired sample directory, e.g.

dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server/README.md

@@ -24,7 +24,7 @@ $env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-
 
 ## Setup and Running
 
-Run the ModelContextProtocolPluginAuth sample
+Run the Agent_MCP_Server sample
 
 ```bash
 dotnet run

dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/Program.cs

@@ -34,7 +34,10 @@ var transport = new HttpClientTransport(new()
     Name = "Secure Weather Client",
     OAuth = new()
     {
-        ClientId = "ProtectedMcpClient",
+        DynamicClientRegistration = new()
+        {
+            ClientName = "ProtectedMcpClient",
+        },
         RedirectUri = new Uri("http://localhost:1179/callback"),
         AuthorizationRedirectDelegate = HandleAuthorizationUrlAsync,
     }

dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/README.md

@@ -54,7 +54,7 @@ dotnet run
 
 The protected server will start at `http://localhost:7071`
 
-### Step 3: Run the ModelContextProtocolPluginAuth sample
+### Step 3: Run the Agent_MCP_Server_Auth sample
 
 Finally, run this client:
 

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj

@@ -16,6 +16,9 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows.Generators\Microsoft.Agents.AI.Workflows.Generators.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/Program.cs

@@ -109,7 +109,7 @@ internal sealed class SloganGeneratedEvent(SloganResult sloganResult) : Workflow
 /// 1. HandleAsync(string message): Handles the initial task to create a slogan.
 /// 2. HandleAsync(Feedback message): Handles feedback to improve the slogan.
 /// </summary>
-internal sealed class SloganWriterExecutor : Executor
+internal sealed partial class SloganWriterExecutor : Executor
 {
     private readonly AIAgent _agent;
     private AgentSession? _session;
@@ -133,10 +133,7 @@ internal sealed class SloganWriterExecutor : Executor
         this._agent = new ChatClientAgent(chatClient, agentOptions);
     }
 
-    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
-        routeBuilder.AddHandler<string, SloganResult>(this.HandleAsync)
-                    .AddHandler<FeedbackResult, SloganResult>(this.HandleAsync);
-
+    [MessageHandler]
     public async ValueTask<SloganResult> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
         this._session ??= await this._agent.CreateSessionAsync(cancellationToken);
@@ -149,6 +146,7 @@ internal sealed class SloganWriterExecutor : Executor
         return sloganResult;
     }
 
+    [MessageHandler]
     public async ValueTask<SloganResult> HandleAsync(FeedbackResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
         var feedbackMessage = $"""

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/Program.cs

@@ -32,10 +32,10 @@ public static class Program
         var checkpoints = new List<CheckpointInfo>();
 
         // Execute the workflow and save checkpoints
-        await using Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
+        await using StreamingRun checkpointedRun = await InProcessExecution
             .StreamAsync(workflow, NumberSignal.Init, checkpointManager);
 
-        await foreach (WorkflowEvent evt in checkpointedRun.Run.WatchStreamAsync())
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
             if (evt is ExecutorCompletedEvent executorCompletedEvt)
             {
@@ -72,10 +72,10 @@ public static class Program
         Console.WriteLine($"\n\nHydrating a new workflow instance from the {CheckpointIndex + 1}th checkpoint.");
         CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
 
-        await using Checkpointed<StreamingRun> newCheckpointedRun =
+        await using StreamingRun newCheckpointedRun =
             await InProcessExecution.ResumeStreamAsync(newWorkflow, savedCheckpoint, checkpointManager);
 
-        await foreach (WorkflowEvent evt in newCheckpointedRun.Run.WatchStreamAsync())
+        await foreach (WorkflowEvent evt in newCheckpointedRun.WatchStreamAsync())
         {
             if (evt is ExecutorCompletedEvent executorCompletedEvt)
             {

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/Program.cs

@@ -31,10 +31,10 @@ public static class Program
         var checkpoints = new List<CheckpointInfo>();
 
         // Execute the workflow and save checkpoints
-        await using Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
+        await using StreamingRun checkpointedRun = await InProcessExecution
             .StreamAsync(workflow, NumberSignal.Init, checkpointManager)
             ;
-        await foreach (WorkflowEvent evt in checkpointedRun.Run.WatchStreamAsync())
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
             if (evt is ExecutorCompletedEvent executorCompletedEvt)
             {
@@ -71,7 +71,7 @@ public static class Program
         CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
         // Note that we are restoring the state directly to the same run instance.
         await checkpointedRun.RestoreCheckpointAsync(savedCheckpoint, CancellationToken.None);
-        await foreach (WorkflowEvent evt in checkpointedRun.Run.WatchStreamAsync())
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
             if (evt is ExecutorCompletedEvent executorCompletedEvt)
             {

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs

@@ -34,17 +34,17 @@ public static class Program
         var checkpoints = new List<CheckpointInfo>();
 
         // Execute the workflow and save checkpoints
-        await using Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
+        await using StreamingRun checkpointedRun = await InProcessExecution
             .StreamAsync(workflow, new SignalWithNumber(NumberSignal.Init), checkpointManager)
             ;
-        await foreach (WorkflowEvent evt in checkpointedRun.Run.WatchStreamAsync())
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
             switch (evt)
             {
                 case RequestInfoEvent requestInputEvt:
                     // Handle `RequestInfoEvent` from the workflow
                     ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
-                    await checkpointedRun.Run.SendResponseAsync(response);
+                    await checkpointedRun.SendResponseAsync(response);
                     break;
                 case ExecutorCompletedEvent executorCompletedEvt:
                     Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
@@ -77,14 +77,14 @@ public static class Program
         CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
         // Note that we are restoring the state directly to the same run instance.
         await checkpointedRun.RestoreCheckpointAsync(savedCheckpoint, CancellationToken.None);
-        await foreach (WorkflowEvent evt in checkpointedRun.Run.WatchStreamAsync())
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
             switch (evt)
             {
                 case RequestInfoEvent requestInputEvt:
                     // Handle `RequestInfoEvent` from the workflow
                     ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
-                    await checkpointedRun.Run.SendResponseAsync(response);
+                    await checkpointedRun.SendResponseAsync(response);
                     break;
                 case ExecutorCompletedEvent executorCompletedEvt:
                     Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/Resources.cs

@@ -9,5 +9,5 @@ internal static class Resources
 {
     private const string ResourceFolder = "Resources";
 
-    public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
 }

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/Resources.cs

@@ -9,5 +9,5 @@ internal static class Resources
 {
     private const string ResourceFolder = "Resources";
 
-    public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
 }

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/Resources.cs

@@ -9,5 +9,5 @@ internal static class Resources
 {
     private const string ResourceFolder = "Resources";
 
-    public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
 }

dotnet/samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.AzureAI\Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeFunctionTool.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.yaml

@@ -0,0 +1,55 @@
+#
+# This workflow demonstrates using InvokeFunctionTool to call functions directly
+# from the workflow without going through an AI agent first.
+#
+# InvokeFunctionTool allows workflows to:
+# - Pre-fetch data before calling an AI agent
+# - Execute operations directly without AI involvement
+# - Store function results in workflow variables for later use
+#
+# Example input: 
+# What are the specials in the menu?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_function_tool_demo
+  actions:
+
+    # Invoke GetSpecials function to get today's specials directly from the workflow
+    - kind: InvokeFunctionTool
+      id: invoke_get_specials
+      conversationId: =System.ConversationId
+      requireApproval: true
+      functionName: GetSpecials
+      output:
+        autoSend: true
+        result: Local.Specials
+        messages: Local.FunctionMessage
+
+    # Display a message showing we retrieved the specials
+    - kind: SendMessage
+      id: show_specials_intro
+      message: "Today's specials have been retrieved. Here they are: {Local.Specials}"
+
+    # Now use an agent to format and present the specials to the user
+    - kind: InvokeAzureAgent
+      id: invoke_menu_agent
+      conversationId: =System.ConversationId
+      agent:
+        name: FunctionMenuAgent
+      input:
+        messages: =UserMessage("Please describe today's specials in an appealing way.")
+      output:
+        messages: Local.AgentResponse
+
+    # Allow the user to ask follow-up questions in a loop
+    - kind: InvokeAzureAgent
+      id: invoke_followup
+      conversationId: =System.ConversationId
+      agent:
+        name: FunctionMenuAgent
+      input:
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"

dotnet/samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/MenuPlugin.cs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+
+namespace Demo.Workflows.Declarative.InvokeFunctionTool;
+
+#pragma warning disable CA1822 // Mark members as static
+
+/// <summary>
+/// Plugin providing menu-related functions that can be invoked directly by the workflow
+/// using the InvokeFunctionTool action.
+/// </summary>
+public sealed class MenuPlugin
+{
+    [Description("Provides a list items on the menu.")]
+    public MenuItem[] GetMenu()
+    {
+        return s_menuItems;
+    }
+
+    [Description("Provides a list of specials from the menu.")]
+    public MenuItem[] GetSpecials()
+    {
+        return [.. s_menuItems.Where(i => i.IsSpecial)];
+    }
+
+    [Description("Provides the price of the requested menu item.")]
+    public float? GetItemPrice(
+        [Description("The name of the menu item.")]
+        string name)
+    {
+        return s_menuItems.FirstOrDefault(i => i.Name.Equals(name, StringComparison.OrdinalIgnoreCase))?.Price;
+    }
+
+    private static readonly MenuItem[] s_menuItems =
+        [
+            new()
+            {
+                Category = "Soup",
+                Name = "Clam Chowder",
+                Price = 4.95f,
+                IsSpecial = true,
+            },
+            new()
+            {
+                Category = "Soup",
+                Name = "Tomato Soup",
+                Price = 4.95f,
+                IsSpecial = false,
+            },
+            new()
+            {
+                Category = "Salad",
+                Name = "Cobb Salad",
+                Price = 9.99f,
+            },
+            new()
+            {
+                Category = "Salad",
+                Name = "House Salad",
+                Price = 4.95f,
+            },
+            new()
+            {
+                Category = "Drink",
+                Name = "Chai Tea",
+                Price = 2.95f,
+                IsSpecial = true,
+            },
+            new()
+            {
+                Category = "Drink",
+                Name = "Soda",
+                Price = 1.95f,
+            },
+        ];
+
+    public sealed class MenuItem
+    {
+        public string Category { get; init; } = string.Empty;
+        public string Name { get; init; } = string.Empty;
+        public float Price { get; init; }
+        public bool IsSpecial { get; init; }
+    }
+}

dotnet/samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/Program.cs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.OpenAI;
+using Azure.Identity;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InvokeFunctionTool;
+
+/// <summary>
+/// Demonstrate a workflow that uses InvokeFunctionTool to call functions directly
+/// from the workflow without going through an AI agent first.
+/// </summary>
+/// <remarks>
+/// The InvokeFunctionTool action allows workflows to invoke function tools directly,
+/// enabling pre-fetching of data or executing operations before calling an AI agent.
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Create the menu plugin with functions that can be invoked directly by the workflow
+        MenuPlugin menuPlugin = new();
+        AIFunction[] functions =
+            [
+                AIFunctionFactory.Create(menuPlugin.GetMenu),
+                AIFunctionFactory.Create(menuPlugin.GetSpecials),
+                AIFunctionFactory.Create(menuPlugin.GetItemPrice),
+            ];
+
+        // Ensure sample agent exists in Foundry
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.
+        WorkflowFactory workflowFactory = new("InvokeFunctionTool.yaml", foundryEndpoint);
+
+        // Execute the workflow
+        WorkflowRunner runner = new(functions) { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "FunctionMenuAgent",
+            agentDefinition: DefineMenuAgent(configuration, []), // Create Agent with no function tool in the definition.
+            agentDescription: "Provides information about the restaurant menu");
+    }
+
+    private static PromptAgentDefinition DefineMenuAgent(IConfiguration configuration, AIFunction[] functions)
+    {
+        PromptAgentDefinition agentDefinition =
+            new(configuration.GetValue(Application.Settings.FoundryModelMini))
+            {
+                Instructions =
+                    """
+                    Answer the users questions about the menu.
+                    Use the information provided in the conversation history to answer questions.
+                    If the information is already available in the conversation, use it directly.
+                    For questions or input that do not require searching the documentation, inform the
+                    user that you can only answer questions about what's on the menu.
+                    """
+            };
+
+        foreach (AIFunction function in functions)
+        {
+            agentDefinition.Tools.Add(function.AsOpenAIResponseTool());
+        }
+
+        return agentDefinition;
+    }
+}

dotnet/samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj

@@ -23,6 +23,9 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows.Generators\Microsoft.Agents.AI.Workflows.Generators.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowHelper.cs

@@ -6,7 +6,7 @@ using Microsoft.Extensions.AI;
 
 namespace WorkflowAsAnAgentObservabilitySample;
 
-internal static class WorkflowHelper
+internal static partial class WorkflowHelper
 {
     /// <summary>
     /// Creates a workflow that uses two language agents to process input concurrently.
@@ -50,21 +50,16 @@ internal static class WorkflowHelper
     /// <summary>
     /// Executor that starts the concurrent processing by sending messages to the agents.
     /// </summary>
-    private sealed class ConcurrentStartExecutor() : Executor("ConcurrentStartExecutor")
+    private sealed partial class ConcurrentStartExecutor() : Executor("ConcurrentStartExecutor")
     {
-        protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
-        {
-            return routeBuilder
-                .AddHandler<List<ChatMessage>>(this.RouteMessages)
-                .AddHandler<TurnToken>(this.RouteTurnTokenAsync);
-        }
-
-        private ValueTask RouteMessages(List<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
+        [MessageHandler]
+        internal ValueTask RouteMessages(List<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
         {
             return context.SendMessageAsync(messages, cancellationToken: cancellationToken);
         }
 
-        private ValueTask RouteTurnTokenAsync(TurnToken token, IWorkflowContext context, CancellationToken cancellationToken)
+        [MessageHandler]
+        internal ValueTask RouteTurnTokenAsync(TurnToken token, IWorkflowContext context, CancellationToken cancellationToken)
         {
             return context.SendMessageAsync(token, cancellationToken: cancellationToken);
         }
@@ -73,7 +68,8 @@ internal static class WorkflowHelper
     /// <summary>
     /// Executor that aggregates the results from the concurrent agents.
     /// </summary>
-    private sealed class ConcurrentAggregationExecutor() : Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
+    [YieldsOutput(typeof(List<ChatMessage>))]
+    private sealed partial class ConcurrentAggregationExecutor() : Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
     {
         private readonly List<ChatMessage> _messages = [];
 

dotnet/samples/GettingStarted/Workflows/SharedStates/Resources.cs

@@ -9,5 +9,5 @@ internal static class Resources
 {
     private const string ResourceFolder = "Resources";
 
-    public static string Read(string fileName) => File.ReadAllText($"{ResourceFolder}/{fileName}");
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
 }

dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
@@ -11,6 +11,10 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows.Generators\Microsoft.Agents.AI.Workflows.Generators.csproj" 
+                      OutputItemType="Analyzer" 
+                      ReferenceOutputAssembly="false" />
+    
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs

@@ -196,7 +196,7 @@ internal sealed class CriticDecision
 /// Executor that creates or revises content based on user requests or critic feedback.
 /// This executor demonstrates multiple message handlers for different input types.
 /// </summary>
-internal sealed class WriterExecutor : Executor
+internal sealed partial class WriterExecutor : Executor
 {
     private readonly AIAgent _agent;
 
@@ -213,15 +213,11 @@ internal sealed class WriterExecutor : Executor
         );
     }
 
-    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
-        routeBuilder
-            .AddHandler<string, ChatMessage>(this.HandleInitialRequestAsync)
-            .AddHandler<CriticDecision, ChatMessage>(this.HandleRevisionRequestAsync);
-
     /// <summary>
     /// Handles the initial writing request from the user.
     /// </summary>
-    private async ValueTask<ChatMessage> HandleInitialRequestAsync(
+    [MessageHandler]
+    public async ValueTask<ChatMessage> HandleInitialRequestAsync(
         string message,
         IWorkflowContext context,
         CancellationToken cancellationToken = default)
@@ -232,7 +228,8 @@ internal sealed class WriterExecutor : Executor
     /// <summary>
     /// Handles revision requests from the critic with feedback.
     /// </summary>
-    private async ValueTask<ChatMessage> HandleRevisionRequestAsync(
+    [MessageHandler]
+    public async ValueTask<ChatMessage> HandleRevisionRequestAsync(
         CriticDecision decision,
         IWorkflowContext context,
         CancellationToken cancellationToken = default)
@@ -330,7 +327,8 @@ internal sealed class CriticExecutor : Executor<ChatMessage, CriticDecision>
 
         // Convert the stream to a response and deserialize the structured output
         AgentResponse response = await updates.ToAgentResponseAsync(cancellationToken);
-        CriticDecision decision = response.Deserialize<CriticDecision>(JsonSerializerOptions.Web);
+        CriticDecision decision = JsonSerializer.Deserialize<CriticDecision>(response.Text, JsonSerializerOptions.Web)
+            ?? throw new JsonException("Failed to deserialize CriticDecision from response text.");
 
         Console.WriteLine($"Decision: {(decision.Approved ? "✅ APPROVED" : "❌ NEEDS REVISION")}");
         if (!string.IsNullOrEmpty(decision.Feedback))

dotnet/samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj

@@ -15,7 +15,6 @@
         and cannot access parent folders where Directory.Packages.props resides.
     -->
     <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
-    <NoWarn>$(NoWarn);MEAI001;OPENAI001</NoWarn>
   </PropertyGroup>
 
   <!-- 
@@ -36,11 +35,10 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.5" />
-    <PackageReference Include="Azure.AI.OpenAI" Version="2.7.0-beta.2" />
+    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.6" />
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
     <PackageReference Include="Azure.Identity" Version="1.17.1" />
-    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.251219.1" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.1.1-preview.1.25612.2" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.3.0" />
   </ItemGroup>
 
   <!-- Add analyzers with compatible versions -->

dotnet/samples/HostedAgents/AgentWithHostedMCP/Program.cs

@@ -9,7 +9,6 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI.Responses;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
@@ -29,6 +28,7 @@ AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
     new DefaultAzureCredential())
     .GetResponsesClient(deploymentName)
+    .AsIChatClient()
     .CreateAIAgent(
         instructions: "You answer questions by searching the Microsoft Learn content only.",
         name: "MicrosoftLearnAgent",

dotnet/samples/HostedAgents/AgentWithHostedMCP/run-requests.http

@@ -7,6 +7,7 @@ GET {{host}}/readiness
 ### Simple string input - Ask about MCP Tools
 POST {{endpoint}}
 Content-Type: application/json
+
 {
     "input": "Please summarize the Azure AI Agent documentation related to MCP Tool calling?"
 }
@@ -14,6 +15,7 @@ Content-Type: application/json
 ### Explicit input - Ask about Agent Framework
 POST {{endpoint}}
 Content-Type: application/json
+
 {
     "input": [
         {

dotnet/samples/M365Agent/Agents/WeatherForecastAgent.cs

@@ -54,7 +54,7 @@ public class WeatherForecastAgent : DelegatingAIAgent
 
         // If the agent returned a valid structured output response
         // we might be able to enhance the response with an adaptive card.
-        if (response.TryDeserialize<WeatherForecastAgentResponse>(JsonSerializerOptions.Web, out var structuredOutput))
+        if (TryDeserialize<WeatherForecastAgentResponse>(response.Text, JsonSerializerOptions.Web, out var structuredOutput))
         {
             var textContentMessage = response.Messages.FirstOrDefault(x => x.Contents.OfType<TextContent>().Any());
             if (textContentMessage is not null)
@@ -112,4 +112,25 @@ public class WeatherForecastAgent : DelegatingAIAgent
         });
         return card;
     }
+
+    private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
+    {
+        try
+        {
+            T? result = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
+            if (result is null)
+            {
+                structuredOutput = default!;
+                return false;
+            }
+
+            structuredOutput = result;
+            return true;
+        }
+        catch
+        {
+            structuredOutput = default!;
+            return false;
+        }
+    }
 }

dotnet/src/LegacySupport/ExperimentalAttribute/ExperimentalAttribute.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft. All rights reserved.
+// Copyright (c) Microsoft. All rights reserved.
 
 #if !NET8_0_OR_GREATER
 
@@ -28,7 +28,7 @@ internal sealed class ExperimentalAttribute : Attribute
     /// <param name="diagnosticId">Human readable explanation for marking experimental API.</param>
     public ExperimentalAttribute(string diagnosticId)
     {
-        DiagnosticId = diagnosticId;
+        this.DiagnosticId = diagnosticId;
     }
 
     /// <summary>

dotnet/src/Microsoft.Agents.AI.A2A/A2AAgent.cs

@@ -63,7 +63,16 @@ public sealed class A2AAgent : AIAgent
     /// <param name="contextId">The context id to continue.</param>
     /// <returns>A value task representing the asynchronous operation. The task result contains a new <see cref="AgentSession"/> instance.</returns>
     public ValueTask<AgentSession> CreateSessionAsync(string contextId)
-        => new(new A2AAgentSession() { ContextId = contextId });
+        => new(new A2AAgentSession() { ContextId = Throw.IfNullOrWhitespace(contextId) });
+
+    /// <summary>
+    /// Get a new <see cref="AgentSession"/> instance using an existing context id and task id, to resume that conversation from a specific task.
+    /// </summary>
+    /// <param name="contextId">The context id to continue.</param>
+    /// <param name="taskId">The task id to resume from.</param>
+    /// <returns>A value task representing the asynchronous operation. The task result contains a new <see cref="AgentSession"/> instance.</returns>
+    public ValueTask<AgentSession> CreateSessionAsync(string contextId, string taskId)
+        => new(new A2AAgentSession() { ContextId = Throw.IfNullOrWhitespace(contextId), TaskId = Throw.IfNullOrWhitespace(taskId) });
 
     /// <inheritdoc/>
     protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
@@ -72,7 +81,7 @@ public sealed class A2AAgent : AIAgent
 
         if (session is not A2AAgentSession typedSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be serialized.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(A2AAgentSession)}' can be serialized by this agent.");
         }
 
         return new(typedSession.Serialize(jsonSerializerOptions));
@@ -247,7 +256,7 @@ public sealed class A2AAgent : AIAgent
 
         if (session is not A2AAgentSession typedSession)
         {
-            throw new InvalidOperationException($"The provided session type {session.GetType()} is not compatible with the agent. Only A2A agent created sessions are supported.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(A2AAgentSession)}' can be used by this agent.");
         }
 
         return typedSession;

dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs

@@ -22,7 +22,7 @@ namespace Microsoft.Agents.AI;
 /// may involve multiple agents working together.
 /// </remarks>
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
-public abstract class AIAgent
+public abstract partial class AIAgent
 {
     private static readonly AsyncLocal<AgentRunContext?> s_currentContext = new();
 

dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgentStructuredOutput.cs

@@ -11,155 +11,130 @@ using Microsoft.Shared.Diagnostics;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Provides an <see cref="AIAgent"/> that delegates to an <see cref="IChatClient"/> implementation.
+/// Provides structured output methods for <see cref="AIAgent"/> that enable requesting responses in a specific type format.
 /// </summary>
-public sealed partial class ChatClientAgent
+public abstract partial class AIAgent
 {
     /// <summary>
     /// Run the agent with no message assuming that all required instructions are already provided to the agent or on the session, and requesting a response of the specified type <typeparamref name="T"/>.
     /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
     /// <param name="session">
     /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
     /// The session will be updated with any response messages generated during invocation.
     /// </param>
-    /// <param name="serializerOptions">The JSON serialization options to use.</param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
     /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
-    /// <param name="useJsonSchemaResponseFormat">
-    /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
-    /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
-    /// </param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse"/> with the agent's output.</returns>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
     /// <remarks>
     /// This overload is useful when the agent has sufficient context from previous messages in the session
     /// or from its initial configuration to generate a meaningful response without additional input.
     /// </remarks>
-    public Task<ChatClientAgentResponse<T>> RunAsync<T>(
+    public Task<AgentResponse<T>> RunAsync<T>(
         AgentSession? session = null,
         JsonSerializerOptions? serializerOptions = null,
         AgentRunOptions? options = null,
-        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default) =>
-        this.RunAsync<T>([], session, serializerOptions, options, useJsonSchemaResponseFormat, cancellationToken);
+        this.RunAsync<T>([], session, serializerOptions, options, cancellationToken);
 
     /// <summary>
     /// Runs the agent with a text message from the user, requesting a response of the specified type <typeparamref name="T"/>.
     /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
     /// <param name="message">The user message to send to the agent.</param>
     /// <param name="session">
     /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
     /// The session will be updated with the input message and any response messages generated during invocation.
     /// </param>
-    /// <param name="serializerOptions">The JSON serialization options to use.</param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
     /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
-    /// <param name="useJsonSchemaResponseFormat">
-    /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
-    /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
-    /// </param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse"/> with the agent's output.</returns>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
     /// <exception cref="ArgumentException"><paramref name="message"/> is <see langword="null"/>, empty, or contains only whitespace.</exception>
     /// <remarks>
     /// The provided text will be wrapped in a <see cref="ChatMessage"/> with the <see cref="ChatRole.User"/> role
     /// before being sent to the agent. This is a convenience method for simple text-based interactions.
     /// </remarks>
-    public Task<ChatClientAgentResponse<T>> RunAsync<T>(
+    public Task<AgentResponse<T>> RunAsync<T>(
         string message,
         AgentSession? session = null,
         JsonSerializerOptions? serializerOptions = null,
         AgentRunOptions? options = null,
-        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default)
     {
         _ = Throw.IfNullOrWhitespace(message);
 
-        return this.RunAsync<T>(new ChatMessage(ChatRole.User, message), session, serializerOptions, options, useJsonSchemaResponseFormat, cancellationToken);
+        return this.RunAsync<T>(new ChatMessage(ChatRole.User, message), session, serializerOptions, options, cancellationToken);
     }
 
     /// <summary>
     /// Runs the agent with a single chat message, requesting a response of the specified type <typeparamref name="T"/>.
     /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
     /// <param name="message">The chat message to send to the agent.</param>
     /// <param name="session">
     /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
     /// The session will be updated with the input message and any response messages generated during invocation.
     /// </param>
-    /// <param name="serializerOptions">The JSON serialization options to use.</param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
     /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
-    /// <param name="useJsonSchemaResponseFormat">
-    /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
-    /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
-    /// </param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse"/> with the agent's output.</returns>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
-    public Task<ChatClientAgentResponse<T>> RunAsync<T>(
+    public Task<AgentResponse<T>> RunAsync<T>(
         ChatMessage message,
         AgentSession? session = null,
         JsonSerializerOptions? serializerOptions = null,
         AgentRunOptions? options = null,
-        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default)
     {
         _ = Throw.IfNull(message);
 
-        return this.RunAsync<T>([message], session, serializerOptions, options, useJsonSchemaResponseFormat, cancellationToken);
+        return this.RunAsync<T>([message], session, serializerOptions, options, cancellationToken);
     }
 
     /// <summary>
     /// Runs the agent with a collection of chat messages, requesting a response of the specified type <typeparamref name="T"/>.
     /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
     /// <param name="messages">The collection of messages to send to the agent for processing.</param>
     /// <param name="session">
     /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
     /// The session will be updated with the input messages and any response messages generated during invocation.
     /// </param>
-    /// <param name="serializerOptions">The JSON serialization options to use.</param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
     /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
-    /// <param name="useJsonSchemaResponseFormat">
-    /// <see langword="true" /> to set a JSON schema on the <see cref="ChatResponseFormat"/>; otherwise, <see langword="false" />. The default is <see langword="true" />.
-    /// Using a JSON schema improves reliability if the underlying model supports native structured output with a schema, but might cause an error if the model does not support it.
-    /// </param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse"/> with the agent's output.</returns>
-    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
     /// <remarks>
     /// <para>
-    /// This is the primary invocation method that implementations must override. It handles collections of messages,
-    /// allowing for complex conversational scenarios including multi-turn interactions, function calls, and
-    /// context-rich conversations.
+    /// This method handles collections of messages, allowing for complex conversational scenarios including
+    /// multi-turn interactions, function calls, and context-rich conversations.
     /// </para>
     /// <para>
     /// The messages are processed in the order provided and become part of the conversation history.
     /// The agent's response will also be added to <paramref name="session"/> if one is provided.
     /// </para>
     /// </remarks>
-    public Task<ChatClientAgentResponse<T>> RunAsync<T>(
+    public async Task<AgentResponse<T>> RunAsync<T>(
         IEnumerable<ChatMessage> messages,
         AgentSession? session = null,
         JsonSerializerOptions? serializerOptions = null,
         AgentRunOptions? options = null,
-        bool? useJsonSchemaResponseFormat = null,
         CancellationToken cancellationToken = default)
     {
-        async Task<ChatResponse<T>> GetResponseAsync(IChatClient chatClient, List<ChatMessage> threadMessages, ChatOptions? chatOptions, CancellationToken ct)
-        {
-            return await chatClient.GetResponseAsync<T>(
-                threadMessages,
-                serializerOptions ?? AgentJsonUtilities.DefaultOptions,
-                chatOptions,
-                useJsonSchemaResponseFormat,
-                ct).ConfigureAwait(false);
-        }
+        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;
 
-        static ChatClientAgentResponse<T> CreateResponse(ChatResponse<T> chatResponse)
-        {
-            return new ChatClientAgentResponse<T>(chatResponse)
-            {
-                ContinuationToken = WrapContinuationToken(chatResponse.ContinuationToken)
-            };
-        }
+        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
 
-        return this.RunCoreAsync(GetResponseAsync, CreateResponse, messages, session, options, cancellationToken);
+        (responseFormat, bool isWrappedInObject) = StructuredOutputSchemaUtilities.WrapNonObjectSchema(responseFormat);
+
+        options = options?.Clone() ?? new AgentRunOptions();
+        options.ResponseFormat = responseFormat;
+
+        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+
+        return new AgentResponse<T>(response, serializerOptions) { IsWrappedInObject = isWrappedInObject };
     }
 }

dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs

@@ -2,6 +2,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
@@ -10,7 +11,7 @@ using Microsoft.Shared.Diagnostics;
 namespace Microsoft.Agents.AI;
 
 /// <summary>
-/// Provides an abstract base class for components that enhance AI context management during agent invocations.
+/// Provides an abstract base class for components that enhance AI context during agent invocations.
 /// </summary>
 /// <remarks>
 /// <para>
@@ -30,6 +31,32 @@ namespace Microsoft.Agents.AI;
 /// </remarks>
 public abstract class AIContextProvider
 {
+    private static IEnumerable<ChatMessage> DefaultExternalOnlyFilter(IEnumerable<ChatMessage> messages)
+        => messages.Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External);
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AIContextProvider"/> class.
+    /// </summary>
+    /// <param name="provideInputMessageFilter">An optional filter function to apply to input messages before providing context via <see cref="ProvideAIContextAsync"/>. If not set, defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to request messages before storing context via <see cref="StoreAIContextAsync"/>. If not set, defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages.</param>
+    protected AIContextProvider(
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideInputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+    {
+        this.ProvideInputMessageFilter = provideInputMessageFilter ?? DefaultExternalOnlyFilter;
+        this.StoreInputMessageFilter = storeInputMessageFilter ?? DefaultExternalOnlyFilter;
+    }
+
+    /// <summary>
+    /// Gets the filter function to apply to input messages before providing context via <see cref="ProvideAIContextAsync"/>.
+    /// </summary>
+    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> ProvideInputMessageFilter { get; }
+
+    /// <summary>
+    /// Gets the filter function to apply to request messages before storing context via <see cref="StoreAIContextAsync"/>.
+    /// </summary>
+    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> StoreInputMessageFilter { get; }
+
     /// <summary>
     /// Gets the key used to store the provider state in the <see cref="AgentSession.StateBag"/>.
     /// </summary>
@@ -58,7 +85,7 @@ public abstract class AIContextProvider
     /// </para>
     /// </remarks>
     public ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        => this.InvokingCoreAsync(context, cancellationToken);
+        => this.InvokingCoreAsync(Throw.IfNull(context), cancellationToken);
 
     /// <summary>
     /// Called at the start of agent invocation to provide additional context.
@@ -76,8 +103,96 @@ public abstract class AIContextProvider
     /// <item><description>Injecting contextual messages from conversation history</description></item>
     /// </list>
     /// </para>
+    /// <para>
+    /// The default implementation of this method filters the input messages using the configured provide-input message filter
+    /// (which defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages),
+    /// then calls <see cref="ProvideAIContextAsync"/> to get additional context,
+    /// stamps any messages from the returned context with <see cref="AgentRequestMessageSourceType.AIContextProvider"/> source attribution,
+    /// and merges the returned context with the original (unfiltered) input context (concatenating instructions, messages, and tools).
+    /// For most scenarios, overriding <see cref="ProvideAIContextAsync"/> is sufficient to provide additional context,
+    /// while still benefiting from the default filtering, merging and source stamping behavior.
+    /// However, for scenarios that require more control over context filtering, merging or source stamping, overriding this method
+    /// allows you to directly control the full <see cref="AIContext"/> returned for the invocation.
+    /// </para>
     /// </remarks>
-    protected abstract ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default);
+    protected virtual async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        var inputContext = context.AIContext;
+
+        // Create a filtered context for ProvideAIContextAsync, filtering input messages
+        // to exclude non-external messages (e.g. chat history, other AI context provider messages).
+        var filteredContext = new InvokingContext(
+            context.Agent,
+            context.Session,
+            new AIContext
+            {
+                Instructions = inputContext.Instructions,
+                Messages = inputContext.Messages is not null ? this.ProvideInputMessageFilter(inputContext.Messages) : null,
+                Tools = inputContext.Tools
+            });
+
+        var provided = await this.ProvideAIContextAsync(filteredContext, cancellationToken).ConfigureAwait(false);
+
+        var mergedInstructions = (inputContext.Instructions, provided.Instructions) switch
+        {
+            (null, null) => null,
+            (string a, null) => a,
+            (null, string b) => b,
+            (string a, string b) => a + "\n" + b
+        };
+
+        var providedMessages = provided.Messages is not null
+            ? provided.Messages.Select(m => m.WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!))
+            : null;
+
+        var mergedMessages = (inputContext.Messages, providedMessages) switch
+        {
+            (null, null) => null,
+            (var a, null) => a,
+            (null, var b) => b,
+            (var a, var b) => a.Concat(b)
+        };
+
+        var mergedTools = (inputContext.Tools, provided.Tools) switch
+        {
+            (null, null) => null,
+            (var a, null) => a,
+            (null, var b) => b,
+            (var a, var b) => a.Concat(b)
+        };
+
+        return new AIContext
+        {
+            Instructions = mergedInstructions,
+            Messages = mergedMessages,
+            Tools = mergedTools
+        };
+    }
+
+    /// <summary>
+    /// When overridden in a derived class, provides additional AI context to be merged with the input context for the current invocation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method is called from <see cref="InvokingCoreAsync"/>.
+    /// Note that <see cref="InvokingCoreAsync"/> can be overridden to directly control context merging and source stamping, in which case
+    /// it is up to the implementer to call this method as needed to retrieve the additional context.
+    /// </para>
+    /// <para>
+    /// In contrast with <see cref="InvokingCoreAsync"/>, this method only returns additional context to be merged with the input,
+    /// while <see cref="InvokingCoreAsync"/> is responsible for returning the full merged <see cref="AIContext"/> for the invocation.
+    /// </para>
+    /// </remarks>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains an <see cref="AIContext"/>
+    /// with additional context to be merged with the input context.
+    /// </returns>
+    protected virtual ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        return new ValueTask<AIContext>(new AIContext());
+    }
 
     /// <summary>
     /// Called at the end of the agent invocation to process the invocation results.
@@ -106,7 +221,7 @@ public abstract class AIContextProvider
     /// </para>
     /// </remarks>
     public ValueTask InvokedAsync(InvokedContext context, CancellationToken cancellationToken = default)
-        => this.InvokedCoreAsync(context, cancellationToken);
+        => this.InvokedCoreAsync(Throw.IfNull(context), cancellationToken);
 
     /// <summary>
     /// Called at the end of the agent invocation to process the invocation results.
@@ -128,9 +243,50 @@ public abstract class AIContextProvider
     /// This method is called regardless of whether the invocation succeeded or failed.
     /// To check if the invocation was successful, inspect the <see cref="InvokedContext.InvokeException"/> property.
     /// </para>
+    /// <para>
+    /// The default implementation of this method skips execution for any invocation failures,
+    /// filters the request messages using the configured store-input message filter
+    /// (which defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages),
+    /// and calls <see cref="StoreAIContextAsync"/> to process the invocation results.
+    /// For most scenarios, overriding <see cref="StoreAIContextAsync"/> is sufficient to process invocation results,
+    /// while still benefiting from the default error handling and filtering behavior.
+    /// However, for scenarios that require more control over error handling or message filtering, overriding this method
+    /// allows you to directly control the processing of invocation results.
+    /// </para>
     /// </remarks>
     protected virtual ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
-        => default;
+    {
+        if (context.InvokeException is not null)
+        {
+            return default;
+        }
+
+        var subContext = new InvokedContext(context.Agent, context.Session, this.StoreInputMessageFilter(context.RequestMessages), context.ResponseMessages!);
+        return this.StoreAIContextAsync(subContext, cancellationToken);
+    }
+
+    /// <summary>
+    /// When overridden in a derived class, processes invocation results at the end of the agent invocation.
+    /// </summary>
+    /// <param name="context">Contains the invocation context including request messages, response messages, and any exception that occurred.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method is called from <see cref="InvokedCoreAsync"/>.
+    /// Note that <see cref="InvokedCoreAsync"/> can be overridden to directly control error handling, in which case
+    /// it is up to the implementer to call this method as needed to process the invocation results.
+    /// </para>
+    /// <para>
+    /// In contrast with <see cref="InvokedCoreAsync"/>, this method only processes the invocation results,
+    /// while <see cref="InvokedCoreAsync"/> is also responsible for error handling.
+    /// </para>
+    /// <para>
+    /// The default implementation of <see cref="InvokedCoreAsync"/> only calls this method if the invocation succeeded.
+    /// </para>
+    /// </remarks>
+    protected virtual ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default) =>
+        default;
 
     /// <summary>Asks the <see cref="AIContextProvider"/> for an object of the specified type <paramref name="serviceType"/>.</summary>
     /// <param name="serviceType">The type of object being requested.</param>

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs

@@ -1,20 +1,12 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
-#if NET
-using System.Buffers;
-#endif
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
-
-#if NET
-using System.Text;
-#endif
-using System.Text.Json;
 using System.Text.Json.Serialization;
-using System.Text.Json.Serialization.Metadata;
-using Microsoft.Shared.Diagnostics;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI;
 
@@ -76,6 +68,29 @@ public class AgentResponse
         this.ContinuationToken = response.ContinuationToken;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentResponse"/> class from an existing <see cref="AgentResponse"/>.
+    /// </summary>
+    /// <param name="response">The <see cref="AgentResponse"/> from which to copy properties.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="response"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// This constructor creates a copy of an existing agent response, preserving all
+    /// metadata and storing the original response in <see cref="RawRepresentation"/> for access to
+    /// the underlying implementation details.
+    /// </remarks>
+    protected AgentResponse(AgentResponse response)
+    {
+        _ = Throw.IfNull(response);
+
+        this.AdditionalProperties = response.AdditionalProperties;
+        this.CreatedAt = response.CreatedAt;
+        this.Messages = response.Messages;
+        this.RawRepresentation = response;
+        this.ResponseId = response.ResponseId;
+        this.Usage = response.Usage;
+        this.ContinuationToken = response.ContinuationToken;
+    }
+
     /// <summary>
     /// Initializes a new instance of the <see cref="AgentResponse"/> class with the specified collection of messages.
     /// </summary>
@@ -159,6 +174,7 @@ public class AgentResponse
     /// to poll for completion.
     /// </para>
     /// </remarks>
+    [Experimental(DiagnosticIds.Experiments.AIResponseContinuations)]
     public ResponseContinuationToken? ContinuationToken { get; set; }
 
     /// <summary>
@@ -274,117 +290,4 @@ public class AgentResponse
 
         return updates;
     }
-
-    /// <summary>
-    /// Deserializes the response text into the given type.
-    /// </summary>
-    /// <typeparam name="T">The output type to deserialize into.</typeparam>
-    /// <returns>The result as the requested type.</returns>
-    /// <exception cref="InvalidOperationException">The result is not parsable into the requested type.</exception>
-    public T Deserialize<T>() =>
-        this.Deserialize<T>(AgentAbstractionsJsonUtilities.DefaultOptions);
-
-    /// <summary>
-    /// Deserializes the response text into the given type using the specified serializer options.
-    /// </summary>
-    /// <typeparam name="T">The output type to deserialize into.</typeparam>
-    /// <param name="serializerOptions">The JSON serialization options to use.</param>
-    /// <returns>The result as the requested type.</returns>
-    /// <exception cref="InvalidOperationException">The result is not parsable into the requested type.</exception>
-    public T Deserialize<T>(JsonSerializerOptions serializerOptions)
-    {
-        _ = Throw.IfNull(serializerOptions);
-
-        var structuredOutput = this.GetResultCore<T>(serializerOptions, out var failureReason);
-        return failureReason switch
-        {
-            FailureReason.ResultDidNotContainJson => throw new InvalidOperationException("The response did not contain JSON to be deserialized."),
-            FailureReason.DeserializationProducedNull => throw new InvalidOperationException("The deserialized response is null."),
-            _ => structuredOutput!,
-        };
-    }
-
-    /// <summary>
-    /// Tries to deserialize response text into the given type.
-    /// </summary>
-    /// <typeparam name="T">The output type to deserialize into.</typeparam>
-    /// <param name="structuredOutput">The parsed structured output.</param>
-    /// <returns><see langword="true" /> if parsing was successful; otherwise, <see langword="false" />.</returns>
-    public bool TryDeserialize<T>([NotNullWhen(true)] out T? structuredOutput) =>
-        this.TryDeserialize(AgentAbstractionsJsonUtilities.DefaultOptions, out structuredOutput);
-
-    /// <summary>
-    /// Tries to deserialize response text into the given type using the specified serializer options.
-    /// </summary>
-    /// <typeparam name="T">The output type to deserialize into.</typeparam>
-    /// <param name="serializerOptions">The JSON serialization options to use.</param>
-    /// <param name="structuredOutput">The parsed structured output.</param>
-    /// <returns><see langword="true" /> if parsing was successful; otherwise, <see langword="false" />.</returns>
-    public bool TryDeserialize<T>(JsonSerializerOptions serializerOptions, [NotNullWhen(true)] out T? structuredOutput)
-    {
-        _ = Throw.IfNull(serializerOptions);
-
-        try
-        {
-            structuredOutput = this.GetResultCore<T>(serializerOptions, out var failureReason);
-            return failureReason is null;
-        }
-        catch
-        {
-            structuredOutput = default;
-            return false;
-        }
-    }
-
-    private static T? DeserializeFirstTopLevelObject<T>(string json, JsonTypeInfo<T> typeInfo)
-    {
-#if NET
-        // We need to deserialize only the first top-level object as a workaround for a common LLM backend
-        // issue. GPT 3.5 Turbo commonly returns multiple top-level objects after doing a function call.
-        // See https://community.openai.com/t/2-json-objects-returned-when-using-function-calling-and-json-mode/574348
-        var utf8ByteLength = Encoding.UTF8.GetByteCount(json);
-        var buffer = ArrayPool<byte>.Shared.Rent(utf8ByteLength);
-        try
-        {
-            var utf8SpanLength = Encoding.UTF8.GetBytes(json, 0, json.Length, buffer, 0);
-            var reader = new Utf8JsonReader(new ReadOnlySpan<byte>(buffer, 0, utf8SpanLength), new() { AllowMultipleValues = true });
-            return JsonSerializer.Deserialize(ref reader, typeInfo);
-        }
-        finally
-        {
-            ArrayPool<byte>.Shared.Return(buffer);
-        }
-#else
-        return JsonSerializer.Deserialize(json, typeInfo);
-#endif
-    }
-
-    private T? GetResultCore<T>(JsonSerializerOptions serializerOptions, out FailureReason? failureReason)
-    {
-        var json = this.Text;
-        if (string.IsNullOrEmpty(json))
-        {
-            failureReason = FailureReason.ResultDidNotContainJson;
-            return default;
-        }
-
-        // If there's an exception here, we want it to propagate, since the Result property is meant to throw directly
-
-        T? deserialized = DeserializeFirstTopLevelObject(json!, (JsonTypeInfo<T>)serializerOptions.GetTypeInfo(typeof(T)));
-
-        if (deserialized is null)
-        {
-            failureReason = FailureReason.DeserializationProducedNull;
-            return default;
-        }
-
-        failureReason = default;
-        return deserialized;
-    }
-
-    private enum FailureReason
-    {
-        ResultDidNotContainJson,
-        DeserializationProducedNull
-    }
 }

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse{T}.cs

@@ -1,6 +1,17 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Microsoft.Extensions.AI;
+using System;
+#if NET
+using System.Buffers;
+#endif
+
+#if NET
+using System.Text;
+#endif
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Text.Json.Serialization.Metadata;
+using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI;
 
@@ -8,23 +19,80 @@ namespace Microsoft.Agents.AI;
 /// Represents the response of the specified type <typeparamref name="T"/> to an <see cref="AIAgent"/> run request.
 /// </summary>
 /// <typeparam name="T">The type of value expected from the agent.</typeparam>
-public abstract class AgentResponse<T> : AgentResponse
+public class AgentResponse<T> : AgentResponse
 {
-    /// <summary>Initializes a new instance of the <see cref="AgentResponse{T}"/> class.</summary>
-    protected AgentResponse()
+    private readonly JsonSerializerOptions _serializerOptions;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentResponse{T}"/> class.
+    /// </summary>
+    /// <param name="response">The <see cref="AgentResponse"/> from which to populate this <see cref="AgentResponse{T}"/>.</param>
+    /// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> to use when deserializing the result.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="serializerOptions"/> is <see langword="null"/>.</exception>
+    public AgentResponse(AgentResponse response, JsonSerializerOptions serializerOptions) : base(response)
     {
+        _ = Throw.IfNull(serializerOptions);
+
+        this._serializerOptions = serializerOptions;
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="AgentResponse{T}"/> class from an existing <see cref="ChatResponse"/>.
+    /// Gets or sets a value indicating whether the JSON schema has an extra object wrapper.
     /// </summary>
-    /// <param name="response">The <see cref="ChatResponse"/> from which to populate this <see cref="AgentResponse{T}"/>.</param>
-    protected AgentResponse(ChatResponse response) : base(response)
-    {
-    }
+    /// <remarks>
+    /// The wrapper is required for any non-JSON-object-typed values such as numbers, enum values, and arrays.
+    /// </remarks>
+    public bool IsWrappedInObject { get; init; }
 
     /// <summary>
     /// Gets the result value of the agent response as an instance of <typeparamref name="T"/>.
     /// </summary>
-    public abstract T Result { get; }
+    [JsonIgnore]
+    public virtual T Result
+    {
+        get
+        {
+            var json = this.Text;
+            if (string.IsNullOrEmpty(json))
+            {
+                throw new InvalidOperationException("The response did not contain JSON to be deserialized.");
+            }
+
+            if (this.IsWrappedInObject)
+            {
+                json = StructuredOutputSchemaUtilities.UnwrapResponseData(json!);
+            }
+
+            T? deserialized = DeserializeFirstTopLevelObject(json!, (JsonTypeInfo<T>)this._serializerOptions.GetTypeInfo(typeof(T)));
+            if (deserialized is null)
+            {
+                throw new InvalidOperationException("The deserialized response is null.");
+            }
+
+            return deserialized;
+        }
+    }
+
+    private static T? DeserializeFirstTopLevelObject(string json, JsonTypeInfo<T> typeInfo)
+    {
+#if NET
+        // We need to deserialize only the first top-level object as a workaround for a common LLM backend
+        // issue. GPT 3.5 Turbo commonly returns multiple top-level objects after doing a function call.
+        // See https://community.openai.com/t/2-json-objects-returned-when-using-function-calling-and-json-mode/574348
+        var utf8ByteLength = Encoding.UTF8.GetByteCount(json);
+        var buffer = ArrayPool<byte>.Shared.Rent(utf8ByteLength);
+        try
+        {
+            var utf8SpanLength = Encoding.UTF8.GetBytes(json, 0, json.Length, buffer, 0);
+            var reader = new Utf8JsonReader(new ReadOnlySpan<byte>(buffer, 0, utf8SpanLength), new() { AllowMultipleValues = true });
+            return JsonSerializer.Deserialize(ref reader, typeInfo);
+        }
+        finally
+        {
+            ArrayPool<byte>.Shared.Return(buffer);
+        }
+#else
+        return JsonSerializer.Deserialize(json, typeInfo);
+#endif
+    }
 }

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs

@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI;
@@ -28,12 +30,13 @@ public class AgentRunOptions
     /// </summary>
     /// <param name="options">The options instance from which to copy values.</param>
     /// <exception cref="ArgumentNullException"><paramref name="options"/> is <see langword="null"/>.</exception>
-    public AgentRunOptions(AgentRunOptions options)
+    protected AgentRunOptions(AgentRunOptions options)
     {
         _ = Throw.IfNull(options);
         this.ContinuationToken = options.ContinuationToken;
         this.AllowBackgroundResponses = options.AllowBackgroundResponses;
         this.AdditionalProperties = options.AdditionalProperties?.Clone();
+        this.ResponseFormat = options.ResponseFormat;
     }
 
     /// <summary>
@@ -49,6 +52,7 @@ public class AgentRunOptions
     /// can be polled for completion by obtaining the token from the <see cref="AgentResponse.ContinuationToken"/> property
     /// and passing it via this property on subsequent calls to <see cref="AIAgent.RunAsync(AgentSession?, AgentRunOptions?, System.Threading.CancellationToken)"/>.
     /// </remarks>
+    [Experimental(DiagnosticIds.Experiments.AIResponseContinuations)]
     public ResponseContinuationToken? ContinuationToken { get; set; }
 
     /// <summary>
@@ -90,4 +94,35 @@ public class AgentRunOptions
     /// preserving implementation-specific details or extending the options with custom data.
     /// </remarks>
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+
+    /// <summary>
+    /// Gets or sets the response format.
+    /// </summary>
+    /// <remarks>
+    /// If <see langword="null"/>, no response format is specified and the agent will use its default.
+    /// This property can be set to <see cref="ChatResponseFormat.Text"/> to specify that the response should be unstructured text,
+    /// to <see cref="ChatResponseFormat.Json"/> to specify that the response should be structured JSON data, or
+    /// an instance of <see cref="ChatResponseFormatJson"/> constructed with a specific JSON schema to request that the
+    /// response be structured JSON data according to that schema. It is up to the agent implementation if or how
+    /// to honor the request. If the agent implementation doesn't recognize the specific kind of <see cref="ChatResponseFormat"/>,
+    /// it can be ignored.
+    /// </remarks>
+    public ChatResponseFormat? ResponseFormat { get; set; }
+
+    /// <summary>
+    /// Produces a clone of the current <see cref="AgentRunOptions"/> instance.
+    /// </summary>
+    /// <returns>
+    /// A clone of the current <see cref="AgentRunOptions"/> instance.
+    /// </returns>
+    /// <remarks>
+    /// <para>
+    /// The clone will have the same values for all properties as the original instance. Any collections, like <see cref="AdditionalProperties"/>,
+    /// are shallow-cloned, meaning a new collection instance is created, but any references contained by the collections are shared with the original.
+    /// </para>
+    /// <para>
+    /// Derived types should override <see cref="Clone"/> to return an instance of the derived type.
+    /// </para>
+    /// </remarks>
+    public virtual AgentRunOptions Clone() => new(this);
 }

dotnet/src/Microsoft.Agents.AI.Abstractions/ChatHistoryProvider.cs

@@ -2,6 +2,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
@@ -39,6 +40,25 @@ namespace Microsoft.Agents.AI;
 /// </remarks>
 public abstract class ChatHistoryProvider
 {
+    private static IEnumerable<ChatMessage> DefaultExcludeChatHistoryFilter(IEnumerable<ChatMessage> messages)
+        => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory);
+
+    private readonly Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? _provideOutputMessageFilter;
+    private readonly Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> _storeInputMessageFilter;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ChatHistoryProvider"/> class.
+    /// </summary>
+    /// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
+    protected ChatHistoryProvider(
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+    {
+        this._provideOutputMessageFilter = provideOutputMessageFilter;
+        this._storeInputMessageFilter = storeInputMessageFilter ?? DefaultExcludeChatHistoryFilter;
+    }
+
     /// <summary>
     /// Gets the key used to store the provider state in the <see cref="AgentSession.StateBag"/>.
     /// </summary>
@@ -50,20 +70,16 @@ public abstract class ChatHistoryProvider
     public virtual string StateKey => this.GetType().Name;
 
     /// <summary>
-    /// Called at the start of agent invocation to provide messages from the chat history as context for the next agent invocation.
+    /// Called at the start of agent invocation to provide messages for the next agent invocation.
     /// </summary>
     /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>
     /// A task that represents the asynchronous operation. The task result contains a collection of <see cref="ChatMessage"/>
-    /// instances in ascending chronological order (oldest first).
+    /// instances that will be used for the agent invocation.
     /// </returns>
     /// <remarks>
     /// <para>
-    /// Messages are returned in chronological order to maintain proper conversation flow and context for the agent.
-    /// The oldest messages appear first in the collection, followed by more recent messages.
-    /// </para>
-    /// <para>
     /// If the total message history becomes very large, implementations should apply appropriate strategies to manage
     /// storage constraints, such as:
     /// <list type="bullet">
@@ -75,23 +91,19 @@ public abstract class ChatHistoryProvider
     /// </para>
     /// </remarks>
     public ValueTask<IEnumerable<ChatMessage>> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        => this.InvokingCoreAsync(context, cancellationToken);
+        => this.InvokingCoreAsync(Throw.IfNull(context), cancellationToken);
 
     /// <summary>
-    /// Called at the start of agent invocation to provide messages from the chat history as context for the next agent invocation.
+    /// Called at the start of agent invocation to provide messages for the next agent invocation.
     /// </summary>
     /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>
     /// A task that represents the asynchronous operation. The task result contains a collection of <see cref="ChatMessage"/>
-    /// instances in ascending chronological order (oldest first).
+    /// instances that will be used for the agent invocation.
     /// </returns>
     /// <remarks>
     /// <para>
-    /// Messages are returned in chronological order to maintain proper conversation flow and context for the agent.
-    /// The oldest messages appear first in the collection, followed by more recent messages.
-    /// </para>
-    /// <para>
     /// If the total message history becomes very large, implementations should apply appropriate strategies to manage
     /// storage constraints, such as:
     /// <list type="bullet">
@@ -102,11 +114,54 @@ public abstract class ChatHistoryProvider
     /// </list>
     /// </para>
     /// <para>
-    /// Each <see cref="ChatHistoryProvider"/> instance should be associated with a single <see cref="AgentSession"/> to ensure proper message isolation
-    /// and context management.
+    /// The default implementation of this method, calls <see cref="ProvideChatHistoryAsync"/> to get the chat history messages, applies the optional retrieval output filter,
+    /// and merges the returned messages with the caller provided messages (with chat history messages appearing first) before returning the full message list to be used for the invocation.
+    /// For most scenarios, overriding <see cref="ProvideChatHistoryAsync"/> is sufficient to return the desired chat history messages, while still benefiting from the default merging and filtering behavior.
+    /// However, for scenarios that require more control over message filtering, merging or source stamping, overriding this method allows you to directly control the full set of messages returned for the invocation.
     /// </para>
     /// </remarks>
-    protected abstract ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default);
+    protected virtual async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        var output = await this.ProvideChatHistoryAsync(context, cancellationToken).ConfigureAwait(false);
+
+        if (this._provideOutputMessageFilter is not null)
+        {
+            output = this._provideOutputMessageFilter(output);
+        }
+
+        return output
+            .Select(message => message.WithAgentRequestMessageSource(AgentRequestMessageSourceType.ChatHistory, this.GetType().FullName!))
+            .Concat(context.RequestMessages);
+    }
+
+    /// <summary>
+    /// When overridden in a derived class, provides the chat history messages to be used for the current invocation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method is called from <see cref="InvokingCoreAsync"/>.
+    /// Note that <see cref="InvokingCoreAsync"/> can be overridden to directly control message filtering, merging and source stamping, in which case
+    /// it is up to the implementer to call this method as needed to retrieve the unfiltered/unmerged chat history messages.
+    /// </para>
+    /// <para>
+    /// In contrast with <see cref="InvokingCoreAsync"/>, this method only returns additional messages to be added to the request,
+    /// while <see cref="InvokingCoreAsync"/> is responsible for returning the full set of messages to be used for the invocation (including caller provided messages).
+    /// </para>
+    /// <para>
+    /// Messages are returned in chronological order to maintain proper conversation flow and context for the agent.
+    /// The oldest messages appear first in the collection, followed by more recent messages.
+    /// </para>
+    /// </remarks>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains a collection of <see cref="ChatMessage"/>
+    /// instances in ascending chronological order (oldest first).
+    /// </returns>
+    protected virtual ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        return new ValueTask<IEnumerable<ChatMessage>>([]);
+    }
 
     /// <summary>
     /// Called at the end of the agent invocation to add new messages to the chat history.
@@ -134,7 +189,7 @@ public abstract class ChatHistoryProvider
     /// </para>
     /// </remarks>
     public ValueTask InvokedAsync(InvokedContext context, CancellationToken cancellationToken = default) =>
-        this.InvokedCoreAsync(context, cancellationToken);
+        this.InvokedCoreAsync(Throw.IfNull(context), cancellationToken);
 
     /// <summary>
     /// Called at the end of the agent invocation to add new messages to the chat history.
@@ -160,8 +215,59 @@ public abstract class ChatHistoryProvider
     /// This method is called regardless of whether the invocation succeeded or failed.
     /// To check if the invocation was successful, inspect the <see cref="InvokedContext.InvokeException"/> property.
     /// </para>
+    /// <para>
+    /// The default implementation of this method, skips execution for any invocation failures, filters messages using the optional storage input message filter
+    /// and calls <see cref="StoreChatHistoryAsync"/> to store new chat history messages.
+    /// For most scenarios, overriding <see cref="StoreChatHistoryAsync"/> is sufficient to store chat history messages, while still benefiting from the default error handling and filtering behavior.
+    /// However, for scenarios that require more control over error handling or message filtering, overriding this method allows you to directly control the messages that are stored for the invocation.
+    /// </para>
     /// </remarks>
-    protected abstract ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default);
+    protected virtual ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
+    {
+        if (context.InvokeException is not null)
+        {
+            return default;
+        }
+
+        var subContext = new InvokedContext(context.Agent, context.Session, this._storeInputMessageFilter(context.RequestMessages), context.ResponseMessages!);
+        return this.StoreChatHistoryAsync(subContext, cancellationToken);
+    }
+
+    /// <summary>
+    /// When overridden in a derived class, adds new messages to the chat history at the end of the agent invocation.
+    /// </summary>
+    /// <param name="context">Contains the invocation context including request messages, response messages, and any exception that occurred.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous add operation.</returns>
+    /// <remarks>
+    /// <para>
+    /// Messages should be added in the order they were generated to maintain proper chronological sequence.
+    /// The <see cref="ChatHistoryProvider"/> is responsible for preserving message ordering and ensuring that subsequent calls to
+    /// <see cref="InvokingCoreAsync"/> return messages in the correct chronological order.
+    /// </para>
+    /// <para>
+    /// Implementations may perform additional processing during message addition, such as:
+    /// <list type="bullet">
+    /// <item><description>Validating message content and metadata</description></item>
+    /// <item><description>Applying storage optimizations or compression</description></item>
+    /// <item><description>Triggering background maintenance operations</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// This method is called from <see cref="InvokedCoreAsync"/>.
+    /// Note that <see cref="InvokedCoreAsync"/> can be overridden to directly control message filtering and error handling, in which case
+    /// it is up to the implementer to call this method as needed to store messages.
+    /// </para>
+    /// <para>
+    /// In contrast with <see cref="InvokedCoreAsync"/>, this method only stores messages,
+    /// while <see cref="InvokedCoreAsync"/> is also responsible for messages filtering and error handling.
+    /// </para>
+    /// <para>
+    /// The default implementation of <see cref="InvokedCoreAsync"/> only calls this method if the invocation succeeded.
+    /// </para>
+    /// </remarks>
+    protected virtual ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default) =>
+        default;
 
     /// <summary>Asks the <see cref="ChatHistoryProvider"/> for an object of the specified type <paramref name="serviceType"/>.</summary>
     /// <param name="serviceType">The type of object being requested.</param>

dotnet/src/Microsoft.Agents.AI.Abstractions/InMemoryChatHistoryProvider.cs

@@ -3,7 +3,6 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Text.Json;
 using System.Text.Json.Serialization;
 using System.Threading;
 using System.Threading.Tasks;
@@ -27,14 +26,7 @@ namespace Microsoft.Agents.AI;
 /// </remarks>
 public sealed class InMemoryChatHistoryProvider : ChatHistoryProvider
 {
-    private static IEnumerable<ChatMessage> DefaultExcludeChatHistoryFilter(IEnumerable<ChatMessage> messages)
-        => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory);
-
-    private readonly string _stateKey;
-    private readonly Func<AgentSession?, State> _stateInitializer;
-    private readonly JsonSerializerOptions _jsonSerializerOptions;
-    private readonly Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> _storageInputMessageFilter;
-    private readonly Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? _retrievalOutputMessageFilter;
+    private readonly ProviderSessionState<State> _sessionState;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="InMemoryChatHistoryProvider"/> class.
@@ -44,18 +36,20 @@ public sealed class InMemoryChatHistoryProvider : ChatHistoryProvider
     /// message reduction, and serialization settings. If <see langword="null"/>, default settings will be used.
     /// </param>
     public InMemoryChatHistoryProvider(InMemoryChatHistoryProviderOptions? options = null)
+        : base(
+            options?.ProvideOutputMessageFilter,
+            options?.StorageInputMessageFilter)
     {
-        this._stateInitializer = options?.StateInitializer ?? (_ => new State());
+        this._sessionState = new ProviderSessionState<State>(
+            options?.StateInitializer ?? (_ => new State()),
+            options?.StateKey ?? this.GetType().Name,
+            options?.JsonSerializerOptions);
         this.ChatReducer = options?.ChatReducer;
         this.ReducerTriggerEvent = options?.ReducerTriggerEvent ?? InMemoryChatHistoryProviderOptions.ChatReducerTriggerEvent.BeforeMessagesRetrieval;
-        this._stateKey = options?.StateKey ?? base.StateKey;
-        this._jsonSerializerOptions = options?.JsonSerializerOptions ?? AgentAbstractionsJsonUtilities.DefaultOptions;
-        this._storageInputMessageFilter = options?.StorageInputMessageFilter ?? DefaultExcludeChatHistoryFilter;
-        this._retrievalOutputMessageFilter = options?.RetrievalOutputMessageFilter;
     }
 
     /// <inheritdoc />
-    public override string StateKey => this._stateKey;
+    public override string StateKey => this._sessionState.StateKey;
 
     /// <summary>
     /// Gets the chat reducer used to process or reduce chat messages. If null, no reduction logic will be applied.
@@ -73,7 +67,7 @@ public sealed class InMemoryChatHistoryProvider : ChatHistoryProvider
     /// <param name="session">The agent session containing the state.</param>
     /// <returns>A list of chat messages, or an empty list if no state is found.</returns>
     public List<ChatMessage> GetMessages(AgentSession? session)
-        => this.GetOrInitializeState(session).Messages;
+        => this._sessionState.GetOrInitializeState(session).Messages;
 
     /// <summary>
     /// Sets the chat messages for the specified session.
@@ -85,67 +79,30 @@ public sealed class InMemoryChatHistoryProvider : ChatHistoryProvider
     {
         _ = Throw.IfNull(messages);
 
-        var state = this.GetOrInitializeState(session);
+        var state = this._sessionState.GetOrInitializeState(session);
         state.Messages = messages;
     }
 
-    /// <summary>
-    /// Gets the state from the session's StateBag, or initializes it using the state initializer if not present.
-    /// </summary>
-    /// <param name="session">The agent session containing the StateBag.</param>
-    /// <returns>The provider state, or null if no session is available.</returns>
-    private State GetOrInitializeState(AgentSession? session)
-    {
-        if (session?.StateBag.TryGetValue<State>(this._stateKey, out var state, this._jsonSerializerOptions) is true && state is not null)
-        {
-            return state;
-        }
-
-        state = this._stateInitializer(session);
-        if (session is not null)
-        {
-            session.StateBag.SetValue(this._stateKey, state, this._jsonSerializerOptions);
-        }
-
-        return state;
-    }
-
     /// <inheritdoc />
-    protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
     {
-        _ = Throw.IfNull(context);
-
-        var state = this.GetOrInitializeState(context.Session);
+        var state = this._sessionState.GetOrInitializeState(context.Session);
 
         if (this.ReducerTriggerEvent is InMemoryChatHistoryProviderOptions.ChatReducerTriggerEvent.BeforeMessagesRetrieval && this.ChatReducer is not null)
         {
             state.Messages = (await this.ChatReducer.ReduceAsync(state.Messages, cancellationToken).ConfigureAwait(false)).ToList();
         }
 
-        IEnumerable<ChatMessage> output = state.Messages;
-        if (this._retrievalOutputMessageFilter is not null)
-        {
-            output = this._retrievalOutputMessageFilter(output);
-        }
-        return output
-            .Select(message => message.WithAgentRequestMessageSource(AgentRequestMessageSourceType.ChatHistory, this.GetType().FullName!))
-            .Concat(context.RequestMessages);
+        return state.Messages;
     }
 
     /// <inheritdoc />
-    protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
+    protected override async ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
     {
-        _ = Throw.IfNull(context);
-
-        if (context.InvokeException is not null)
-        {
-            return;
-        }
-
-        var state = this.GetOrInitializeState(context.Session);
+        var state = this._sessionState.GetOrInitializeState(context.Session);
 
         // Add request and response messages to the provider
-        var allNewMessages = this._storageInputMessageFilter(context.RequestMessages).Concat(context.ResponseMessages ?? []);
+        var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
         state.Messages.AddRange(allNewMessages);
 
         if (this.ReducerTriggerEvent is InMemoryChatHistoryProviderOptions.ChatReducerTriggerEvent.AfterMessageAdded && this.ChatReducer is not null)

dotnet/src/Microsoft.Agents.AI.Abstractions/InMemoryChatHistoryProviderOptions.cs

@@ -71,7 +71,7 @@ public sealed class InMemoryChatHistoryProviderOptions
     /// <value>
     /// When <see langword="null"/>, no filtering is applied to the output messages.
     /// </value>
-    public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? RetrievalOutputMessageFilter { get; set; }
+    public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? ProvideOutputMessageFilter { get; set; }
 
     /// <summary>
     /// Defines the events that can trigger a reducer in the <see cref="InMemoryChatHistoryProvider"/>.

dotnet/src/Microsoft.Agents.AI.Abstractions/MessageAIContextProvider.cs

@@ -0,0 +1,203 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides an abstract base class for components that enhance AI context during agent invocations by supplying additional chat messages.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A message AI context provider is a component that participates in the agent invocation lifecycle by:
+/// <list type="bullet">
+/// <item><description>Listening to changes in conversations</description></item>
+/// <item><description>Providing additional messages to agents during invocation</description></item>
+/// <item><description>Processing invocation results for state management or learning</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Context providers operate through a two-phase lifecycle: they are called at the start of invocation via
+/// <see cref="AIContextProvider.InvokingAsync"/> to provide context, and optionally called at the end of invocation via
+/// <see cref="AIContextProvider.InvokedAsync"/> to process results.
+/// </para>
+/// </remarks>
+public abstract class MessageAIContextProvider : AIContextProvider
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MessageAIContextProvider"/> class.
+    /// </summary>
+    /// <param name="provideInputMessageFilter">An optional filter function to apply to input messages before providing messages via <see cref="ProvideMessagesAsync"/>. If not set, defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to request messages before storing messages via <see cref="AIContextProvider.StoreAIContextAsync"/>. If not set, defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages.</param>
+    protected MessageAIContextProvider(
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideInputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+        : base(provideInputMessageFilter, storeInputMessageFilter)
+    {
+    }
+
+    /// <inheritdoc/>
+    protected override async ValueTask<AIContext> ProvideAIContextAsync(AIContextProvider.InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        // Call ProvideMessagesAsync directly to return only additional messages.
+        // The base AIContextProvider.InvokingCoreAsync handles merging with the original input and stamping.
+        return new AIContext
+        {
+            Messages = await this.ProvideMessagesAsync(
+                new InvokingContext(context.Agent, context.Session, context.AIContext.Messages ?? []),
+                cancellationToken).ConfigureAwait(false)
+        };
+    }
+
+    /// <summary>
+    /// Called at the start of agent invocation to provide additional messages.
+    /// </summary>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the <see cref="IEnumerable{ChatMessage}"/> to be used by the agent during this invocation.</returns>
+    /// <remarks>
+    /// <para>
+    /// Implementers can load any additional messages required at this time, such as:
+    /// <list type="bullet">
+    /// <item><description>Retrieving relevant information from knowledge bases</description></item>
+    /// <item><description>Adding system instructions or prompts</description></item>
+    /// <item><description>Injecting contextual messages from conversation history</description></item>
+    /// </list>
+    /// </para>
+    /// </remarks>
+    public ValueTask<IEnumerable<ChatMessage>> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        => this.InvokingCoreAsync(Throw.IfNull(context), cancellationToken);
+
+    /// <summary>
+    /// Called at the start of agent invocation to provide additional messages.
+    /// </summary>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the <see cref="IEnumerable{ChatMessage}"/> to be used by the agent during this invocation.</returns>
+    /// <remarks>
+    /// <para>
+    /// Implementers can load any additional messages required at this time, such as:
+    /// <list type="bullet">
+    /// <item><description>Retrieving relevant information from knowledge bases</description></item>
+    /// <item><description>Adding system instructions or prompts</description></item>
+    /// <item><description>Injecting contextual messages from conversation history</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// The default implementation of this method filters the input messages using the configured provide-input message filter
+    /// (which defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages),
+    /// then calls <see cref="ProvideMessagesAsync"/> to get additional messages,
+    /// stamps any messages with <see cref="AgentRequestMessageSourceType.AIContextProvider"/> source attribution,
+    /// and merges the returned messages with the original (unfiltered) input messages.
+    /// For most scenarios, overriding <see cref="ProvideMessagesAsync"/> is sufficient to provide additional messages,
+    /// while still benefiting from the default filtering, merging and source stamping behavior.
+    /// However, for scenarios that require more control over message filtering, merging or source stamping, overriding this method
+    /// allows you to directly control the full <see cref="IEnumerable{ChatMessage}"/> returned for the invocation.
+    /// </para>
+    /// </remarks>
+    protected virtual async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        var inputMessages = context.RequestMessages;
+
+        // Create a filtered context for ProvideMessagesAsync, filtering input messages
+        // to exclude non-external messages (e.g. chat history, other AI context provider messages).
+        var filteredContext = new InvokingContext(
+            context.Agent,
+            context.Session,
+            this.ProvideInputMessageFilter(inputMessages));
+
+        var providedMessages = await this.ProvideMessagesAsync(filteredContext, cancellationToken).ConfigureAwait(false);
+
+        // Stamp and merge provided messages.
+        providedMessages = providedMessages.Select(m => m.WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!));
+        return inputMessages.Concat(providedMessages);
+    }
+
+    /// <summary>
+    /// When overridden in a derived class, provides additional messages to be merged with the input messages for the current invocation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method is called from <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/>.
+    /// Note that <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/> can be overridden to directly control messages merging and source stamping, in which case
+    /// it is up to the implementer to call this method as needed to retrieve the additional messages.
+    /// </para>
+    /// <para>
+    /// In contrast with <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/>, this method only returns additional messages to be merged with the input,
+    /// while <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/> is responsible for returning the full merged <see cref="IEnumerable{ChatMessage}"/> for the invocation.
+    /// </para>
+    /// </remarks>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains an <see cref="IEnumerable{ChatMessage}"/>
+    /// with additional messages to be merged with the input messages.
+    /// </returns>
+    protected virtual ValueTask<IEnumerable<ChatMessage>> ProvideMessagesAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        return new ValueTask<IEnumerable<ChatMessage>>([]);
+    }
+
+    /// <summary>
+    /// Contains the context information provided to <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/>.
+    /// </summary>
+    /// <remarks>
+    /// This class provides context about the invocation before the underlying AI model is invoked, including the messages
+    /// that will be used. Message AI Context providers can use this information to determine what additional messages
+    /// should be provided for the invocation.
+    /// </remarks>
+    public new sealed class InvokingContext
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvokingContext"/> class with the specified request messages.
+        /// </summary>
+        /// <param name="agent">The agent being invoked.</param>
+        /// <param name="session">The session associated with the agent invocation.</param>
+        /// <param name="requestMessages">The messages to be used by the agent for this invocation.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="agent"/> or <paramref name="requestMessages"/> is <see langword="null"/>.</exception>
+        public InvokingContext(
+            AIAgent agent,
+            AgentSession? session,
+            IEnumerable<ChatMessage> requestMessages)
+        {
+            this.Agent = Throw.IfNull(agent);
+            this.Session = session;
+            this.RequestMessages = Throw.IfNull(requestMessages);
+        }
+
+        /// <summary>
+        /// Gets the agent that is being invoked.
+        /// </summary>
+        public AIAgent Agent { get; }
+
+        /// <summary>
+        /// Gets the agent session associated with the agent invocation.
+        /// </summary>
+        public AgentSession? Session { get; }
+
+        /// <summary>
+        /// Gets the messages that will be used by the agent for this invocation. <see cref="MessageAIContextProvider"/> instances can modify
+        /// and return or return a new message list to add additional messages for the invocation.
+        /// </summary>
+        /// <value>
+        /// A collection of <see cref="ChatMessage"/> instances representing the messages that will be used by the agent for this invocation.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// If multiple <see cref="MessageAIContextProvider"/> instances are used in the same invocation, each <see cref="MessageAIContextProvider"/>
+        /// will receive the messages returned by the previous <see cref="MessageAIContextProvider"/> allowing them to build on top of each other's context.
+        /// </para>
+        /// <para>
+        /// The first <see cref="MessageAIContextProvider"/> in the invocation pipeline will receive the
+        /// caller provided messages.
+        /// </para>
+        /// </remarks>
+        public IEnumerable<ChatMessage> RequestMessages { get; set { field = Throw.IfNull(value); } }
+    }
+}

dotnet/src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj

@@ -3,16 +3,19 @@
   <PropertyGroup>
     <RootNamespace>Microsoft.Agents.AI</RootNamespace>
     <NoWarn>$(NoWarn);MEAI001</NoWarn>
-    <VersionSuffix>preview</VersionSuffix>
+    <IsReleaseCandidate>true</IsReleaseCandidate>
   </PropertyGroup>
 
   <PropertyGroup>
     <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectSharedStructuredOutput>true</InjectSharedStructuredOutput>
     <InjectDiagnosticClassesOnLegacy>true</InjectDiagnosticClassesOnLegacy>
     <InjectTrimAttributesOnLegacy>true</InjectTrimAttributesOnLegacy>
     <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
     <InjectRequiredMemberOnLegacy>true</InjectRequiredMemberOnLegacy>
     <InjectCompilerFeatureRequiredOnLegacy>true</InjectCompilerFeatureRequiredOnLegacy>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
   </PropertyGroup>
 
   <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />

dotnet/src/Microsoft.Agents.AI.Abstractions/ProviderSessionState{TState}.cs

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Text.Json;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides strongly-typed state management for providers, enabling reading and writing of provider-specific state
+/// to and from an <see cref="AgentSession"/>'s <see cref="AgentSessionStateBag"/>.
+/// </summary>
+/// <typeparam name="TState">The type of the state to be maintained. Must be a reference type.</typeparam>
+/// <remarks>
+/// <para>
+/// This class encapsulates the logic for initializing, retrieving, and persisting provider state in the session's StateBag
+/// using a configurable key and JSON serialization options. It is intended to be used as a composed field within provider
+/// implementations (e.g., <see cref="AIContextProvider"/> or <see cref="ChatHistoryProvider"/> subclasses) to avoid
+/// duplicating state management logic across provider type hierarchies.
+/// </para>
+/// <para>
+/// State is stored in the <see cref="AgentSession.StateBag"/> using the <see cref="StateKey"/> property as the key,
+/// enabling multiple providers to maintain independent state within the same session.
+/// </para>
+/// </remarks>
+public class ProviderSessionState<TState>
+    where TState : class
+{
+    private readonly Func<AgentSession?, TState> _stateInitializer;
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ProviderSessionState{TState}"/> class.
+    /// </summary>
+    /// <param name="stateInitializer">A function to initialize the state when it is not yet present in the session's StateBag.</param>
+    /// <param name="stateKey">The key used to store the state in the session's StateBag.</param>
+    /// <param name="jsonSerializerOptions">Options for JSON serialization and deserialization of the state.</param>
+    public ProviderSessionState(
+        Func<AgentSession?, TState> stateInitializer,
+        string stateKey,
+        JsonSerializerOptions? jsonSerializerOptions = null)
+    {
+        this._stateInitializer = Throw.IfNull(stateInitializer);
+        this.StateKey = Throw.IfNullOrWhitespace(stateKey);
+        this._jsonSerializerOptions = jsonSerializerOptions ?? AgentAbstractionsJsonUtilities.DefaultOptions;
+    }
+
+    /// <summary>
+    /// Gets the key used to store the provider state in the <see cref="AgentSession.StateBag"/>.
+    /// </summary>
+    public string StateKey { get; }
+
+    /// <summary>
+    /// Gets the state from the session's StateBag, or initializes it using the state initializer if not present.
+    /// </summary>
+    /// <param name="session">The agent session containing the StateBag.</param>
+    /// <returns>The provider state.</returns>
+    public TState GetOrInitializeState(AgentSession? session)
+    {
+        if (session?.StateBag.TryGetValue<TState>(this.StateKey, out var state, this._jsonSerializerOptions) is true && state is not null)
+        {
+            return state;
+        }
+
+        state = this._stateInitializer(session);
+        if (session is not null)
+        {
+            session.StateBag.SetValue(this.StateKey, state, this._jsonSerializerOptions);
+        }
+
+        return state;
+    }
+
+    /// <summary>
+    /// Saves the specified state to the session's StateBag using the configured state key and JSON serializer options.
+    /// If the session is null, this method does nothing.
+    /// </summary>
+    /// <param name="session">The agent session containing the StateBag.</param>
+    /// <param name="state">The state to be saved.</param>
+    public void SaveState(AgentSession? session, TState state)
+    {
+        if (session is not null)
+        {
+            session.StateBag.SetValue(this.StateKey, state, this._jsonSerializerOptions);
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionSuffix>preview</VersionSuffix>
+    <IsReleaseCandidate>true</IsReleaseCandidate>
     <ImplicitUsings>enable</ImplicitUsings>
     <InjectSharedThrow>true</InjectSharedThrow>
   </PropertyGroup>

dotnet/src/Microsoft.Agents.AI.AzureAI/AzureAIProjectChatClient.cs

@@ -1,20 +1,21 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using Azure.AI.Projects;
 using Azure.AI.Projects.OpenAI;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 using OpenAI.Responses;
 
-#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-
 namespace Microsoft.Agents.AI.AzureAI;
 
 /// <summary>
 /// Provides a chat client implementation that integrates with Azure AI Agents, enabling chat interactions using
 /// Azure-specific agent capabilities.
 /// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 internal sealed class AzureAIProjectChatClient : DelegatingChatClient
 {
     private readonly ChatClientMetadata? _metadata;

dotnet/src/Microsoft.Agents.AI.AzureAI/AzureAIProjectChatClientExtensions.cs

@@ -2,6 +2,7 @@
 
 using System.ClientModel;
 using System.ClientModel.Primitives;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.Json;
@@ -12,18 +13,17 @@ using Azure.AI.Projects.OpenAI;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.AzureAI;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 using OpenAI;
 using OpenAI.Responses;
 
-#pragma warning disable MEAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-
 namespace Azure.AI.Projects;
 
 /// <summary>
 /// Provides extension methods for <see cref="AIProjectClient"/>.
 /// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public static partial class AzureAIProjectChatClientExtensions
 {
     /// <summary>

dotnet/src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj

@@ -1,13 +1,18 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionSuffix>preview</VersionSuffix>
+    <IsReleaseCandidate>true</IsReleaseCandidate>
     <ImplicitUsings>enable</ImplicitUsings>
     <InjectSharedThrow>true</InjectSharedThrow>
   </PropertyGroup>
 
   <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
 
+  <PropertyGroup>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.AI.Projects.OpenAI" />

dotnet/src/Microsoft.Agents.AI.CopilotStudio/CopilotStudioAgent.cs

@@ -60,7 +60,7 @@ public class CopilotStudioAgent : AIAgent
 
         if (session is not CopilotStudioAgentSession typedSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be serialized.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(CopilotStudioAgentSession)}' can be serialized by this agent.");
         }
 
         return new(typedSession.Serialize(jsonSerializerOptions));
@@ -84,7 +84,7 @@ public class CopilotStudioAgent : AIAgent
         session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
         if (session is not CopilotStudioAgentSession typedSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be used.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(CopilotStudioAgentSession)}' can be used by this agent.");
         }
 
         typedSession.ConversationId ??= await this.StartNewConversationAsync(cancellationToken).ConfigureAwait(false);
@@ -123,7 +123,7 @@ public class CopilotStudioAgent : AIAgent
         session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
         if (session is not CopilotStudioAgentSession typedSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be used.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(CopilotStudioAgentSession)}' can be used by this agent.");
         }
 
         typedSession.ConversationId ??= await this.StartNewConversationAsync(cancellationToken).ConfigureAwait(false);

dotnet/src/Microsoft.Agents.AI.CosmosNoSql/CosmosChatHistoryProvider.cs

@@ -21,14 +21,10 @@ namespace Microsoft.Agents.AI;
 [RequiresDynamicCode("The CosmosChatHistoryProvider uses JSON serialization which is incompatible with NativeAOT.")]
 public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
 {
-    private static IEnumerable<ChatMessage> DefaultExcludeChatHistoryFilter(IEnumerable<ChatMessage> messages)
-        => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory);
-
+    private readonly ProviderSessionState<State> _sessionState;
     private readonly CosmosClient _cosmosClient;
     private readonly Container _container;
     private readonly bool _ownsClient;
-    private readonly string _stateKey;
-    private readonly Func<AgentSession?, State> _stateInitializer;
     private bool _disposed;
 
     /// <summary>
@@ -46,9 +42,6 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         return options;
     }
 
-    /// <inheritdoc />
-    public override string StateKey => this._stateKey;
-
     /// <summary>
     /// Gets or sets the maximum number of messages to return in a single query batch.
     /// Default is 100 for optimal performance.
@@ -84,25 +77,6 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
     /// </summary>
     public string ContainerId { get; init; }
 
-    /// <summary>
-    /// A filter function applied to request messages before they are stored
-    /// during <see cref="ChatHistoryProvider.InvokedAsync"/>. The default filter excludes messages with the
-    /// <see cref="AgentRequestMessageSourceType.ChatHistory"/> source type.
-    /// </summary>
-    public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> StorageInputMessageFilter { get; set { field = Throw.IfNull(value); } } = DefaultExcludeChatHistoryFilter;
-
-    /// <summary>
-    /// Gets or sets an optional filter function applied to messages produced by this provider
-    /// during <see cref="ChatHistoryProvider.InvokingAsync"/>.
-    /// </summary>
-    /// <remarks>
-    /// This filter is only applied to the messages that the provider itself produces (from its internal storage).
-    /// </remarks>
-    /// <value>
-    /// When <see langword="null"/>, no filtering is applied to the output messages.
-    /// </value>
-    public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? RetrievalOutputMessageFilter { get; set; }
-
     /// <summary>
     /// Initializes a new instance of the <see cref="CosmosChatHistoryProvider"/> class.
     /// </summary>
@@ -112,6 +86,8 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
     /// <param name="stateInitializer">A delegate that initializes the provider state on the first invocation, providing the conversation routing info (conversationId, tenantId, userId).</param>
     /// <param name="ownsClient">Whether this instance owns the CosmosClient and should dispose it.</param>
     /// <param name="stateKey">An optional key to use for storing the state in the <see cref="AgentSession.StateBag"/>.</param>
+    /// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="cosmosClient"/> or <paramref name="stateInitializer"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException">Thrown when any string parameter is null or whitespace.</exception>
     public CosmosChatHistoryProvider(
@@ -120,17 +96,24 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         string containerId,
         Func<AgentSession?, State> stateInitializer,
         bool ownsClient = false,
-        string? stateKey = null)
+        string? stateKey = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+        : base(provideOutputMessageFilter, storeInputMessageFilter)
     {
+        this._sessionState = new ProviderSessionState<State>(
+            Throw.IfNull(stateInitializer),
+            stateKey ?? this.GetType().Name);
         this._cosmosClient = Throw.IfNull(cosmosClient);
         this.DatabaseId = Throw.IfNullOrWhitespace(databaseId);
         this.ContainerId = Throw.IfNullOrWhitespace(containerId);
         this._container = this._cosmosClient.GetContainer(databaseId, containerId);
-        this._stateInitializer = Throw.IfNull(stateInitializer);
         this._ownsClient = ownsClient;
-        this._stateKey = stateKey ?? base.StateKey;
     }
 
+    /// <inheritdoc />
+    public override string StateKey => this._sessionState.StateKey;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="CosmosChatHistoryProvider"/> class using a connection string.
     /// </summary>
@@ -139,6 +122,8 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
     /// <param name="containerId">The identifier of the Cosmos DB container.</param>
     /// <param name="stateInitializer">A delegate that initializes the provider state on the first invocation.</param>
     /// <param name="stateKey">An optional key to use for storing the state in the <see cref="AgentSession.StateBag"/>.</param>
+    /// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
     /// <exception cref="ArgumentNullException">Thrown when any required parameter is null.</exception>
     /// <exception cref="ArgumentException">Thrown when any string parameter is null or whitespace.</exception>
     public CosmosChatHistoryProvider(
@@ -146,8 +131,10 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         string databaseId,
         string containerId,
         Func<AgentSession?, State> stateInitializer,
-        string? stateKey = null)
-        : this(new CosmosClient(Throw.IfNullOrWhitespace(connectionString)), databaseId, containerId, stateInitializer, ownsClient: true, stateKey)
+        string? stateKey = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+        : this(new CosmosClient(Throw.IfNullOrWhitespace(connectionString)), databaseId, containerId, stateInitializer, ownsClient: true, stateKey, provideOutputMessageFilter, storeInputMessageFilter)
     {
     }
 
@@ -160,6 +147,8 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
     /// <param name="containerId">The identifier of the Cosmos DB container.</param>
     /// <param name="stateInitializer">A delegate that initializes the provider state on the first invocation.</param>
     /// <param name="stateKey">An optional key to use for storing the state in the <see cref="AgentSession.StateBag"/>.</param>
+    /// <param name="provideOutputMessageFilter">An optional filter function to apply to messages when retrieving them from the chat history.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to messages before storing them in the chat history. If not set, defaults to excluding messages with source type <see cref="AgentRequestMessageSourceType.ChatHistory"/>.</param>
     /// <exception cref="ArgumentNullException">Thrown when any required parameter is null.</exception>
     /// <exception cref="ArgumentException">Thrown when any string parameter is null or whitespace.</exception>
     public CosmosChatHistoryProvider(
@@ -168,32 +157,13 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         string databaseId,
         string containerId,
         Func<AgentSession?, State> stateInitializer,
-        string? stateKey = null)
-        : this(new CosmosClient(Throw.IfNullOrWhitespace(accountEndpoint), Throw.IfNull(tokenCredential)), databaseId, containerId, stateInitializer, ownsClient: true, stateKey)
+        string? stateKey = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+        : this(new CosmosClient(Throw.IfNullOrWhitespace(accountEndpoint), Throw.IfNull(tokenCredential)), databaseId, containerId, stateInitializer, ownsClient: true, stateKey, provideOutputMessageFilter, storeInputMessageFilter)
     {
     }
 
-    /// <summary>
-    /// Gets the state from the session's StateBag, or initializes it using the state initializer if not present.
-    /// </summary>
-    /// <param name="session">The agent session containing the StateBag.</param>
-    /// <returns>The provider state, or null if no session is available.</returns>
-    private State GetOrInitializeState(AgentSession? session)
-    {
-        if (session?.StateBag.TryGetValue<State>(this._stateKey, out var state, AgentAbstractionsJsonUtilities.DefaultOptions) is true && state is not null)
-        {
-            return state;
-        }
-
-        state = this._stateInitializer(session);
-        if (session is not null)
-        {
-            session.StateBag.SetValue(this._stateKey, state, AgentAbstractionsJsonUtilities.DefaultOptions);
-        }
-
-        return state;
-    }
-
     /// <summary>
     /// Determines whether hierarchical partitioning should be used based on the state.
     /// </summary>
@@ -218,7 +188,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
     }
 
     /// <inheritdoc />
-    protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
     {
 #pragma warning disable CA1513 // Use ObjectDisposedException.ThrowIf - not available on all target frameworks
         if (this._disposed)
@@ -227,9 +197,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         }
 #pragma warning restore CA1513
 
-        _ = Throw.IfNull(context);
-
-        var state = this.GetOrInitializeState(context.Session);
+        var state = this._sessionState.GetOrInitializeState(context.Session);
         var partitionKey = BuildPartitionKey(state);
 
         // Fetch most recent messages in descending order when limit is set, then reverse to ascending
@@ -279,22 +247,12 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
             messages.Reverse();
         }
 
-        return (this.RetrievalOutputMessageFilter is not null ? this.RetrievalOutputMessageFilter(messages) : messages)
-            .Select(message => message.WithAgentRequestMessageSource(AgentRequestMessageSourceType.ChatHistory, this.GetType().FullName!))
-            .Concat(context.RequestMessages);
+        return messages;
     }
 
     /// <inheritdoc />
-    protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
+    protected override async ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
     {
-        Throw.IfNull(context);
-
-        if (context.InvokeException is not null)
-        {
-            // Do not store messages if there was an exception during invocation
-            return;
-        }
-
 #pragma warning disable CA1513 // Use ObjectDisposedException.ThrowIf - not available on all target frameworks
         if (this._disposed)
         {
@@ -302,8 +260,8 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         }
 #pragma warning restore CA1513
 
-        var state = this.GetOrInitializeState(context.Session);
-        var messageList = this.StorageInputMessageFilter(context.RequestMessages).Concat(context.ResponseMessages ?? []).ToList();
+        var state = this._sessionState.GetOrInitializeState(context.Session);
+        var messageList = context.RequestMessages.Concat(context.ResponseMessages ?? []).ToList();
         if (messageList.Count == 0)
         {
             return;
@@ -473,7 +431,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         }
 #pragma warning restore CA1513
 
-        var state = this.GetOrInitializeState(session);
+        var state = this._sessionState.GetOrInitializeState(session);
         var partitionKey = BuildPartitionKey(state);
 
         // Efficient count query
@@ -507,7 +465,7 @@ public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
         }
 #pragma warning restore CA1513
 
-        var state = this.GetOrInitializeState(session);
+        var state = this._sessionState.GetOrInitializeState(session);
         var partitionKey = BuildPartitionKey(state);
 
         // Batch delete for efficiency

dotnet/src/Microsoft.Agents.AI.CosmosNoSql/Microsoft.Agents.AI.CosmosNoSql.csproj

@@ -3,7 +3,6 @@
   <PropertyGroup>
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
     <RootNamespace>Microsoft.Agents.AI</RootNamespace>
-    <NoWarn>$(NoWarn);MEAI001</NoWarn>
     <VersionSuffix>preview</VersionSuffix>
   </PropertyGroup>
 

dotnet/src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionSuffix>preview</VersionSuffix>
+    <IsReleaseCandidate>true</IsReleaseCandidate>
     <NoWarn>$(NoWarn);MEAI001</NoWarn>
     <IsPackable>false</IsPackable>
   </PropertyGroup>

dotnet/src/Microsoft.Agents.AI.DurableTask/CHANGELOG.md

@@ -13,6 +13,8 @@
 - Introduce Core method pattern for Session management methods on AIAgent ([#3699](https://github.com/microsoft/agent-framework/pull/3699))
 - Changed AIAgent.SerializeSession to AIAgent.SerializeSessionAsync ([#3879](https://github.com/microsoft/agent-framework/pull/3879))
 - Changed ChatHistory and AIContext Providers to have pipeline semantics ([#3806](https://github.com/microsoft/agent-framework/pull/3806))
+- Marked all `RunAsync<T>` overloads as `new`, added missing ones, and added support for primitives and arrays ([#3803](https://github.com/microsoft/agent-framework/pull/3803))
+- Improve session cast error message quality and consistency ([#3973](https://github.com/microsoft/agent-framework/pull/3973))
 
 ## v1.0.0-preview.251204.1
 

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAIAgent.cs

@@ -1,12 +1,11 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Text.Json;
-using System.Text.Json.Serialization.Metadata;
 using Microsoft.DurableTask;
 using Microsoft.DurableTask.Entities;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.DurableTask;
 
@@ -56,7 +55,7 @@ public sealed class DurableAIAgent : AIAgent
 
         if (session is not DurableAgentSession durableSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be serialized.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(DurableAgentSession)}' can be serialized by this agent.");
         }
 
         return new(durableSession.Serialize(jsonSerializerOptions));
@@ -114,7 +113,6 @@ public sealed class DurableAIAgent : AIAgent
         {
             enableToolCalls = durableOptions.EnableToolCalls;
             enableToolNames = durableOptions.EnableToolNames;
-            responseFormat = durableOptions.ResponseFormat;
         }
         else if (options is ChatClientAgentRunOptions chatClientOptions && chatClientOptions.ChatOptions?.Tools != null)
         {
@@ -122,6 +120,12 @@ public sealed class DurableAIAgent : AIAgent
             responseFormat = chatClientOptions.ChatOptions?.ResponseFormat;
         }
 
+        // Override the response format if specified in the agent run options
+        if (options?.ResponseFormat is { } format)
+        {
+            responseFormat = format;
+        }
+
         RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames)
         {
             OrchestrationId = this._context.InstanceId
@@ -168,108 +172,125 @@ public sealed class DurableAIAgent : AIAgent
     }
 
     /// <summary>
-    /// Runs the agent with a message and returns the deserialized output as an instance of <typeparamref name="T"/>.
+    /// Run the agent with no message assuming that all required instructions are already provided to the agent or on the session, and requesting a response of the specified type <typeparamref name="T"/>.
     /// </summary>
-    /// <param name="message">The message to send to the agent.</param>
-    /// <param name="session">The agent session to use.</param>
-    /// <param name="serializerOptions">Optional JSON serializer options.</param>
-    /// <param name="options">Optional run options.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
-    /// <typeparam name="T">The type of the output.</typeparam>
-    /// <exception cref="ArgumentException">
-    /// Thrown when the provided <paramref name="options"/> already contains a response schema.
-    /// Thrown when the provided <paramref name="options"/> is not a <see cref="DurableAgentRunOptions"/>.
-    /// </exception>
-    /// <exception cref="InvalidOperationException">
-    /// Thrown when the agent response is empty or cannot be deserialized.
-    /// </exception>
-    /// <returns>The output from the agent.</returns>
-    public async Task<AgentResponse<T>> RunAsync<T>(
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <remarks>
+    /// This method is specific to durable agents because the Durable Task Framework uses a custom
+    /// synchronization context for orchestration execution, and all continuations must run on the
+    /// orchestration thread to avoid breaking the durable orchestration and potential deadlocks.
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default) =>
+        this.RunAsync<T>([], session, serializerOptions, options, cancellationToken);
+
+    /// <summary>
+    /// Runs the agent with a text message from the user, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="message">The user message to send to the agent.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input message and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <exception cref="ArgumentException"><paramref name="message"/> is <see langword="null"/>, empty, or contains only whitespace.</exception>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
         string message,
         AgentSession? session = null,
         JsonSerializerOptions? serializerOptions = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default)
     {
-        return await this.RunAsync<T>(
-            messages: [new ChatMessage(ChatRole.User, message) { CreatedAt = DateTimeOffset.UtcNow }],
-            session,
-            serializerOptions,
-            options,
-            cancellationToken);
+        _ = Throw.IfNull(message);
+
+        return this.RunAsync<T>(new ChatMessage(ChatRole.User, message), session, serializerOptions, options, cancellationToken);
     }
 
     /// <summary>
-    /// Runs the agent with messages and returns the deserialized output as an instance of <typeparamref name="T"/>.
+    /// Runs the agent with a single chat message, requesting a response of the specified type <typeparamref name="T"/>.
     /// </summary>
-    /// <param name="messages">The messages to send to the agent.</param>
-    /// <param name="session">The agent session to use.</param>
-    /// <param name="serializerOptions">Optional JSON serializer options.</param>
-    /// <param name="options">Optional run options.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
-    /// <typeparam name="T">The type of the output.</typeparam>
-    /// <exception cref="ArgumentException">
-    /// Thrown when the provided <paramref name="options"/> already contains a response schema.
-    /// Thrown when the provided <paramref name="options"/> is not a <see cref="DurableAgentRunOptions"/>.
-    /// </exception>
-    /// <exception cref="InvalidOperationException">
-    /// Thrown when the agent response is empty or cannot be deserialized.
-    /// </exception>
-    /// <returns>The output from the agent.</returns>
-    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback to reflection-based deserialization is intentional for library flexibility with user-defined types.")]
-    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050", Justification = "Fallback to reflection-based deserialization is intentional for library flexibility with user-defined types.")]
-    public async Task<AgentResponse<T>> RunAsync<T>(
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="message">The chat message to send to the agent.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input message and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        ChatMessage message,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(message);
+
+        return this.RunAsync<T>([message], session, serializerOptions, options, cancellationToken);
+    }
+
+    /// <summary>
+    /// Runs the agent with a collection of chat messages, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="messages">The collection of messages to send to the agent for processing.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input messages and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new async Task<AgentResponse<T>> RunAsync<T>(
         IEnumerable<ChatMessage> messages,
         AgentSession? session = null,
         JsonSerializerOptions? serializerOptions = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default)
     {
-        options ??= new DurableAgentRunOptions();
-        if (options is not DurableAgentRunOptions durableOptions)
-        {
-            throw new ArgumentException(
-                "Response schema is only supported with DurableAgentRunOptions when using durable agents. " +
-                "Cannot specify a response schema when calling RunAsync<T>.",
-                paramName: nameof(options));
-        }
+        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;
 
-        if (durableOptions.ResponseFormat is not null)
-        {
-            throw new ArgumentException(
-                "A response schema is already defined in the provided DurableAgentRunOptions. " +
-                "Cannot specify a response schema when calling RunAsync<T>.",
-                paramName: nameof(options));
-        }
+        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
 
-        // Create the JSON schema for the response type
-        durableOptions.ResponseFormat = ChatResponseFormat.ForJsonSchema<T>();
+        (responseFormat, bool isWrappedInObject) = StructuredOutputSchemaUtilities.WrapNonObjectSchema(responseFormat);
 
-        AgentResponse response = await this.RunAsync(messages, session, durableOptions, cancellationToken);
+        options = options?.Clone() ?? new DurableAgentRunOptions();
+        options.ResponseFormat = responseFormat;
 
-        // Deserialize the response text to the requested type
-        if (string.IsNullOrEmpty(response.Text))
-        {
-            throw new InvalidOperationException("Agent response is empty and cannot be deserialized.");
-        }
+        // ConfigureAwait(false) cannot be used here because the Durable Task Framework uses
+        // a custom synchronization context that requires all continuations to execute on the
+        // orchestration thread. Scheduling the continuation on an arbitrary thread would break
+        // the orchestration.
+        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken);
 
-        serializerOptions ??= DurableAgentJsonUtilities.DefaultOptions;
-
-        // Prefer source-generated metadata when available to support AOT/trimming scenarios.
-        // Fallback to reflection-based deserialization for types without source-generated metadata.
-        // This is necessary since T is a user-provided type that may not have [JsonSerializable] coverage.
-        JsonTypeInfo? typeInfo = serializerOptions.GetTypeInfo(typeof(T));
-        T? result = (typeInfo is JsonTypeInfo typedInfo
-            ? (T?)JsonSerializer.Deserialize(response.Text, typedInfo)
-            : JsonSerializer.Deserialize<T>(response.Text, serializerOptions))
-            ?? throw new InvalidOperationException($"Failed to deserialize agent response to type {typeof(T).Name}.");
-
-        return new DurableAIAgentResponse<T>(response, result);
-    }
-
-    private sealed class DurableAIAgentResponse<T>(AgentResponse response, T result)
-        : AgentResponse<T>(response.AsChatResponse())
-    {
-        public override T Result { get; } = result;
+        return new AgentResponse<T>(response, serializerOptions) { IsWrappedInObject = isWrappedInObject };
     }
 }

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAIAgentProxy.cs

@@ -20,7 +20,7 @@ internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient)
 
         if (session is not DurableAgentSession durableSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be serialized.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(DurableAgentSession)}' can be serialized by this agent.");
         }
 
         return new(durableSession.Serialize(jsonSerializerOptions));
@@ -62,7 +62,6 @@ internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient)
         {
             enableToolCalls = durableOptions.EnableToolCalls;
             enableToolNames = durableOptions.EnableToolNames;
-            responseFormat = durableOptions.ResponseFormat;
             isFireAndForget = durableOptions.IsFireAndForget;
         }
         else if (options is ChatClientAgentRunOptions chatClientOptions)
@@ -71,6 +70,12 @@ internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient)
             responseFormat = chatClientOptions.ChatOptions?.ResponseFormat;
         }
 
+        // Override the response format if specified in the agent run options
+        if (options?.ResponseFormat is { } format)
+        {
+            responseFormat = format;
+        }
+
         RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames);
         AgentSessionId sessionId = durableSession.SessionId;
 

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentRunOptions.cs

@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Microsoft.Extensions.AI;
-
 namespace Microsoft.Agents.AI.DurableTask;
 
 /// <summary>
@@ -9,6 +7,25 @@ namespace Microsoft.Agents.AI.DurableTask;
 /// </summary>
 public sealed class DurableAgentRunOptions : AgentRunOptions
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAgentRunOptions"/> class.
+    /// </summary>
+    public DurableAgentRunOptions()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAgentRunOptions"/> class by copying values from the specified options.
+    /// </summary>
+    /// <param name="options">The options instance from which to copy values.</param>
+    private DurableAgentRunOptions(DurableAgentRunOptions options)
+        : base(options)
+    {
+        this.EnableToolCalls = options.EnableToolCalls;
+        this.EnableToolNames = options.EnableToolNames is not null ? new List<string>(options.EnableToolNames) : null;
+        this.IsFireAndForget = options.IsFireAndForget;
+    }
+
     /// <summary>
     /// Gets or sets whether to enable tool calls for this request.
     /// </summary>
@@ -19,11 +36,6 @@ public sealed class DurableAgentRunOptions : AgentRunOptions
     /// </summary>
     public IList<string>? EnableToolNames { get; set; }
 
-    /// <summary>
-    /// Gets or sets the response format for the agent's response.
-    /// </summary>
-    public ChatResponseFormat? ResponseFormat { get; set; }
-
     /// <summary>
     /// Gets or sets whether to fire and forget the agent run request.
     /// </summary>
@@ -33,4 +45,7 @@ public sealed class DurableAgentRunOptions : AgentRunOptions
     /// long-running tasks where the caller does not need to wait for the agent to complete the run.
     /// </remarks>
     public bool IsFireAndForget { get; set; }
+
+    /// <inheritdoc/>
+    public override AgentRunOptions Clone() => new DurableAgentRunOptions(this);
 }

dotnet/src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj

@@ -4,8 +4,7 @@
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <!-- CA2007: This rule should generally be suppressed in Durable Task libraries -->
-    <!-- MEAI001: UserInputRequestContent is experimental but used in source-generated code for AgentResponse -->
-    <NoWarn>$(NoWarn);CA2007;MEAI001</NoWarn>
+    <NoWarn>$(NoWarn);CA2007</NoWarn>
   </PropertyGroup>
 
   <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
@@ -17,6 +16,11 @@
     <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectSharedStructuredOutput>true</InjectSharedStructuredOutput>
+  </PropertyGroup>
+  
   <!-- Durable Task dependencies -->
   <ItemGroup>
     <PackageReference Include="Microsoft.DurableTask.Client" />

dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs

@@ -104,7 +104,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
 
         if (session is not GitHubCopilotAgentSession typedSession)
         {
-            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be serialized.");
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(GitHubCopilotAgentSession)}' can be serialized by this agent.");
         }
 
         return new(typedSession.Serialize(jsonSerializerOptions));
@@ -139,7 +139,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable
         if (session is not GitHubCopilotAgentSession typedSession)
         {
             throw new InvalidOperationException(
-                $"The provided session type {session.GetType()} is not compatible with the agent. Only GitHub Copilot agent created sessions are supported.");
+                $"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(GitHubCopilotAgentSession)}' can be used by this agent.");
         }
 
         // Ensure the client is started

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
-    <NoWarn>$(NoWarn);OPENAI001;MEAI001</NoWarn>
+    <NoWarn>$(NoWarn);MEAI001</NoWarn>
     <RootNamespace>Microsoft.Agents.AI.Hosting.OpenAI</RootNamespace>
     <VersionSuffix>alpha</VersionSuffix>
     <InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.Http.Generated</InterceptorsNamespaces>