Update GitHub.Copilot.SDK to 0.1.25 and use Clone() to replace custom SessionConfig copying

Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>

.github/workflows/dotnet-build-and-test.yml

@@ -7,6 +7,13 @@ name: dotnet-build-and-test
 
 on:
   workflow_dispatch:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., a commit SHA from a PR)"
+        required: false
+        type: string
+        default: ""
   pull_request:
     branches: ["main", "feature*"]
   merge_group:
@@ -39,6 +46,8 @@ jobs:
       cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
       - uses: dorny/paths-filter@v3
         id: filter
         with:
@@ -76,6 +85,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
+            ref: ${{ inputs.checkout-ref }}
             persist-credentials: false
             sparse-checkout: |
               .

.github/workflows/integration-tests-manual.yml

@@ -0,0 +1,106 @@
+#
+# This workflow allows manually running integration tests against an open PR or a branch.
+# Go to Actions → "Integration Tests (Manual)" → Run workflow → enter a PR number or branch name.
+#
+# It reuses the existing dotnet-build-and-test and python-merge-tests workflows,
+# passing a ref so they check out and test the correct code.
+#
+
+name: Integration Tests (Manual)
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr-number:
+        description: "PR number to run integration tests against (leave empty if using branch)"
+        required: false
+        type: string
+        default: ""
+      branch:
+        description: "Branch name to run integration tests against (leave empty if using PR number)"
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+  pull-requests: read
+  id-token: write
+
+concurrency:
+  group: integration-tests-manual-${{ github.event.inputs.pr-number || github.event.inputs.branch }}
+  cancel-in-progress: true
+
+jobs:
+  resolve-ref:
+    name: Resolve ref
+    runs-on: ubuntu-latest
+    outputs:
+      checkout-ref: ${{ steps.resolve.outputs.checkout-ref }}
+    steps:
+      - name: Resolve checkout ref
+        id: resolve
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.inputs.pr-number }}
+          BRANCH: ${{ github.event.inputs.branch }}
+          REPO: ${{ github.repository }}
+          REPO_OWNER: ${{ github.repository_owner }}
+        run: |
+          if [ -n "$PR_NUMBER" ] && [ -n "$BRANCH" ]; then
+            echo "::error::Please provide either a PR number or a branch name, not both."
+            exit 1
+          fi
+
+          if [ -z "$PR_NUMBER" ] && [ -z "$BRANCH" ]; then
+            echo "::error::Please provide either a PR number or a branch name."
+            exit 1
+          fi
+
+          if [ -n "$PR_NUMBER" ]; then
+            if ! echo "$PR_NUMBER" | grep -Eq '^[0-9]+$'; then
+              echo "::error::Invalid PR number. Only numeric values are allowed."
+              exit 1
+            fi
+
+            PR_DATA=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json state,headRepository,headRepositoryOwner)
+            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
+            HEAD_OWNER=$(echo "$PR_DATA" | jq -r '.headRepositoryOwner.login')
+
+            if [ "$PR_STATE" != "OPEN" ]; then
+              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
+              exit 1
+            fi
+
+            if [ "$HEAD_OWNER" != "$REPO_OWNER" ]; then
+              echo "::error::PR #$PR_NUMBER is from a fork ($HEAD_OWNER). Running integration tests against fork PRs is not allowed for security reasons."
+              exit 1
+            fi
+
+            echo "checkout-ref=refs/pull/$PR_NUMBER/head" >> "$GITHUB_OUTPUT"
+            echo "Running integration tests for PR #$PR_NUMBER"
+          else
+            if ! echo "$BRANCH" | grep -Eq '^[a-zA-Z0-9_./-]+$'; then
+              echo "::error::Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes are allowed."
+              exit 1
+            fi
+
+            echo "checkout-ref=$BRANCH" >> "$GITHUB_OUTPUT"
+            echo "Running integration tests for branch $BRANCH"
+          fi
+
+  dotnet-integration-tests:
+    name: .NET Integration Tests
+    needs: resolve-ref
+    uses: ./.github/workflows/dotnet-build-and-test.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit
+
+  python-integration-tests:
+    name: Python Integration Tests
+    needs: resolve-ref
+    uses: ./.github/workflows/python-merge-tests.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit

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

@@ -1,10 +1,13 @@
 #!/usr/bin/env python3
 # Copyright (c) Microsoft. All rights reserved.
-"""Check Python test coverage against threshold for enforced modules.
+"""Check Python test coverage against threshold for enforced targets.
 
 This script parses a Cobertura XML coverage report and enforces a minimum
-coverage threshold on specific modules. Non-enforced modules are reported
-for visibility but don't block the build.
+coverage threshold on specific targets. Targets can be package names
+(e.g., "packages.core.agent_framework") or individual Python file paths
+(e.g., "packages/core/agent_framework/observability.py").
+
+Non-enforced targets are reported for visibility but don't block the build.
 
 Usage:
     python python-check-coverage.py <coverage-xml-path> <threshold>
@@ -18,22 +21,31 @@ import xml.etree.ElementTree as ET
 from dataclasses import dataclass
 
 # =============================================================================
-# ENFORCED MODULES CONFIGURATION
+# ENFORCED TARGETS CONFIGURATION
 # =============================================================================
-# Add or remove modules from this set to control which packages must meet
-# the coverage threshold. Only these modules will fail the build if below
-# threshold. Other modules are reported for visibility only.
+# Add or remove entries from this set to control which targets must meet
+# the coverage threshold. Only these targets will fail the build if below
+# threshold. Other targets are reported for visibility only.
 #
-# Module paths should match the package paths as they appear in the coverage
-# report (e.g., "packages.azure-ai.agent_framework_azure_ai" for packages/azure-ai).
-# Sub-modules can be included by specifying their full path.
+# Target values can be:
+# - Package paths as they appear in the coverage report
+#   (e.g., "packages.azure-ai.agent_framework_azure_ai")
+# - Python source file paths as they appear in the coverage report
+#   (e.g., "packages/core/agent_framework/observability.py")
 # =============================================================================
-ENFORCED_MODULES: set[str] = {
+ENFORCED_TARGETS: set[str] = {
+    # Packages
     "packages.azure-ai.agent_framework_azure_ai",
-    # Add more modules here as coverage improves:
-    # "packages.core.agent_framework",
-    # "packages.core.agent_framework._workflows",
-    # "packages.anthropic.agent_framework_anthropic",
+    "packages.core.agent_framework",
+    "packages.core.agent_framework._workflows",
+    "packages.purview.agent_framework_purview",
+    "packages.anthropic.agent_framework_anthropic",
+    "packages.azure-ai-search.agent_framework_azure_ai_search",
+    "packages.core.agent_framework.azure",
+    "packages.core.agent_framework.openai",
+    # Individual files (if you want to enforce specific files instead of whole packages)
+    "packages/core/agent_framework/observability.py",
+    # Add more targets here as coverage improves
 }
 
 
@@ -60,14 +72,21 @@ class PackageCoverage:
         return self.branch_rate * 100
 
 
-def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float, float]:
+def normalize_coverage_path(path: str) -> str:
+    """Normalize coverage paths for reliable matching."""
+    return path.replace("\\", "/").lstrip("./")
+
+
+def parse_coverage_xml(
+    xml_path: str,
+) -> tuple[dict[str, PackageCoverage], dict[str, PackageCoverage], float, float]:
     """Parse Cobertura XML and extract per-package coverage data.
 
     Args:
         xml_path: Path to the Cobertura XML coverage report.
 
     Returns:
-        A tuple of (packages_dict, overall_line_rate, overall_branch_rate).
+        A tuple of (packages_dict, files_dict, overall_line_rate, overall_branch_rate).
     """
     tree = ET.parse(xml_path)
     root = tree.getroot()
@@ -77,6 +96,7 @@ def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float
     overall_branch_rate = float(root.get("branch-rate", 0))
 
     packages: dict[str, PackageCoverage] = {}
+    file_stats: dict[str, dict[str, int]] = {}
 
     for package in root.findall(".//package"):
         package_path = package.get("name", "unknown")
@@ -91,19 +111,43 @@ def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float
         branches_covered = 0
 
         for class_elem in package.findall(".//class"):
+            file_path = normalize_coverage_path(class_elem.get("filename", ""))
+            if file_path and file_path not in file_stats:
+                file_stats[file_path] = {
+                    "lines_valid": 0,
+                    "lines_covered": 0,
+                    "branches_valid": 0,
+                    "branches_covered": 0,
+                }
+
             for line in class_elem.findall(".//line"):
                 lines_valid += 1
                 if int(line.get("hits", 0)) > 0:
                     lines_covered += 1
+
+                if file_path:
+                    file_stats[file_path]["lines_valid"] += 1
+                    if int(line.get("hits", 0)) > 0:
+                        file_stats[file_path]["lines_covered"] += 1
+
                 # Branch coverage from line elements
                 if line.get("branch") == "true":
                     condition_coverage = line.get("condition-coverage", "")
                     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])
+                            if file_path:
+                                file_stats[file_path]["branches_covered"] += int(
+                                    coverage_parts[0]
+                                )
+                                file_stats[file_path]["branches_valid"] += int(
+                                    coverage_parts[1]
+                                )
                         except (IndexError, ValueError):
                             # Ignore malformed condition-coverage strings; treat this line as having no branch data.
                             pass
@@ -112,14 +156,33 @@ 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,
             branches_covered=branches_covered,
         )
 
-    return packages, overall_line_rate, overall_branch_rate
+    files: dict[str, PackageCoverage] = {}
+    for file_path, stats in file_stats.items():
+        lines_valid = stats["lines_valid"]
+        lines_covered = stats["lines_covered"]
+        branches_valid = stats["branches_valid"]
+        branches_covered = stats["branches_covered"]
+
+        files[file_path] = PackageCoverage(
+            name=file_path,
+            line_rate=0 if lines_valid == 0 else lines_covered / lines_valid,
+            branch_rate=0 if branches_valid == 0 else branches_covered / branches_valid,
+            lines_valid=lines_valid,
+            lines_covered=lines_covered,
+            branches_valid=branches_valid,
+            branches_covered=branches_covered,
+        )
+
+    return packages, files, overall_line_rate, overall_branch_rate
 
 
 def format_coverage_value(coverage: float, threshold: float, is_enforced: bool) -> str:
@@ -128,7 +191,7 @@ def format_coverage_value(coverage: float, threshold: float, is_enforced: bool)
     Args:
         coverage: Coverage percentage (0-100).
         threshold: Minimum required coverage percentage.
-        is_enforced: Whether this module is enforced.
+        is_enforced: Whether this target is enforced.
 
     Returns:
         Formatted string like "85.5%" or "85.5% ✅" or "75.0% ❌".
@@ -142,6 +205,7 @@ def format_coverage_value(coverage: float, threshold: float, is_enforced: bool)
 
 def print_coverage_table(
     packages: dict[str, PackageCoverage],
+    files: dict[str, PackageCoverage],
     threshold: float,
     overall_line_rate: float,
     overall_branch_rate: float,
@@ -150,6 +214,7 @@ def print_coverage_table(
 
     Args:
         packages: Dictionary of package name to coverage data.
+        files: Dictionary of file path to coverage data, used for per-file enforcement.
         threshold: Minimum required coverage percentage.
         overall_line_rate: Overall line coverage rate (0-1).
         overall_branch_rate: Overall branch coverage rate (0-1).
@@ -163,21 +228,25 @@ def print_coverage_table(
     print(f"Overall Branch Coverage: {overall_branch_rate * 100:.1f}%")
     print(f"Threshold:               {threshold}%")
 
+    enforced_targets = {normalize_coverage_path(t) for t in ENFORCED_TARGETS}
+
     # Package table
     print("\n" + "-" * 110)
     print(f"{'Package':<80} {'Lines':<15} {'Line Cov':<15}")
     print("-" * 110)
 
-    # Sort: enforced modules first, then alphabetically
+    # Sort: enforced package targets first, then alphabetically
     sorted_packages = sorted(
         packages.values(),
-        key=lambda p: (p.name not in ENFORCED_MODULES, p.name),
+        key=lambda p: (p.name not in ENFORCED_TARGETS, p.name),
     )
 
     for pkg in sorted_packages:
-        is_enforced = pkg.name in ENFORCED_MODULES
+        is_enforced = normalize_coverage_path(pkg.name) in enforced_targets
         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}"
 
@@ -185,50 +254,98 @@ def print_coverage_table(
 
     print("-" * 110)
 
+    # Enforced file/model entries (if configured)
+    enforced_files = [
+        files[target]
+        for target in sorted(enforced_targets)
+        if target in files and target.endswith(".py")
+    ]
+
+    if enforced_files:
+        print("\nEnforced Files/Models")
+        print("-" * 110)
+        print(f"{'File':<80} {'Lines':<15} {'Line Cov':<15}")
+        print("-" * 110)
+
+        for file_cov in enforced_files:
+            line_cov = format_coverage_value(
+                file_cov.line_coverage_percent, threshold, True
+            )
+            lines_info = f"{file_cov.lines_covered}/{file_cov.lines_valid}"
+            print(f"[ENFORCED] {file_cov.name:<69} {lines_info:<15} {line_cov:<15}")
+
+        print("-" * 110)
+
 
 def check_coverage(xml_path: str, threshold: float) -> bool:
-    """Check if all enforced modules meet the coverage threshold.
+    """Check if all enforced targets meet the coverage threshold.
 
     Args:
         xml_path: Path to the Cobertura XML coverage report.
         threshold: Minimum required coverage percentage.
 
     Returns:
-        True if all enforced modules pass, False otherwise.
+        True if all enforced targets pass, False otherwise.
     """
-    packages, overall_line_rate, overall_branch_rate = parse_coverage_xml(xml_path)
+    packages, files, overall_line_rate, overall_branch_rate = parse_coverage_xml(
+        xml_path
+    )
 
-    print_coverage_table(packages, threshold, overall_line_rate, overall_branch_rate)
+    print_coverage_table(
+        packages, files, threshold, overall_line_rate, overall_branch_rate
+    )
 
-    # Check enforced modules
-    failed_modules: list[str] = []
-    missing_modules: list[str] = []
+    # Check enforced targets
+    failed_targets: list[str] = []
+    missing_targets: list[str] = []
 
-    for module_name in ENFORCED_MODULES:
-        if module_name not in packages:
-            missing_modules.append(module_name)
+    for target_name in ENFORCED_TARGETS:
+        normalized_target = normalize_coverage_path(target_name)
+        package_alias = normalized_target.replace("/", ".")
+
+        target_coverage = None
+        if target_name in packages:
+            target_coverage = packages[target_name]
+        elif normalized_target in files:
+            target_coverage = files[normalized_target]
+        elif package_alias in packages:
+            target_coverage = packages[package_alias]
+
+        if target_coverage is None:
+            missing_targets.append(target_name)
             continue
 
-        pkg = packages[module_name]
-        if pkg.line_coverage_percent < threshold:
-            failed_modules.append(f"{module_name} ({pkg.line_coverage_percent:.1f}%)")
+        if target_coverage.line_coverage_percent < threshold:
+            failed_targets.append(
+                f"{target_name} ({target_coverage.line_coverage_percent:.1f}%)"
+            )
 
     # Report results
-    if missing_modules:
-        print(f"\n❌ FAILED: Enforced modules not found in coverage report: {', '.join(missing_modules)}")
+    if missing_targets:
+        print(
+            f"\n❌ FAILED: Enforced targets not found in coverage report: {', '.join(missing_targets)}"
+        )
         return False
 
-    if failed_modules:
-        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.")
+    if failed_targets:
+        print(
+            f"\n❌ FAILED: The following enforced targets are below {threshold}% coverage threshold:"
+        )
+        for target in failed_targets:
+            print(f"   - {target}")
+        print("\nTo fix: Add more tests to improve coverage for the failing targets.")
         return False
 
-    if ENFORCED_MODULES:
-        found_enforced = [m for m in ENFORCED_MODULES if m in packages]
+    if ENFORCED_TARGETS:
+        found_enforced = [
+            target
+            for target in ENFORCED_TARGETS
+            if target in packages or normalize_coverage_path(target) in files
+        ]
         if found_enforced:
-            print(f"\n✅ PASSED: All enforced modules meet the {threshold}% coverage threshold.")
+            print(
+                f"\n✅ PASSED: All enforced targets meet the {threshold}% coverage threshold."
+            )
 
     return True
 

.github/workflows/python-merge-tests.yml

@@ -2,6 +2,13 @@ name: Python - Merge - Tests
 
 on:
   workflow_dispatch:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., a commit SHA from a PR)"
+        required: false
+        type: string
+        default: ""
   pull_request:
     branches: ["main"]
   merge_group:
@@ -29,6 +36,8 @@ jobs:
       pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
       - uses: dorny/paths-filter@v3
         id: filter
         with:
@@ -76,6 +85,8 @@ jobs:
         working-directory: python
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup
@@ -135,6 +146,8 @@ jobs:
         working-directory: python
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
       - name: Set up python and install the project
         id: python-setup
         uses: ./.github/actions/python-setup

README.md

@@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 ### ✨ **Highlights**
 
 - **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/getting_started/workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/)
+  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/)
 - **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
   - [Labs directory](./python/packages/lab/)
 - **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
@@ -73,11 +73,11 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 - **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
   - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
 - **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/getting_started/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
+  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
 - **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
-  - [Python examples](./python/samples/getting_started/agents/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/)
+  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/)
 - **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
-  - [Python middleware](./python/samples/getting_started/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
+  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
 
 ### 💬 **We want your feedback!**
 
@@ -125,12 +125,13 @@ Create a simple Agent, using OpenAI Responses, that writes a haiku about the Mic
 
 ```c#
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-using System;
+using Microsoft.Agents.AI;
 using OpenAI;
+using OpenAI.Responses;
 
 // Replace the <apikey> with your OpenAI API key.
 var agent = new OpenAIClient("<apikey>")
-    .GetOpenAIResponseClient("gpt-4o-mini")
+    .GetResponsesClient("gpt-4o-mini")
     .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
@@ -142,14 +143,17 @@ Create a simple Agent, using Azure OpenAI Responses with token based auth, that
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 // dotnet add package Azure.Identity
 // Use `az login` to authenticate with Azure CLI
-using System;
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Microsoft.Agents.AI;
 using OpenAI;
+using OpenAI.Responses;
 
 // Replace <resource> and gpt-4o-mini with your Azure OpenAI resource name and deployment name.
 var agent = new OpenAIClient(
     new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
     new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
-    .GetOpenAIResponseClient("gpt-4o-mini")
+    .GetResponsesClient("gpt-4o-mini")
     .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
@@ -159,9 +163,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 
 ### Python
 
-- [Getting Started with Agents](./python/samples/getting_started/agents): basic agent creation and tool usage
-- [Chat Client Examples](./python/samples/getting_started/chat_client): direct chat client usage patterns
-- [Getting Started with Workflows](./python/samples/getting_started/workflows): basic workflow creation and integration with agents
+- [Getting Started with Agents](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
+- [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.)
+- [Getting Started with Workflows](./python/samples/03-workflows): workflow creation and integration with agents
 
 ### .NET
 

agent-samples/README.md

@@ -1,3 +1,3 @@
 # Declarative Agents
 
-This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/getting_started/declarative/).
+This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/02-agents/declarative/).

docs/decisions/0012-python-typeddict-options.md

@@ -126,4 +126,4 @@ response = await client.get_response(
 
 Chosen option: **"Option 2: TypedDict with Generic Type Parameters"**, because it provides full type safety, excellent IDE support with autocompletion, and allows users to extend provider-specific options for their use cases. Extended this Generic to ChatAgents in order to also properly type the options used in agent construction and run methods.
 
-See [typed_options.py](../../python/samples/concepts/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.
+See [typed_options.py](../../python/samples/02-agents/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.

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,44 +4,32 @@ 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
 
+- **Encoding**: All new files must be saved with UTF-8 encoding with BOM (Byte Order Mark). This is required for `dotnet format` to work correctly.
 - **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
 - **XML docs**: Required for all public methods and classes
 - **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
@@ -49,8 +37,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 +59,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

@@ -33,18 +33,18 @@
     <!-- Newtonsoft.Json -->
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="System.ClientModel" Version="1.8.1" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.2" />
+    <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.Text.Json" Version="10.0.2" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.2" />
+    <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" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
@@ -61,9 +61,12 @@
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.2.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.2.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.2.0-preview.1.26063.2" />
+    <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" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
@@ -71,11 +74,11 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -89,7 +92,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.18" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.25" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.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/README.md

@@ -11,16 +11,16 @@
 ### Basic Agent - .NET
 
 ```c#
-using System;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
+using OpenAI.Responses;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")!;
 
 var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetOpenAIResponseClient(deploymentName)
+    .GetResponsesClient(deploymentName)
     .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));

dotnet/agent-framework-dotnet.slnx

@@ -96,6 +96,10 @@
     <Project Path="samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Agent_Step20_AdditionalAIContext.csproj" />
   </Folder>
+  <Folder Name="/Samples/GettingStarted/AgentSkills/">
+    <File Path="samples/GettingStarted/AgentSkills/README.md" />
+    <Project Path="samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj" />
+  </Folder>
   <Folder Name="/Samples/GettingStarted/DeclarativeAgents/">
     <Project Path="samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
   </Folder>
@@ -138,6 +142,7 @@
     <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
     <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
     <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/AgentWithMemory_Step03_CustomMemory.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
     <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
@@ -176,6 +181,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 +222,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 +381,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 +403,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 +415,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,19 +422,21 @@
     <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" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.FoundryMemory/Microsoft.Agents.AI.FoundryMemory.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <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,11 +446,12 @@
     <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" />
+    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj" />
@@ -443,18 +462,19 @@
     <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" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.UnitTests/Microsoft.Agents.AI.FoundryMemory.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />

dotnet/agent-framework-release.slnf

@@ -25,6 +25,7 @@
       "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
+      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
       "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
       "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.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).260209.1</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260209.1</PackageVersion>
-    <GitTag>1.0.0-preview.260209.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/A2AClientServer/A2AServer/HostAgentFactory.cs

@@ -14,7 +14,10 @@ internal static class HostAgentFactory
 {
     internal static async Task<(AIAgent, AgentCard)> CreateFoundryHostAgentAsync(string agentType, string model, string endpoint, string assistantId, IList<AITool>? tools = null)
     {
-        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+        // 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.
+        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
         PersistentAgent persistentAgent = await persistentAgentsClient.Administration.GetAgentAsync(assistantId);
 
         AIAgent agent = await persistentAgentsClient

dotnet/samples/AGUIClientServer/AGUIDojoServer/ChatClientAgentFactory.cs

@@ -24,6 +24,9 @@ internal static class ChatClientAgentFactory
         string endpoint = configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
         s_deploymentName = configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
+        // 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.
         s_azureOpenAIClient = new AzureOpenAIClient(
             new Uri(endpoint),
             new DefaultAzureCredential());

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/AGUIClientServer/AGUIServer/Program.cs

@@ -19,6 +19,9 @@ string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new In
 string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent with tools
+// 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.
 var agent = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/AGUIWebChat/Server/Program.cs

@@ -19,6 +19,9 @@ string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new In
 string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent
+// 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.
 AzureOpenAIClient azureOpenAIClient = new(
     new Uri(endpoint),
     new DefaultAzureCredential());

dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Program.cs

@@ -70,7 +70,7 @@ var knightsKnavesAgentBuilder = builder.AddAIAgent("knights-and-knaves", (sp, ke
         If the user asks a general question about their surrounding, make something up which is consistent with the scenario.
         """, "Narrator");
 
-    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAgent(name: key);
+    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAIAgent(name: key);
 });
 
 // Workflow consisting of multiple specialized agents

dotnet/samples/Durable/Agents/AzureFunctions/01_SingleAgent/Program.cs

@@ -19,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 const string JokerName = "Joker";

dotnet/samples/Durable/Agents/AzureFunctions/02_AgentOrchestration_Chaining/Program.cs

@@ -19,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate sequential calls on the same session.
 const string WriterName = "WriterAgent";

dotnet/samples/Durable/Agents/AzureFunctions/03_AgentOrchestration_Concurrency/Program.cs

@@ -19,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Two agents used by the orchestration to demonstrate concurrent execution.
 const string PhysicistName = "PhysicistAgent";

dotnet/samples/Durable/Agents/AzureFunctions/04_AgentOrchestration_Conditionals/Program.cs

@@ -19,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Two agents used by the orchestration to demonstrate conditional logic.
 const string SpamDetectionName = "SpamDetectionAgent";

dotnet/samples/Durable/Agents/AzureFunctions/05_AgentOrchestration_HITL/Program.cs

@@ -19,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate human-in-the-loop workflow.
 const string WriterName = "WriterAgent";

dotnet/samples/Durable/Agents/AzureFunctions/06_LongRunningTools/Program.cs

@@ -23,9 +23,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Agent used by the orchestration to write content.
 const string WriterAgentName = "Writer";

dotnet/samples/Durable/Agents/AzureFunctions/07_AgentAsMcpTool/Program.cs

@@ -25,9 +25,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Define three AI agents we are going to use in this application.
 AIAgent agent1 = client.GetChatClient(deploymentName).AsAIAgent("You are good at telling jokes.", "Joker");

dotnet/samples/Durable/Agents/AzureFunctions/08_ReliableStreaming/Program.cs

@@ -40,9 +40,12 @@ int redisStreamTtlMinutes = int.TryParse(
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Travel Planner agent instructions - designed to produce longer responses for demonstrating streaming.
 const string TravelPlannerName = "TravelPlanner";

dotnet/samples/Durable/Agents/ConsoleApps/01_SingleAgent/Program.cs

@@ -25,9 +25,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 const string JokerName = "Joker";

dotnet/samples/Durable/Agents/ConsoleApps/02_AgentOrchestration_Chaining/Program.cs

@@ -29,9 +29,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate sequential calls on the same session.
 const string WriterName = "WriterAgent";

dotnet/samples/Durable/Agents/ConsoleApps/03_AgentOrchestration_Concurrency/Program.cs

@@ -29,9 +29,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Two agents used by the orchestration to demonstrate concurrent execution.
 const string PhysicistName = "PhysicistAgent";

dotnet/samples/Durable/Agents/ConsoleApps/04_AgentOrchestration_Conditionals/Program.cs

@@ -28,9 +28,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Spam detection agent
 const string SpamDetectionAgentName = "SpamDetectionAgent";

dotnet/samples/Durable/Agents/ConsoleApps/05_AgentOrchestration_HITL/Program.cs

@@ -29,9 +29,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate human-in-the-loop workflow.
 const string WriterName = "WriterAgent";

dotnet/samples/Durable/Agents/ConsoleApps/06_LongRunningTools/Program.cs

@@ -30,9 +30,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Agent used by the orchestration to write content.
 const string WriterAgentName = "Writer";

dotnet/samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/Program.cs

@@ -38,9 +38,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// 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.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Travel Planner agent instructions - designed to produce longer responses for demonstrating streaming.
 const string TravelPlannerName = "TravelPlanner";

dotnet/samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/Program.cs

@@ -26,9 +26,12 @@ AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
 AIAgent a2aAgent = agentCard.AsAIAgent();
 
 // Create the main agent, and provide the a2a agent skills as a function tools.
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         instructions: "You are a helpful assistant that helps people with travel planning.",

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Program.cs

@@ -19,6 +19,9 @@ string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
     ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent
+// 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.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Server/Program.cs

@@ -74,6 +74,9 @@ AITool[] tools =
 ];
 
 // Create the AI agent with tools
+// 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.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Program.cs

@@ -19,6 +19,9 @@ string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
     ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent
+// 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.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Program.cs

@@ -52,6 +52,9 @@ AITool[] tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(Approv
 #pragma warning restore MEAI001
 
 // Create base agent
+// 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.
 ChatClient openAIChatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

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

@@ -29,6 +29,9 @@ string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
 var jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;
 
 // Create base agent
+// 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.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

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/AgentOpenTelemetry/Program.cs

@@ -110,7 +110,10 @@ static async Task<string> GetWeatherAsync([Description("The location to get the
     return $"The weather in {location} is cloudy with a high of 15°C.";
 }
 
-using var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// 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.
+using var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName)
         .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
         .AsBuilder()

dotnet/samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Program.cs

@@ -17,11 +17,14 @@ string? apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY");
 const string JokerInstructions = "You are good at telling jokes.";
 const string JokerName = "JokerAgent";
 
+// 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.
 using AnthropicClient client = (resource is null)
     ? new AnthropicClient() { ApiKey = apiKey ?? throw new InvalidOperationException("ANTHROPIC_API_KEY is required when no ANTHROPIC_RESOURCE is provided") }  // If no resource is provided, use Anthropic public API
     : (apiKey is not null)
         ? new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(apiKey, resource)) // If an apiKey is provided, use Foundry with ApiKey authentication
-        : new AnthropicFoundryClient(new AnthropicFoundryIdentityTokenCredentials(new AzureCliCredential(), resource, ["https://ai.azure.com/.default"])); // Otherwise, use Foundry with Azure TokenCredential authentication
+        : new AnthropicFoundryClient(new AnthropicFoundryIdentityTokenCredentials(new DefaultAzureCredential(), resource, ["https://ai.azure.com/.default"])); // Otherwise, use Foundry with Azure TokenCredential authentication
 
 AIAgent agent = client.AsAIAgent(model: deploymentName, instructions: JokerInstructions, name: JokerName);
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/Program.cs

@@ -13,7 +13,10 @@ const string JokerName = "Joker";
 const string JokerInstructions = "You are good at telling jokes.";
 
 // Get a client to create/retrieve server side agents with.
-var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+// 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.
+var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
 
 // You can create a server side persistent agent with the Azure.AI.Agents.Persistent SDK.
 var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Program.cs

@@ -13,7 +13,10 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_D
 const string JokerName = "JokerAgent";
 
 // Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-var aiProjectClient = new AIProjectClient(new Uri(endpoint), new AzureCliCredential());
+// 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.
+var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Define the agent you want to create. (Prompt Agent in this case)
 var agentVersionCreationOptions = new AgentVersionCreationOptions(new PromptAgentDefinition(model: deploymentName) { Instructions = "You are good at telling jokes." });

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Program.cs

@@ -19,8 +19,11 @@ var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_MODEL_DEPLOYMENT")
 var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(endpoint) };
 
 // Create the OpenAI client with either an API key or Azure CLI credential.
+// 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.
 OpenAIClient client = string.IsNullOrWhiteSpace(apiKey)
-    ? new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions)
+    ? new OpenAIClient(new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), clientOptions)
     : new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);
 
 AIAgent agent = client

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Program.cs

@@ -10,9 +10,12 @@ using OpenAI.Chat;
 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";
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetChatClient(deploymentName)
      .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Program.cs

@@ -10,9 +10,12 @@ 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";
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetResponsesClient(deploymentName)
      .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Program.cs

@@ -6,6 +6,7 @@
 
 using System.Runtime.CompilerServices;
 using System.Text.Json;
+using System.Text.Json.Serialization;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using SampleApp;
@@ -28,21 +29,23 @@ namespace SampleApp
     {
         public override string? Name => "UpperCaseParrotAgent";
 
+        public readonly ChatHistoryProvider ChatHistoryProvider = new InMemoryChatHistoryProvider();
+
         protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
             => new(new CustomAgentSession());
 
-        protected override JsonElement SerializeSessionCore(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null)
+        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
         {
             if (session is not CustomAgentSession typedSession)
             {
                 throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
             }
 
-            return typedSession.Serialize(jsonSerializerOptions);
+            return new(JsonSerializer.SerializeToElement(typedSession, jsonSerializerOptions));
         }
 
         protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
-            => new(new CustomAgentSession(serializedState, jsonSerializerOptions));
+            => new(serializedState.Deserialize<CustomAgentSession>(jsonSerializerOptions)!);
 
         protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
         {
@@ -56,17 +59,14 @@ namespace SampleApp
 
             // Get existing messages from the store
             var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
-            var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
+            var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
 
             // Clone the input messages and turn them into response messages with upper case text.
             List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
 
             // Notify the session of the input and output messages.
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, messages)
-            {
-                ResponseMessages = responseMessages
-            };
-            await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
+            await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
 
             return new AgentResponse
             {
@@ -88,17 +88,14 @@ namespace SampleApp
 
             // Get existing messages from the store
             var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
-            var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
+            var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
 
             // Clone the input messages and turn them into response messages with upper case text.
             List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
 
             // Notify the session of the input and output messages.
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, messages)
-            {
-                ResponseMessages = responseMessages
-            };
-            await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
+            await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
 
             foreach (var message in responseMessages)
             {
@@ -140,15 +137,16 @@ namespace SampleApp
         /// <summary>
         /// A session type for our custom agent that only supports in memory storage of messages.
         /// </summary>
-        internal sealed class CustomAgentSession : InMemoryAgentSession
+        internal sealed class CustomAgentSession : AgentSession
         {
-            internal CustomAgentSession() { }
+            internal CustomAgentSession()
+            {
+            }
 
-            internal CustomAgentSession(JsonElement serializedSessionState, JsonSerializerOptions? jsonSerializerOptions = null)
-                : base(serializedSessionState, jsonSerializerOptions) { }
-
-            internal new JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
-                => base.Serialize(jsonSerializerOptions);
+            [JsonConstructor]
+            internal CustomAgentSession(AgentSessionStateBag stateBag) : base(stateBag)
+            {
+            }
         }
     }
 }

dotnet/samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj

@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+  <!-- Copy skills directory to output -->
+  <ItemGroup>
+    <None Include="skills\**\*.*">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/Program.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Agent Skills with a ChatClientAgent.
+// Agent Skills are modular packages of instructions and resources that extend an agent's capabilities.
+// Skills follow the progressive disclosure pattern: advertise -> load -> read resources.
+//
+// This sample includes the expense-report skill:
+//   - Policy-based expense filing with references and assets
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+// --- Configuration ---
+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";
+
+// --- Skills Provider ---
+// Discovers skills from the 'skills' directory and makes them available to the agent
+var skillsProvider = new FileAgentSkillsProvider(skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
+
+// --- Agent Setup ---
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetResponsesClient(deploymentName)
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "SkillsAgent",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant.",
+        },
+        AIContextProviders = [skillsProvider],
+    });
+
+// --- Example 1: Expense policy question (loads FAQ resource) ---
+Console.WriteLine("Example 1: Checking expense policy FAQ");
+Console.WriteLine("---------------------------------------");
+AgentResponse response1 = await agent.RunAsync("Are tips reimbursable? I left a 25% tip on a taxi ride and want to know if that's covered.");
+Console.WriteLine($"Agent: {response1.Text}\n");
+
+// --- Example 2: Filing an expense report (multi-turn with template asset) ---
+Console.WriteLine("Example 2: Filing an expense report");
+Console.WriteLine("---------------------------------------");
+AgentSession session = await agent.CreateSessionAsync();
+AgentResponse response2 = await agent.RunAsync("I had 3 client dinners and a $1,200 flight last week. Return a draft expense report and ask about any missing details.",
+    session);
+Console.WriteLine($"Agent: {response2.Text}\n");

dotnet/samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/README.md

@@ -0,0 +1,63 @@
+# Agent Skills Sample
+
+This sample demonstrates how to use **Agent Skills** with a `ChatClientAgent` in the Microsoft Agent Framework.
+
+## What are Agent Skills?
+
+Agent Skills are modular packages of instructions and resources that enable AI agents to perform specialized tasks. They follow the [Agent Skills specification](https://agentskills.io/) and implement the progressive disclosure pattern:
+
+1. **Advertise**: Skills are advertised with name + description (~100 tokens per skill)
+2. **Load**: Full instructions are loaded on-demand via `load_skill` tool
+3. **Resources**: References and other files loaded via `read_skill_resource` tool
+
+## Skills Included
+
+### expense-report
+Policy-based expense filing with spending limits, receipt requirements, and approval workflows.
+- `references/POLICY_FAQ.md` — Detailed expense policy Q&A
+- `assets/expense-report-template.md` — Submission template
+
+## Project Structure
+
+```
+Agent_Step01_BasicSkills/
+├── Program.cs
+├── Agent_Step01_BasicSkills.csproj
+└── skills/
+    └── expense-report/
+        ├── SKILL.md
+        ├── references/
+        │   └── POLICY_FAQ.md
+        └── assets/
+            └── expense-report-template.md
+```
+
+## Running the Sample
+
+### Prerequisites
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model
+
+### Setup
+1. Set environment variables:
+   ```bash
+   export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+   export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+   ```
+
+2. Run the sample:
+   ```bash
+   dotnet run
+   ```
+
+### Examples
+
+The sample runs two examples:
+
+1. **Expense policy FAQ** — Asks about tip reimbursement; the agent loads the expense-report skill and reads the FAQ resource
+2. **Filing an expense report** — Multi-turn conversation to draft an expense report using the template asset
+
+## Learn More
+
+- [Agent Skills Specification](https://agentskills.io/)
+- [Microsoft Agent Framework Documentation](../../../../../docs/)

dotnet/samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: expense-report
+description: File and validate employee expense reports according to Contoso company policy. Use when asked about expense submissions, reimbursement rules, receipt requirements, spending limits, or expense categories.
+metadata:
+  author: contoso-finance
+  version: "2.1"
+---
+
+# Expense Report
+
+## Categories and Limits
+
+| Category | Limit | Receipt | Approval |
+|---|---|---|---|
+| Meals — solo | $50/day | >$25 | No |
+| Meals — team/client | $75/person | Always | Manager if >$200 total |
+| Lodging | $250/night | Always | Manager if >3 nights |
+| Ground transport | $100/day | >$15 | No |
+| Airfare | Economy | Always | Manager; VP if >$1,500 |
+| Conference/training | $2,000/event | Always | Manager + L&D |
+| Office supplies | $100 | Yes | No |
+| Software/subscriptions | $50/month | Yes | Manager if >$200/year |
+
+## Filing Process
+
+1. Collect receipts — must show vendor, date, amount, payment method.
+2. Categorize per table above.
+3. Use template: [assets/expense-report-template.md](assets/expense-report-template.md).
+4. For client/team meals: list attendee names and business purpose.
+5. Submit — auto-approved if <$500; manager if $500–$2,000; VP if >$2,000.
+6. Reimbursement: 10 business days via direct deposit.
+
+## Policy Rules
+
+- Submit within 30 days of transaction.
+- Alcohol is never reimbursable.
+- Foreign currency: convert to USD at transaction-date rate; note original currency and amount.
+- Mixed personal/business travel: only business portion reimbursable; provide comparison quotes.
+- Lost receipts (>$25): file Lost Receipt Affidavit from Finance. Max 2 per quarter.
+- For policy questions not covered above, consult the FAQ: [references/POLICY_FAQ.md](references/POLICY_FAQ.md). Answers should be based on what this document and the FAQ state.

dotnet/samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/assets/expense-report-template.md

@@ -0,0 +1,5 @@
+# Expense Report Template
+
+| Date | Category | Vendor | Description | Amount (USD) | Original Currency | Original Amount | Attendees | Business Purpose | Receipt Attached |
+|------|----------|--------|-------------|--------------|-------------------|-----------------|-----------|------------------|------------------|
+|      |          |        |             |              |                   |                 |           |                  | Yes or No        |

dotnet/samples/GettingStarted/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/references/POLICY_FAQ.md

@@ -0,0 +1,55 @@
+# Expense Policy — Frequently Asked Questions
+
+## Meals
+
+**Q: Can I expense coffee or snacks during the workday?**
+A: Daily coffee/snacks under $10 are not reimbursable (considered personal). Coffee purchased during a client meeting or team working session is reimbursable as a team meal.
+
+**Q: What if a team dinner exceeds the per-person limit?**
+A: The $75/person limit applies as a guideline. Overages up to 20% are accepted with a written justification (e.g., "client dinner at venue chosen by client"). Overages beyond 20% require pre-approval from your VP.
+
+**Q: Do I need to list every attendee?**
+A: Yes. For client meals, list the client's name and company. For team meals, list all employee names. For groups over 10, you may attach a separate attendee list.
+
+## Travel
+
+**Q: Can I book a premium economy or business class flight?**
+A: Economy class is the standard. Premium economy is allowed for flights over 6 hours. Business class requires VP pre-approval and is generally reserved for flights over 10 hours or medical accommodation.
+
+**Q: What about ride-sharing (Uber/Lyft) vs. rental cars?**
+A: Use ride-sharing for trips under 30 miles round-trip. Rent a car for multi-day travel or when ride-sharing would exceed $100/day. Always choose the compact/standard category unless traveling with 3+ people.
+
+**Q: Are tips reimbursable?**
+A: Tips up to 20% are reimbursable for meals, taxi/ride-share, and hotel housekeeping. Tips above 20% require justification.
+
+## Lodging
+
+**Q: What if the $250/night limit isn't enough for the city I'm visiting?**
+A: For high-cost cities (New York, San Francisco, London, Tokyo, Sydney), the limit is automatically increased to $350/night. No additional approval is needed. For other locations where rates are unusually high (e.g., during a major conference), request a per-trip exception from your manager before booking.
+
+**Q: Can I stay with friends/family instead and get a per-diem?**
+A: No. Contoso reimburses actual lodging costs only, not per-diems.
+
+## Subscriptions and Software
+
+**Q: Can I expense a personal productivity tool?**
+A: Software must be directly related to your job function. Tools like IDE licenses, design software, or project management apps are reimbursable. General productivity apps (note-taking, personal calendar) are not, unless your manager confirms a business need in writing.
+
+**Q: What about annual subscriptions?**
+A: Annual subscriptions over $200 require manager approval before purchase. Submit the approval email with your expense report.
+
+## Receipts and Documentation
+
+**Q: My receipt is faded/damaged. What do I do?**
+A: Try to obtain a duplicate from the vendor. If not possible, submit a Lost Receipt Affidavit (available from the Finance SharePoint site). You're limited to 2 affidavits per quarter.
+
+**Q: Do I need a receipt for parking meters or tolls?**
+A: For amounts under $15, no receipt is required — just note the date, location, and amount. For $15 and above, a receipt or bank/credit card statement excerpt is required.
+
+## Approval and Reimbursement
+
+**Q: My manager is on leave. Who approves my report?**
+A: Expense reports can be approved by your skip-level manager or any manager designated as an alternate approver in the expense system.
+
+**Q: Can I submit expenses from a previous quarter?**
+A: The standard 30-day window applies. Expenses older than 30 days require a written explanation and VP approval. Expenses older than 90 days are not reimbursable except in extraordinary circumstances (extended leave, medical emergency) with CFO approval.

dotnet/samples/GettingStarted/AgentSkills/README.md

@@ -0,0 +1,7 @@
+# AgentSkills Samples
+
+Samples demonstrating Agent Skills capabilities.
+
+| Sample | Description |
+|--------|-------------|
+| [Agent_Step01_BasicSkills](Agent_Step01_BasicSkills/) | Using Agent Skills with a ChatClientAgent, including progressive disclosure and skill resources |

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

@@ -20,7 +20,10 @@ var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_E
 // Replace this with a vector store implementation of your choice that can persist the chat history long term.
 VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions()
 {
-    EmbeddingGenerator = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+    // 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.
+    EmbeddingGenerator = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
         .GetEmbeddingClient(embeddingDeploymentName)
         .AsIEmbeddingGenerator()
 });
@@ -28,22 +31,27 @@ VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions
 // Create the agent and add the ChatHistoryMemoryProvider to store chat messages in the vector store.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new ChatHistoryMemoryProvider(
+        AIContextProviders = [new ChatHistoryMemoryProvider(
             vectorStore,
             collectionName: "chathistory",
             vectorDimensions: 3072,
-            // Configure the scope values under which chat messages will be stored.
-            // In this case, we are using a fixed user ID and a unique session ID for each new session.
-            storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
-            // Configure the scope which would be used to search for relevant prior messages.
-            // In this case, we are searching for any messages for the user across all sessions.
-            searchScope: new() { UserId = "UID1" }))
+            // Callback to configure the initial state of the ChatHistoryMemoryProvider.
+            // The ChatHistoryMemoryProvider stores its state in the AgentSession and this callback
+            // will be called whenever the ChatHistoryMemoryProvider cannot find existing state in the session,
+            // typically the first time it is used with a new session.
+            session => new ChatHistoryMemoryProvider.State(
+                // Configure the scope values under which chat messages will be stored.
+                // In this case, we are using a fixed user ID and a unique session ID for each new session.
+                storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
+                // Configure the scope which would be used to search for relevant prior messages.
+                // In this case, we are searching for any messages for the user across all sessions.
+                searchScope: new() { UserId = "UID1" }))]
     });
 
 // Start a new session for the agent conversation.

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

@@ -24,27 +24,31 @@ using HttpClient mem0HttpClient = new();
 mem0HttpClient.BaseAddress = new Uri(mem0ServiceUri);
 mem0HttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", mem0ApiKey);
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions()
     {
         ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(ctx.SerializedState.ValueKind is not JsonValueKind.Null and not JsonValueKind.Undefined
-            // If each session should have its own Mem0 scope, you can create a new id per session here:
-            // ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() })
-            // In this case we are storing memories scoped by application and user instead so that memories are retained across threads.
-            ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" })
-            // For cases where we are restoring from serialized state:
-            : new Mem0Provider(mem0HttpClient, ctx.SerializedState, ctx.JsonSerializerOptions))
+        // The stateInitializer can be used to customize the Mem0 scope per session and it will be called each time a session
+        // is encountered by the Mem0Provider that does not already have Mem0Provider state stored on the session.
+        // If each session should have its own Mem0 scope, you can create a new id per session via the stateInitializer, e.g.:
+        // new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() }))
+        // In our case we are storing memories scoped by application and user instead so that memories are retained across threads.
+        AIContextProviders = [new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" }))]
     });
 
 AgentSession session = await agent.CreateSessionAsync();
 
 // Clear any existing memories for this scope to demonstrate fresh behavior.
-Mem0Provider mem0Provider = session.GetService<Mem0Provider>()!;
-await mem0Provider.ClearStoredMemoriesAsync();
+// Note that the ClearStoredMemoriesAsync method will clear memories
+// using the scope stored in the session, or provided via the stateInitializer.
+Mem0Provider mem0Provider = agent.GetService<Mem0Provider>()!;
+await mem0Provider.ClearStoredMemoriesAsync(session);
 
 Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
 Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
@@ -55,7 +59,7 @@ await Task.Delay(TimeSpan.FromSeconds(2));
 Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
 
 Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
-JsonElement serializedSession = agent.SerializeSession(session);
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
 Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
 

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

@@ -18,9 +18,12 @@ using SampleApp;
 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";
 
+// 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.
 ChatClient chatClient = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName);
 
 // Create the agent and provide a factory to add our custom memory component to
@@ -33,7 +36,7 @@ ChatClient chatClient = new AzureOpenAIClient(
 AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
 {
     ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
-    AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new UserInfoMemory(chatClient.AsIChatClient(), ctx.SerializedState, ctx.JsonSerializerOptions))
+    AIContextProviders = [new UserInfoMemory(chatClient.AsIChatClient())]
 });
 
 // Create a new session for the conversation.
@@ -47,7 +50,7 @@ Console.WriteLine(await agent.RunAsync("My name is Ruaidhrí", session));
 Console.WriteLine(await agent.RunAsync("I am 20 years old", session));
 
 // We can serialize the session. The serialized state will include the state of the memory component.
-JsonElement sesionElement = agent.SerializeSession(session);
+JsonElement sesionElement = await agent.SerializeSessionAsync(session);
 
 Console.WriteLine("\n>> Use deserialized session with previously created memories\n");
 
@@ -55,10 +58,10 @@ Console.WriteLine("\n>> Use deserialized session with previously created memorie
 var deserializedSession = await agent.DeserializeSessionAsync(sesionElement);
 Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));
 
-Console.WriteLine("\n>> Read memories from memory component\n");
+Console.WriteLine("\n>> Read memories using memory component\n");
 
-// It's possible to access the memory component via the session's GetService method.
-var userInfo = deserializedSession.GetService<UserInfoMemory>()?.UserInfo;
+// It's possible to access the memory component via the agent's GetService method.
+var userInfo = agent.GetService<UserInfoMemory>()?.GetUserInfo(deserializedSession);
 
 // Output the user info that was captured by the memory component.
 Console.WriteLine($"MEMORY - User Name: {userInfo?.UserName}");
@@ -66,12 +69,12 @@ Console.WriteLine($"MEMORY - User Age: {userInfo?.UserAge}");
 
 Console.WriteLine("\n>> Use new session with previously created memories\n");
 
-// It is also possible to set the memories in a memory component on an individual session.
+// It is also possible to set the memories using a memory component on an individual session.
 // This is useful if we want to start a new session, but have it share the same memories as a previous session.
 var newSession = await agent.CreateSessionAsync();
-if (userInfo is not null && newSession.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
+if (userInfo is not null && agent.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
 {
-    newSessionMemory.UserInfo = userInfo;
+    newSessionMemory.SetUserInfo(newSession, userInfo);
 }
 
 // Invoke the agent and output the text result.
@@ -85,29 +88,32 @@ namespace SampleApp
     /// </summary>
     internal sealed class UserInfoMemory : AIContextProvider
     {
+        private readonly ProviderSessionState<UserInfo> _sessionState;
         private readonly IChatClient _chatClient;
 
-        public UserInfoMemory(IChatClient chatClient, UserInfo? userInfo = null)
+        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.UserInfo = userInfo ?? new UserInfo();
         }
 
-        public UserInfoMemory(IChatClient chatClient, JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null)
+        public override string StateKey => this._sessionState.StateKey;
+
+        public UserInfo GetUserInfo(AgentSession session)
+            => this._sessionState.GetOrInitializeState(session);
+
+        public void SetUserInfo(AgentSession session, UserInfo userInfo)
+            => this._sessionState.SaveState(session, userInfo);
+
+        protected override async ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default)
         {
-            this._chatClient = chatClient;
+            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
 
-            this.UserInfo = serializedState.ValueKind == JsonValueKind.Object ?
-                serializedState.Deserialize<UserInfo>(jsonSerializerOptions)! :
-                new UserInfo();
-        }
-
-        public UserInfo UserInfo { get; set; }
-
-        protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
-        {
             // 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 ((this.UserInfo.UserName is null || this.UserInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
+            if ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
             {
                 var result = await this._chatClient.GetResponseAsync<UserInfo>(
                     context.RequestMessages,
@@ -117,36 +123,35 @@ namespace SampleApp
                     },
                     cancellationToken: cancellationToken);
 
-                this.UserInfo.UserName ??= result.Result.UserName;
-                this.UserInfo.UserAge ??= result.Result.UserAge;
+                userInfo.UserName ??= result.Result.UserName;
+                userInfo.UserAge ??= result.Result.UserAge;
             }
+
+            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 userInfo = this._sessionState.GetOrInitializeState(context.Session);
+
             StringBuilder instructions = new();
 
             // 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
                 .AppendLine(
-                    this.UserInfo.UserName is null ?
+                    userInfo.UserName is null ?
                         "Ask the user for their name and politely decline to answer any questions until they provide it." :
-                        $"The user's name is {this.UserInfo.UserName}.")
+                        $"The user's name is {userInfo.UserName}.")
                 .AppendLine(
-                    this.UserInfo.UserAge is null ?
+                    userInfo.UserAge is null ?
                         "Ask the user for their age and politely decline to answer any questions until they provide it." :
-                        $"The user's age is {this.UserInfo.UserAge}.");
+                        $"The user's age is {userInfo.UserAge}.");
 
             return new ValueTask<AIContext>(new AIContext
             {
                 Instructions = instructions.ToString()
             });
         }
-
-        public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
-        {
-            return JsonSerializer.SerializeToElement(this.UserInfo, jsonSerializerOptions);
-        }
     }
 
     internal sealed class UserInfo

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj

@@ -0,0 +1,21 @@
+<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>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.FoundryMemory\Microsoft.Agents.AI.FoundryMemory.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use the FoundryMemoryProvider to persist and recall memories for an agent.
+// The sample stores conversation messages in an Azure AI Foundry memory store and retrieves relevant
+// memories for subsequent invocations, even across new sessions.
+//
+// Note: Memory extraction in Azure AI Foundry is asynchronous and takes time. This sample demonstrates
+// a simple polling approach to wait for memory updates to complete before querying.
+
+using System.Text.Json;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.FoundryMemory;
+
+string foundryEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string memoryStoreName = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_MEMORY_STORE_NAME") ?? "memory-store-sample";
+string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_MODEL") ?? "gpt-4.1-mini";
+string embeddingModelName = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_EMBEDDING_MODEL") ?? "text-embedding-ada-002";
+
+// Create an AIProjectClient for Foundry with Azure Identity authentication.
+DefaultAzureCredential credential = new();
+AIProjectClient projectClient = new(new Uri(foundryEndpoint), credential);
+
+// Get the ChatClient from the AIProjectClient's OpenAI property using the deployment name.
+// The stateInitializer can be used to customize the Foundry Memory scope per session and it will be called each time a session
+// is encountered by the FoundryMemoryProvider that does not already have state stored on the session.
+// If each session should have its own scope, you can create a new id per session via the stateInitializer, e.g.:
+// new FoundryMemoryProvider(projectClient, memoryStoreName, stateInitializer: _ => new(new FoundryMemoryProviderScope(Guid.NewGuid().ToString())), ...)
+// In our case we are storing memories scoped by user so that memories are retained across sessions.
+FoundryMemoryProvider memoryProvider = new(
+    projectClient,
+    memoryStoreName,
+    stateInitializer: _ => new(new FoundryMemoryProviderScope("sample-user-123")));
+
+AIAgent agent = await projectClient.CreateAIAgentAsync(deploymentName,
+    options: new ChatClientAgentOptions()
+    {
+        Name = "TravelAssistantWithFoundryMemory",
+        ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
+        AIContextProviders = [memoryProvider]
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine("\n>> Setting up Foundry Memory Store\n");
+
+// Ensure the memory store exists (creates it with the specified models if needed).
+await memoryProvider.EnsureMemoryStoreCreatedAsync(deploymentName, embeddingModelName, "Sample memory store for travel assistant");
+
+// Clear any existing memories for this scope to demonstrate fresh behavior.
+await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
+
+Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
+Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
+
+// Memory extraction in Azure AI Foundry is asynchronous and takes time to process.
+// WhenUpdatesCompletedAsync polls all pending updates and waits for them to complete.
+Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
+await memoryProvider.WhenUpdatesCompletedAsync();
+
+Console.WriteLine("Updates completed.\n");
+
+Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
+
+Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
+AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
+Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
+
+Console.WriteLine("\n>> Start a new session that shares the same Foundry Memory scope\n");
+
+Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
+await memoryProvider.WhenUpdatesCompletedAsync();
+
+AgentSession newSession = await agent.CreateSessionAsync();
+Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/README.md

@@ -0,0 +1,57 @@
+# Agent with Memory Using Azure AI Foundry
+
+This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories across sessions.
+
+## Features Demonstrated
+
+- Creating a `FoundryMemoryProvider` with Azure Identity authentication
+- Automatic memory store creation if it doesn't exist
+- Multi-turn conversations with automatic memory extraction
+- Memory retrieval to inform agent responses
+- Session serialization and deserialization
+- Memory persistence across completely new sessions
+
+## Prerequisites
+
+1. Azure subscription with Azure AI Foundry project
+2. Azure OpenAI resource with a chat model deployment (e.g., gpt-4o-mini) and an embedding model deployment (e.g., text-embedding-ada-002)
+3. .NET 10.0 SDK
+4. Azure CLI logged in (`az login`)
+
+## Environment Variables
+
+```bash
+# Azure AI Foundry project endpoint and memory store name
+export FOUNDRY_PROJECT_ENDPOINT="https://your-account.services.ai.azure.com/api/projects/your-project"
+export FOUNDRY_PROJECT_MEMORY_STORE_NAME="my_memory_store"
+
+# Model deployment names (models deployed in your Foundry project)
+export FOUNDRY_PROJECT_MODEL="gpt-4o-mini"
+export FOUNDRY_PROJECT_EMBEDDING_MODEL="text-embedding-ada-002"
+```
+
+## Run the Sample
+
+```bash
+dotnet run
+```
+
+## Expected Output
+
+The agent will:
+1. Create the memory store if it doesn't exist (using the specified chat and embedding models)
+2. Learn your name (Taylor), travel destination (Patagonia), timing (November), companions (sister), and interests (scenic viewpoints)
+3. Wait for Foundry Memory to index the memories
+4. Recall those details when asked about the trip
+5. Demonstrate memory persistence across session serialization/deserialization
+6. Show that a brand new session can still access the same memories
+
+## Key Differences from Mem0
+
+| Aspect | Mem0 | Azure AI Foundry Memory |
+|--------|------|------------------------|
+| Authentication | API Key | Azure Identity (DefaultAzureCredential) |
+| Scope | ApplicationId, UserId, AgentId, ThreadId | Single `Scope` string |
+| Memory Types | Single memory store | User Profile + Chat Summary |
+| Hosting | Mem0 cloud or self-hosted | Azure AI Foundry managed service |
+| Store Creation | N/A (automatic) | Explicit via `EnsureMemoryStoreCreatedAsync` |

dotnet/samples/GettingStarted/AgentWithMemory/README.md

@@ -7,3 +7,4 @@ These samples show how to create an agent with the Agent Framework that uses Mem
 |[Chat History memory](./AgentWithMemory_Step01_ChatHistoryMemory/)|This sample demonstrates how to enable an agent to remember messages from previous conversations.|
 |[Memory with MemoryStore](./AgentWithMemory_Step02_MemoryUsingMem0/)|This sample demonstrates how to create and run an agent that uses the Mem0 service to extract and retrieve individual memories.|
 |[Custom Memory Implementation](./AgentWithMemory_Step03_CustomMemory/)|This sample demonstrates how to create a custom memory component and attach it to an agent.|
+|[Memory with Azure AI Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories.|

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Program.cs

@@ -5,7 +5,6 @@
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using OpenAI;
-using OpenAI.Responses;
 
 var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-5";
@@ -15,14 +14,10 @@ var client = new OpenAIClient(apiKey)
         .AsIChatClient().AsBuilder()
         .ConfigureOptions(o =>
         {
-            o.RawRepresentationFactory = _ => new CreateResponseOptions()
+            o.Reasoning = new()
             {
-                ReasoningOptions = new()
-                {
-                    ReasoningEffortLevel = ResponseReasoningEffortLevel.Medium,
-                    // Verbosity requires OpenAI verified Organization
-                    ReasoningSummaryVerbosity = ResponseReasoningSummaryVerbosity.Detailed
-                }
+                Effort = ReasoningEffort.Medium,
+                Output = ReasoningOutput.Full,
             };
         }).Build();
 

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

@@ -18,9 +18,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-3-large";
 
+// 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.
 AzureOpenAIClient azureOpenAIClient = new(
     new Uri(endpoint),
-    new AzureCliCredential());
+    new DefaultAzureCredential());
 
 // Create an In-Memory vector store that uses the Azure OpenAI embedding model to generate embeddings.
 VectorStore vectorStore = new InMemoryVectorStore(new()
@@ -62,12 +65,16 @@ AIAgent agent = azureOpenAIClient
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)),
-        // Since we are using ChatCompletion which stores chat history locally, we can also add a message removal policy
+        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        // Since we are using ChatCompletion which stores chat history locally, we can also add a message filter
         // that removes messages produced by the TextSearchProvider before they are added to the chat history, so that
         // we don't bloat chat history with all the search result messages.
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(ctx.SerializedState, ctx.JsonSerializerOptions)
-            .WithAIContextProviderMessageRemoval()),
+        // By default the chat history provider will store all messages, except for those that came from chat history in the first place.
+        // We also want to maintain that exclusion here.
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+        {
+            StorageInputMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
+        }),
     });
 
 AgentSession session = await agent.CreateSessionAsync();

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

@@ -19,9 +19,12 @@ var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_E
 var afOverviewUrl = "https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/agent-framework/overview/agent-framework-overview.md";
 var afMigrationUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/migration-guide/from-semantic-kernel/index.md";
 
+// 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.
 AzureOpenAIClient azureOpenAIClient = new(
     new Uri(endpoint),
-    new AzureCliCredential());
+    new DefaultAzureCredential());
 
 // Create a Qdrant vector store that uses the Azure OpenAI embedding model to generate embeddings.
 QdrantClient client = new("localhost");
@@ -59,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
@@ -71,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." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, 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/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/Program.cs

@@ -22,14 +22,17 @@ TextSearchProviderOptions textSearchOptions = new()
     RecentMessageMemoryLimit = 6,
 };
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions))
+        AIContextProviders = [new TextSearchProvider(MockSearchAsync, textSearchOptions)]
     });
 
 AgentSession session = await agent.CreateSessionAsync();

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

@@ -15,9 +15,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOIN
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create an AI Project client and get an OpenAI client that works with the foundry service.
+// 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 AzureCliCredential());
+    new DefaultAzureCredential());
 OpenAIClient openAIClient = aiProjectClient.GetProjectOpenAIClient();
 
 // Upload the file that contains the data to be used for RAG to the Foundry service.

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

@@ -10,9 +10,12 @@ using OpenAI.Chat;
 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";
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

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

@@ -10,9 +10,12 @@ using OpenAI.Chat;
 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";
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

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

@@ -18,9 +18,12 @@ static string GetWeather([Description("The location to get the weather for.")] s
     => $"The weather in {location} is cloudy with a high of 15°C.";
 
 // Create the chat client and agent, and provide the function tool to the agent.
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
 

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

@@ -23,9 +23,12 @@ static string GetWeather([Description("The location to get the weather for.")] s
 
 // Create the chat client and agent.
 // Note that we are wrapping the function tool with ApprovalRequiredAIFunction to require user approval before invoking it.
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(GetWeather))]);
 

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,64 +8,176 @@ 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.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    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;
@@ -12,9 +14,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create the agent
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 
@@ -25,17 +30,16 @@ AgentSession session = await agent.CreateSessionAsync();
 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 = agent.SerializeSession(session);
+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

@@ -3,7 +3,7 @@
 #pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
 
 // This sample shows how to create and use a simple AI agent with custom ChatHistoryProvider that stores chat history in a custom storage location.
-// The state of the custom ChatHistoryProvider (SessionDbKey) is stored with the agent session, so that when the session is resumed later,
+// The state of the custom ChatHistoryProvider (SessionDbKey) is stored in the AgentSession's StateBag, so that when the session is resumed later,
 // the chat history can be retrieved from the custom storage location.
 
 using System.Text.Json;
@@ -25,19 +25,19 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 VectorStore vectorStore = new InMemoryVectorStore();
 
 // Create the agent
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
-            // Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
-            // Each session must get its own copy of the VectorChatHistoryProvider, since the provider
-            // also contains the id that the chat history is stored under.
-            new VectorChatHistoryProvider(vectorStore, ctx.SerializedState, ctx.JsonSerializerOptions))
+        // Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
+        ChatHistoryProvider = new VectorChatHistoryProvider(vectorStore)
     });
 
 // Start a new session for the agent conversation.
@@ -49,7 +49,7 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session
 // Serialize the session state, so it can be stored for later use.
 // Since the chat history is stored in the vector store, the serialized session
 // only contains the guid that the messages are stored under in the vector store.
-JsonElement serializedSession = agent.SerializeSession(session);
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 
 Console.WriteLine("\n--- Serialized session ---\n");
 Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }));
@@ -63,80 +63,90 @@ AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSess
 // Run the agent with the session that stores chat history in the vector store a second time.
 Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));
 
-// We can access the VectorChatHistoryProvider via the session's GetService method if we need to read the key under which chat history is stored.
-var chatHistoryProvider = resumedSession.GetService<VectorChatHistoryProvider>()!;
-Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.SessionDbKey}");
+// We can access the VectorChatHistoryProvider via the agent's GetService method
+// if we need to read the key under which chat history is stored. The key is stored
+// in the session state, and therefore we need to provide the session when reading it.
+var chatHistoryProvider = agent.GetService<VectorChatHistoryProvider>()!;
+Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.GetSessionDbKey(resumedSession)}");
 
 namespace SampleApp
 {
     /// <summary>
     /// A sample implementation of <see cref="ChatHistoryProvider"/> that stores chat history in a vector store.
+    /// State (the session DB key) is stored in the <see cref="AgentSession.StateBag"/> so it roundtrips
+    /// automatically with session serialization.
     /// </summary>
     internal sealed class VectorChatHistoryProvider : ChatHistoryProvider
     {
+        private readonly ProviderSessionState<State> _sessionState;
         private readonly VectorStore _vectorStore;
 
-        public VectorChatHistoryProvider(VectorStore vectorStore, JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null)
+        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));
-
-            if (serializedState.ValueKind is JsonValueKind.String)
-            {
-                // Here we can deserialize the session id so that we can access the same messages as before the suspension.
-                this.SessionDbKey = serializedState.Deserialize<string>();
-            }
         }
 
-        public string? SessionDbKey { get; private set; }
+        public override string StateKey => this._sessionState.StateKey;
 
-        protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        public string GetSessionDbKey(AgentSession session)
+            => this._sessionState.GetOrInitializeState(session).SessionDbKey;
+
+        protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
+            var state = this._sessionState.GetOrInitializeState(context.Session);
             var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
             await collection.EnsureCollectionExistsAsync(cancellationToken);
 
             var records = await collection
                 .GetAsync(
-                    x => x.SessionId == this.SessionDbKey, 10,
+                    x => x.SessionId == state.SessionDbKey, 10,
                     new() { OrderBy = x => x.Descending(y => y.Timestamp) },
                     cancellationToken)
                 .ToListAsync(cancellationToken);
 
-            var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!)
-;
+            var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!);
             messages.Reverse();
             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;
-            }
-
-            this.SessionDbKey ??= Guid.NewGuid().ToString("N");
+            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
-            // Optionally messages produced by the AIContextProvider can also be persisted (not shown).
             var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
 
             await collection.UpsertAsync(allNewMessages.Select(x => new ChatHistoryItem()
             {
-                Key = this.SessionDbKey + x.MessageId,
+                Key = state.SessionDbKey + x.MessageId,
                 Timestamp = DateTimeOffset.UtcNow,
-                SessionId = this.SessionDbKey,
+                SessionId = state.SessionDbKey,
                 SerializedMessage = JsonSerializer.Serialize(x),
                 MessageText = x.Text
             }), cancellationToken);
         }
 
-        public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null) =>
-            // We have to serialize the session id, so that on deserialization we can retrieve the messages using the same session id.
-            JsonSerializer.SerializeToElement(this.SessionDbKey);
+        /// <summary>
+        /// Represents the per-session state stored in the <see cref="AgentSession.StateBag"/>.
+        /// </summary>
+        public sealed class State
+        {
+            public State(string sessionDbKey)
+            {
+                this.SessionDbKey = sessionDbKey ?? throw new ArgumentNullException(nameof(sessionDbKey));
+            }
+
+            public string SessionDbKey { get; }
+        }
 
         /// <summary>
         /// The data structure used to store chat history items in the vector store.

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

@@ -27,7 +27,10 @@ if (!string.IsNullOrWhiteSpace(applicationInsightsConnectionString))
 using var tracerProvider = tracerProviderBuilder.Build();
 
 // Create the agent, and enable OpenTelemetry instrumentation.
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// 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.
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker")
     .AsBuilder()

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

@@ -21,9 +21,12 @@ HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
 builder.Services.AddSingleton(new ChatClientAgentOptions() { Name = "Joker", ChatOptions = new() { Instructions = "You are good at telling jokes." } });
 
 // Add a chat client to the service collection.
+// 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.
 builder.Services.AddKeyedChatClient("AzureOpenAI", (sp) => new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
         .GetChatClient(deploymentName)
         .AsIChatClient());
 

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

@@ -12,7 +12,10 @@ using ModelContextProtocol.Server;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
-var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+// 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.
+var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
 
 // Create a server side persistent agent
 var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(

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_Step11_UsingImages/Program.cs

@@ -11,7 +11,10 @@ using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";
 
-var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// 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.
+var agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         name: "VisionAgent",

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

@@ -17,9 +17,12 @@ static string GetWeather([Description("The location to get the weather for.")] s
     => $"The weather in {location} is cloudy with a high of 15°C.";
 
 // Create the chat client and agent, and provide the function tool to the agent.
+// 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.
 AIAgent weatherAgent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetChatClient(deploymentName)
      .AsAIAgent(
         instructions: "You answer questions about the weather.",
@@ -30,7 +33,7 @@ AIAgent weatherAgent = new AzureOpenAIClient(
 // Create the main agent, and provide the weather agent as a function tool.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant who responds in French.", tools: [weatherAgent.AsAIFunction()]);
 

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

@@ -19,9 +19,12 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 
 var stateStore = new Dictionary<string, JsonElement?>();
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetResponsesClient(deploymentName)
      .AsAIAgent(
         name: "SpaceNovelWriter",
@@ -40,7 +43,7 @@ AgentResponse response = await agent.RunAsync("Write a very long novel about a t
 // Poll for background responses until complete.
 while (response.ContinuationToken is not null)
 {
-    PersistAgentState(agent, session, response.ContinuationToken);
+    await PersistAgentState(agent, session, response.ContinuationToken);
 
     await Task.Delay(TimeSpan.FromSeconds(10));
 
@@ -52,9 +55,9 @@ while (response.ContinuationToken is not null)
 
 Console.WriteLine(response.Text);
 
-void PersistAgentState(AIAgent agent, AgentSession? session, ResponseContinuationToken? continuationToken)
+async Task PersistAgentState(AIAgent agent, AgentSession? session, ResponseContinuationToken? continuationToken)
 {
-    stateStore["session"] = agent.SerializeSession(session!);
+    stateStore["session"] = await agent.SerializeSessionAsync(session!);
     stateStore["continuationToken"] = JsonSerializer.SerializeToElement(continuationToken, AgentAbstractionsJsonUtilities.DefaultOptions.GetTypeInfo(typeof(ResponseContinuationToken)));
 }
 

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;
@@ -17,7 +18,10 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";
 
 // Get a client to create/retrieve server side agents with
-var azureOpenAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// 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.
+var azureOpenAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName);
 
 [Description("Get the weather for a given location.")]
@@ -93,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)
 {
@@ -256,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

@@ -7,13 +7,14 @@ This sample demonstrates how to add middleware to intercept:
 
 ## What This Sample Shows
 
-1. Azure OpenAI integration via `AzureOpenAIClient` and `AzureCliCredential`
+1. Azure OpenAI integration via `AzureOpenAIClient` and `DefaultAzureCredential`
 2. Chat client middleware using `ChatClientBuilder.Use(...)`
 3. Agent run middleware (PII redaction and wording guardrails)
 4. Function invocation middleware (logging and overriding a tool result)
 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_Step15_Plugins/Program.cs

@@ -27,9 +27,12 @@ services.AddSingleton<AgentPlugin>(); // The plugin depends on WeatherProvider a
 
 IServiceProvider serviceProvider = services.BuildServiceProvider();
 
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         instructions: "You are a helpful assistant that helps people find information.",

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

@@ -16,15 +16,18 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Construct the agent, and provide a factory to create an in-memory chat message store with a reducer that keeps only the last 2 non-system messages.
+// 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.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(new MessageCountingChatReducer(2), ctx.SerializedState, ctx.JsonSerializerOptions))
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new() { ChatReducer = new MessageCountingChatReducer(2) })
     });
 
 AgentSession session = await agent.CreateSessionAsync();
@@ -33,17 +36,31 @@ AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
 
 // Get the chat history to see how many messages are stored.
-IList<ChatMessage>? chatHistory = session.GetService<IList<ChatMessage>>();
+// 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");