Fixed CA1873 warning (#4479)

* discover resources in skills folder

* address pr review comments

* change type of AllowedResourceExtensions

* address pr review comment

.devcontainer/dotnet/devcontainer.json

@@ -1,10 +1,6 @@
 {
   "name": "C# (.NET)",
-  //"image": "mcr.microsoft.com/devcontainers/dotnet",
-  // Workaround for https://github.com/devcontainers/images/issues/1752
-  "build": {
-    "dockerfile": "dotnet.Dockerfile"
-  },
+  "image": "mcr.microsoft.com/devcontainers/dotnet",
   "features": {
     "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
     "ghcr.io/devcontainers/features/github-cli:1": {

.devcontainer/dotnet/dotnet.Dockerfile

@@ -1,5 +0,0 @@
-FROM mcr.microsoft.com/devcontainers/universal:latest
-
-# Remove Yarn repository with expired GPG key to prevent apt-get update failures
-# Tracking issue: https://github.com/devcontainers/images/issues/1752
-RUN rm -f /etc/apt/sources.list.d/yarn.list

.github/actions/sample-validation-setup/action.yml

@@ -0,0 +1,48 @@
+name: Sample Validation Setup
+description: Sets up the environment for sample validation (checkout, Node.js, Copilot CLI, Azure login, Python)
+
+inputs:
+  azure-client-id:
+    description: Azure Client ID for OIDC login
+    required: true
+  azure-tenant-id:
+    description: Azure Tenant ID for OIDC login
+    required: true
+  azure-subscription-id:
+    description: Azure Subscription ID for OIDC login
+    required: true
+  python-version:
+    description: The Python version to set up
+    required: false
+    default: "3.12"
+  os:
+    description: The operating system to set up
+    required: false
+    default: "Linux"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Node.js environment
+      uses: actions/setup-node@v4
+
+    - name: Install Copilot CLI
+      shell: bash
+      run: npm install -g @github/copilot
+
+    - name: Test Copilot CLI
+      shell: bash
+      run: copilot -p "What can you do in one sentence?"
+
+    - name: Azure CLI Login
+      uses: azure/login@v2
+      with:
+        client-id: ${{ inputs.azure-client-id }}
+        tenant-id: ${{ inputs.azure-tenant-id }}
+        subscription-id: ${{ inputs.azure-subscription-id }}
+
+    - name: Set up python and install the project
+      uses: ./.github/actions/python-setup
+      with:
+        python-version: ${{ inputs.python-version }}
+        os: ${{ inputs.os }}

.github/labeler.yml

@@ -23,7 +23,7 @@ workflows:
   - any-glob-to-any-file:
     - dotnet/src/Microsoft.Agents.AI.Workflows/**
     - dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/**
-    - dotnet/samples/GettingStarted/Workflow/**
+    - dotnet/samples/03-workflows/**
     - python/packages/main/agent_framework/_workflow/**
     - python/samples/getting_started/workflow/**
 

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

@@ -92,7 +92,7 @@ jobs:
           Write-Host "Launching Azure Cosmos DB Emulator"
           Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
           Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+          echo "COSMOSDB_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
 
       - name: Setup dotnet
         uses: actions/setup-dotnet@v5.1.0
@@ -205,20 +205,17 @@ jobs:
           COSMOSDB_ENDPOINT: https://localhost:8081
           COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
           # OpenAI Models
-          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
-          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
-          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_CHAT_MODEL_NAME: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
+          OPENAI_REASONING_MODEL_NAME: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
           # Azure OpenAI Models
-          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
           # Azure AI Foundry
-          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
-          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
-          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
-          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
-          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}
+          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+          AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
 
       # Generate test reports and check coverage
       - name: Generate test reports

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

@@ -0,0 +1,102 @@
+#
+# Dedicated .NET integration tests workflow, called from the manual integration test orchestrator.
+# Only runs integration test matrix entries (net10.0 and net472).
+#
+
+name: dotnet-integration-tests
+
+on:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., refs/pull/123/head)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  dotnet-integration-tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release }
+          - { targetFramework: "net472", os: "windows-latest", configuration: Release }
+    runs-on: ${{ matrix.os }}
+    environment: integration
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+          sparse-checkout: |
+            .
+            .github
+            dotnet
+            python
+            workflow-samples
+
+      - name: Start Azure Cosmos DB Emulator
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          Write-Host "Launching Azure Cosmos DB Emulator"
+          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
+          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5.1.0
+        with:
+          global-json-file: ${{ github.workspace }}/dotnet/global.json
+
+      - name: Build dotnet solutions
+        shell: bash
+        run: |
+          export SOLUTIONS=$(find ./dotnet/ -type f -name "*.slnx" | tr '\n' ' ')
+          for solution in $SOLUTIONS; do
+            dotnet build $solution -c ${{ matrix.configuration }} --warnaserror
+          done
+
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Set up Durable Task and Azure Functions Integration Test Emulators
+        if: matrix.os == 'ubuntu-latest'
+        uses: ./.github/actions/azure-functions-integration-setup
+
+      - name: Run Integration Tests
+        shell: bash
+        run: |
+          export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
+          for project in $INTEGRATION_TEST_PROJECTS; do
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --filter "Category!=IntegrationDisabled"
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
+          done
+        env:
+          COSMOSDB_ENDPOINT: https://localhost:8081
+          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
+          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
+          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
+          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
+          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
+          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
+          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}

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

@@ -0,0 +1,134 @@
+#
+# 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 calls dedicated integration-only workflows (dotnet-integration-tests and python-integration-tests),
+# passing a ref so they check out and test the correct code.
+# Changed paths are detected here so only the relevant test suites run.
+#
+
+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 }}
+      dotnet-changes: ${{ steps.detect-changes.outputs.dotnet }}
+      python-changes: ${{ steps.detect-changes.outputs.python }}
+    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 }}
+        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)
+            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
+
+            if [ "$PR_STATE" != "OPEN" ]; then
+              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
+              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
+
+      - name: Detect changed paths
+        id: detect-changes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.inputs.pr-number }}
+          BRANCH: ${{ github.event.inputs.branch }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ -n "$PR_NUMBER" ]; then
+            CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --repo "$REPO" --name-only)
+          else
+            # For branches, compare against main using the GitHub API
+            CHANGED_FILES=$(gh api "repos/$REPO/compare/main...$BRANCH" --jq '.files[].filename')
+          fi
+
+          DOTNET_CHANGES=false
+          PYTHON_CHANGES=false
+
+          if echo "$CHANGED_FILES" | grep -q '^dotnet/'; then
+            DOTNET_CHANGES=true
+          fi
+
+          if echo "$CHANGED_FILES" | grep -q '^python/'; then
+            PYTHON_CHANGES=true
+          fi
+
+          echo "dotnet=$DOTNET_CHANGES" >> "$GITHUB_OUTPUT"
+          echo "python=$PYTHON_CHANGES" >> "$GITHUB_OUTPUT"
+          echo "Detected changes — dotnet: $DOTNET_CHANGES, python: $PYTHON_CHANGES"
+
+  dotnet-integration-tests:
+    name: .NET Integration Tests
+    needs: resolve-ref
+    if: needs.resolve-ref.outputs.dotnet-changes == 'true'
+    uses: ./.github/workflows/dotnet-integration-tests.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit
+
+  python-integration-tests:
+    name: Python Integration Tests
+    needs: resolve-ref
+    if: needs.resolve-ref.outputs.python-changes == 'true'
+    uses: ./.github/workflows/python-integration-tests.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit

.github/workflows/merge-gatekeeper.yml

@@ -29,4 +29,7 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           timeout: 3600
           interval: 30
-          ignored: CodeQL,CodeQL analysis (csharp)
+          # "Cleanup artifacts", "Agent", "Prepare", and "Upload results" are check runs
+          # created by an org-level GitHub App (MSDO), not by any workflow in this repo.
+          # They are outside our control and their transient failures should not block merges.
+          ignored: CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results

.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-integration-tests.yml

@@ -0,0 +1,319 @@
+#
+# Dedicated Python integration tests workflow, called from the manual integration test orchestrator.
+# Runs all tests (unit + integration) split into parallel jobs by provider.
+#
+# NOTE: This workflow and python-merge-tests.yml share the same set of parallel
+# test jobs. Keep them in sync — when adding, removing, or modifying a job here,
+# apply the same change to python-merge-tests.yml.
+#
+
+name: python-integration-tests
+
+on:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., refs/pull/123/head)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+  UV_PYTHON: "3.13"
+
+jobs:
+  # Unit tests: all non-integration tests across all packages
+  python-tests-unit:
+    name: Python Integration Tests - Unit
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (unit tests only)
+        run: >
+          uv run poe all-tests
+          -m "not integration"
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # OpenAI integration tests
+  python-tests-openai:
+    name: Python Integration Tests - OpenAI
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/openai
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # Azure OpenAI integration tests
+  python-tests-azure-openai:
+    name: Python Integration Tests - Azure OpenAI
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Test with pytest (Azure OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/azure
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # Misc integration tests (Anthropic, Ollama, MCP)
+  python-tests-misc-integration:
+    name: Python Integration Tests - Misc
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/anthropic/tests
+          packages/ollama/tests
+          packages/core/tests/core/test_mcp.py
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # Azure Functions + Durable Task integration tests
+  python-tests-functions:
+    name: Python Integration Tests - Functions
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      UV_PYTHON: "3.10"
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      FUNCTIONS_WORKER_RUNTIME: "python"
+      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+      AzureWebJobsStorage: "UseDevelopmentStorage=true"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Set up Azure Functions Integration Test Emulators
+        uses: ./.github/actions/azure-functions-integration-setup
+        id: azure-functions-setup
+      - name: Test with pytest (Functions + Durable Task integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/azurefunctions/tests/integration_tests
+          packages/durabletask/tests/integration_tests
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # Azure AI integration tests
+  python-tests-azure-ai:
+    name: Python Integration Tests - Azure AI
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Test with pytest
+        timeout-minutes: 15
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+
+  # Azure Cosmos integration tests
+  python-tests-cosmos:
+    name: Python Integration Tests - Cosmos
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    services:
+      cosmosdb:
+        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
+        ports:
+          - 8081:8081
+    env:
+      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
+      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
+      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
+      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Wait for Cosmos DB emulator
+        run: |
+          for i in {1..60}; do
+            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
+              echo "Cosmos DB emulator is ready."
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Cosmos DB emulator did not become ready in time." >&2
+          exit 1
+      - name: Test with pytest (Cosmos integration)
+        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+
+  python-integration-tests-check:
+    if: always()
+    runs-on: ubuntu-latest
+    needs:
+      [
+        python-tests-unit,
+        python-tests-openai,
+        python-tests-azure-openai,
+        python-tests-misc-integration,
+        python-tests-functions,
+        python-tests-azure-ai,
+        python-tests-cosmos
+      ]
+    steps:
+      - name: Fail workflow if tests failed
+        if: contains(join(needs.*.result, ','), 'failure')
+        uses: actions/github-script@v8
+        with:
+          script: core.setFailed('Integration Tests Failed!')
+
+      - name: Fail workflow if tests cancelled
+        if: contains(join(needs.*.result, ','), 'cancelled')
+        uses: actions/github-script@v8
+        with:
+          script: core.setFailed('Integration Tests Cancelled!')

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

@@ -1,4 +1,9 @@
 name: Python - Merge - Tests
+#
+# NOTE: This workflow and python-integration-tests.yml share the same set of
+# parallel test jobs. Keep them in sync — when adding, removing, or modifying a
+# job here, apply the same change to python-integration-tests.yml.
+#
 
 on:
   workflow_dispatch:
@@ -10,13 +15,13 @@ on:
     - cron: "0 0 * * *" # Run at midnight UTC daily
 
 permissions:
-  contents: write
+  contents: read
   id-token: write
 
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
-  RUN_INTEGRATION_TESTS: "true"
+  UV_PYTHON: "3.13"
   RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}
 
 jobs:
@@ -26,7 +31,14 @@ jobs:
       contents: read
       pull-requests: read
     outputs:
-      pythonChanges: ${{ steps.filter.outputs.python}}
+      pythonChanges: ${{ steps.filter.outputs.python }}
+      coreChanged: ${{ steps.filter.outputs.core }}
+      openaiChanged: ${{ steps.filter.outputs.openai }}
+      azureChanged: ${{ steps.filter.outputs.azure }}
+      miscChanged: ${{ steps.filter.outputs.misc }}
+      functionsChanged: ${{ steps.filter.outputs.functions }}
+      azureAiChanged: ${{ steps.filter.outputs.azure-ai }}
+      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
     steps:
       - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
@@ -35,6 +47,29 @@ jobs:
           filters: |
             python:
               - 'python/**'
+            core:
+              - 'python/packages/core/agent_framework/_*.py'
+              - 'python/packages/core/agent_framework/_workflows/**'
+              - 'python/packages/core/agent_framework/exceptions.py'
+              - 'python/packages/core/agent_framework/observability.py'
+            openai:
+              - 'python/packages/core/agent_framework/openai/**'
+              - 'python/packages/core/tests/openai/**'
+            azure:
+              - 'python/packages/core/agent_framework/azure/**'
+              - 'python/packages/core/tests/azure/**'
+            misc:
+              - 'python/packages/anthropic/**'
+              - 'python/packages/ollama/**'
+              - 'python/packages/core/agent_framework/_mcp.py'
+              - 'python/packages/core/tests/core/test_mcp.py'
+            functions:
+              - 'python/packages/azurefunctions/**'
+              - 'python/packages/durabletask/**'
+            azure-ai:
+              - 'python/packages/azure-ai/**'
+            cosmos:
+              - 'python/packages/azure-cosmos/**'
       # run only if 'python' files were changed
       - name: python tests
         if: steps.filter.outputs.python == 'true'
@@ -43,34 +78,15 @@ jobs:
       - name: not python tests
         if: steps.filter.outputs.python != 'true'
         run: echo "NOT python file"
-  python-tests-core:
-    name: Python Tests - Core
+  # Unit tests: always run all non-integration tests across all packages
+  python-tests-unit:
+    name: Python Tests - Unit
     needs: paths-filter
-    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.10"]
-        os: [ubuntu-latest]
-        environment: ["integration"]
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-      # For Azure Functions integration tests
-      FUNCTIONS_WORKER_RUNTIME: "python"
-      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
-      AzureWebJobsStorage: "UseDevelopmentStorage=true"
-
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ubuntu-latest
+    environment: integration
     defaults:
       run:
         working-directory: python
@@ -80,11 +96,219 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (unit tests only)
+        run: >
+          uv run poe all-tests
+          -m "not integration"
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Unit test results
+
+  # OpenAI integration tests
+  python-tests-openai:
+    name: Python Tests - OpenAI Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.openaiChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/openai
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Test OpenAI samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "openai"
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: OpenAI integration test results
+
+  # Azure OpenAI integration tests
+  python-tests-azure-openai:
+    name: Python Tests - Azure OpenAI Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.azureChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        if: github.event_name != 'pull_request'
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Test with pytest (Azure OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/azure
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Test Azure samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "azure"
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Azure OpenAI integration test results
+
+  # Misc integration tests (Anthropic, Ollama, MCP)
+  python-tests-misc-integration:
+    name: Python Tests - Misc Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.miscChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/anthropic/tests
+          packages/ollama/tests
+          packages/core/tests/core/test_mcp.py
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Misc integration test results
+
+  # Azure Functions + Durable Task integration tests
+  python-tests-functions:
+    name: Python Tests - Functions Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.functionsChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      UV_PYTHON: "3.10"
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      FUNCTIONS_WORKER_RUNTIME: "python"
+      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+      AzureWebJobsStorage: "UseDevelopmentStorage=true"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
-        env:
-          # Configure a constant location for the uv cache
-          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
         uses: azure/login@v2
@@ -95,13 +319,15 @@ jobs:
       - name: Set up Azure Functions Integration Test Emulators
         uses: ./.github/actions/azure-functions-integration-setup
         id: azure-functions-setup
-      - name: Test with pytest
-        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test core samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "openai" -m "azure"
+      - name: Test with pytest (Functions + Durable Task integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/azurefunctions/tests/integration_tests
+          packages/durabletask/tests/integration_tests
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Surface failing tests
         if: always()
@@ -111,22 +337,20 @@ jobs:
           summary: true
           display-options: fEX
           fail-on-empty: false
-          title: Test results
+          title: Functions integration test results
 
   python-tests-azure-ai:
     name: Python Tests - Azure AI
     needs: paths-filter
-    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.10"]
-        os: [ubuntu-latest]
-        environment: ["integration"]
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.azureAiChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
     env:
-      UV_PYTHON: ${{ matrix.python-version }}
       AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
       AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
       LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
@@ -139,11 +363,8 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
-        env:
-          # Configure a constant location for the uv cache
-          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
         uses: azure/login@v2
@@ -153,7 +374,7 @@ jobs:
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
         timeout-minutes: 15
-        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Test Azure AI samples
         timeout-minutes: 10
@@ -172,16 +393,78 @@ jobs:
 
   # TODO: Add python-tests-lab
 
+  # Azure Cosmos integration tests
+  python-tests-cosmos:
+    name: Python Tests - Cosmos Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.cosmosChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    services:
+      cosmosdb:
+        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
+        ports:
+          - 8081:8081
+    env:
+      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
+      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
+      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
+      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Wait for Cosmos DB emulator
+        run: |
+          for i in {1..60}; do
+            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
+              echo "Cosmos DB emulator is ready."
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Cosmos DB emulator did not become ready in time." >&2
+          exit 1
+      - name: Test with pytest (Cosmos integration)
+        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Cosmos integration test results
+
   python-integration-tests-check:
     if: always()
     runs-on: ubuntu-latest
     needs:
       [
-        python-tests-core,
-        python-tests-azure-ai
+        python-tests-unit,
+        python-tests-openai,
+        python-tests-azure-openai,
+        python-tests-misc-integration,
+        python-tests-functions,
+        python-tests-azure-ai,
+        python-tests-cosmos,
       ]
     steps:
-
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')

.github/workflows/python-sample-validation.yml

@@ -0,0 +1,302 @@
+name: Python - Sample Validation
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *" # Run at midnight UTC daily
+
+env:
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
+  # GitHub Copilot configuration
+  GITHUB_COPILOT_MODEL: claude-opus-4.6
+  COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  validate-01-get-started:
+    name: Validate 01-get-started
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Required configuration for get-started samples
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 01-get-started --save-report --report-name 01-get-started
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-01-get-started
+          path: python/scripts/sample_validation/reports/
+
+  validate-02-agents:
+    name: Validate 02-agents
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Azure AI configuration
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # OpenAI configuration
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      # Observability
+      ENABLE_INSTRUMENTATION: "true"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 02-agents --save-report --report-name 02-agents
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-02-agents
+          path: python/scripts/sample_validation/reports/
+
+  validate-03-workflows:
+    name: Validate 03-workflows
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Azure AI configuration
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 03-workflows --save-report --report-name 03-workflows
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-03-workflows
+          path: python/scripts/sample_validation/reports/
+
+  validate-04-hosting:
+    name: Validate 04-hosting
+    if: false  # Temporarily disabled because of sample complexity
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Azure AI configuration
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # A2A configuration
+      A2A_AGENT_HOST: http://localhost:5001/
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 04-hosting --save-report --report-name 04-hosting
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-04-hosting
+          path: python/scripts/sample_validation/reports/
+
+  validate-05-end-to-end:
+    name: Validate 05-end-to-end
+    if: false  # Temporarily disabled because of sample complexity
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Azure AI configuration
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure AI Search (for evaluation samples)
+      AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
+      AZURE_SEARCH_API_KEY: ${{ secrets.AZURE_SEARCH_API_KEY }}
+      AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
+      # Evaluation sample
+      AZURE_AI_MODEL_DEPLOYMENT_NAME_WORKFLOW: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 05-end-to-end --save-report --report-name 05-end-to-end
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-05-end-to-end
+          path: python/scripts/sample_validation/reports/
+
+  validate-autogen-migration:
+    name: Validate autogen-migration
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Azure AI configuration
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      # OpenAI configuration
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir autogen-migration --save-report --report-name autogen-migration
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-autogen-migration
+          path: python/scripts/sample_validation/reports/
+
+  validate-semantic-kernel-migration:
+    name: Validate semantic-kernel-migration
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      # Azure AI configuration
+      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # OpenAI configuration
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      # Copilot Studio
+      COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
+      COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
+      COPILOTSTUDIOAGENT__TENANTID: ${{ secrets.COPILOTSTUDIOAGENT__TENANTID }}
+      COPILOTSTUDIOAGENT__AGENTAPPID: ${{ secrets.COPILOTSTUDIOAGENT__AGENTAPPID }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup environment
+        uses: ./.github/actions/sample-validation-setup
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          os: ${{ runner.os }}
+
+      - name: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir semantic-kernel-migration --save-report --report-name semantic-kernel-migration
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-semantic-kernel-migration
+          path: python/scripts/sample_validation/reports/

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/03-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/02-agents/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/02-agents/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/02-agents/Agents/Agent_Step11_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,15 +163,15 @@ 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
 
-- [Getting Started with Agents](./dotnet/samples/GettingStarted/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./dotnet/samples/GettingStarted/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./dotnet/samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started with Agents](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
 
 ## Contributor Resources
 

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/).

agent-samples/openai/OpenAIResponses.yaml

@@ -11,7 +11,7 @@ model:
         topP: 0.95
     connection:
         kind: key
-        apiKey: =Env.OPENAI_APIKEY
+        apiKey: =Env.OPENAI_API_KEY
 outputSchema:
     properties:
         language:

docs/decisions/0001-agent-run-response.md

@@ -498,7 +498,7 @@ We need to decide what AIContent types, each agent response type will be mapped
 | Google ADK | **Approach 1** Both [input and output schemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
 | AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.structured_output) |
 | LangGraph | **Approach 1** Supports [configuring an agent](https://langchain-ai.github.io/langgraph/agents/agents/?h=structured#6-configure-structured-output) at agent construction time, and a [structured response](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) can be retrieved as a special property on the agent response |
-| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/examples/getting-started/structured-output) at agent construction time |
+| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/input-output/structured-output/agent) at agent construction time |
 | A2A | **Informal Approach 2** Doesn't formally support schema negotiation, but [hints can be provided via metadata](https://a2a-protocol.org/latest/specification/#97-structured-data-exchange-requesting-and-providing-json) at invocation time |
 | Protocol Activity | Supports returning [Complex types](https://github.com/microsoft/Agents/blob/main/specs/activity/protocol-activity.md#complex-types) but no support for requesting a type |
 

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,51 @@ 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"`
+- `FoundryMemoryProvider.DEFAULT_SOURCE_ID = "foundry_memory"`
+
+
 ## 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/decisions/0017-agent-additional-properties.md

@@ -0,0 +1,211 @@
+---
+status: accepted
+contact: westey-m
+date: 2026-02-24
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
+consulted:
+informed:
+---
+
+# AdditionalProperties for AIAgent and AgentSession
+
+## Context and Problem Statement
+
+The `AIAgent` base class currently exposes `Id`, `Name`, and `Description` as its core metadata properties, and `AgentSession` exposes only a `StateBag` property.
+Neither type has a mechanism for attaching arbitrary metadata, such as protocol-specific descriptors (e.g., A2A agent cards), hosting attributes, session-level tags, or custom user-defined metadata for discovery and routing.
+
+Other types in the framework already carry `AdditionalProperties` — notably `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate` — all using `AdditionalPropertiesDictionary` from `Microsoft.Extensions.AI`.
+Adding a similar property to `AIAgent` and `AgentSession` would give both types a consistent, extensible metadata surface.
+
+Related: [Work Item #2133](https://github.com/microsoft/agent-framework/issues/2133)
+
+## Decision Drivers
+
+- **Consistency**: Other core types (`AgentRunOptions`, `AgentResponse`, `AgentResponseUpdate`) already expose `AdditionalProperties`. `AIAgent` and `AgentSession` are the major abstractions that lack this.
+- **Extensibility**: Hosting libraries, protocol adapters (A2A, AG-UI), and discovery mechanisms need a place to attach agent-level and session-level metadata without subclassing.
+- **Simplicity**: The solution should be easy to understand and use; avoid over-engineering.
+- **Minimal breaking change**: The addition should not require changes to existing agent implementations.
+- **Clear semantics**: Users should understand what `AdditionalProperties` on an agent or session means and how it differs from `AdditionalProperties` on `AgentRunOptions`.
+
+## Considered Options
+
+### Surface Area
+
+- **Option A**: Public get-only property, auto-initialized (`AdditionalPropertiesDictionary AdditionalProperties { get; } = new()`) on both `AIAgent` and `AgentSession`
+- **Option B**: Public get/set nullable property (`AdditionalPropertiesDictionary? AdditionalProperties { get; set; }`) on both `AIAgent` and `AgentSession`
+- **Option C**: Constructor-injected dictionary with public get-only accessor on both `AIAgent` and `AgentSession`
+- **Option D**: External container/wrapper object — metadata lives outside `AIAgent` and `AgentSession`; no changes to the base classes
+
+### Semantics
+
+- **Option 1**: Metadata only — describes the agent or session; not propagated when calling `IChatClient`
+- **Option 2**: Passed down the stack — merged into `ChatOptions.AdditionalProperties` during `ChatClientAgent` runs
+
+## Decision Outcome
+
+The chosen option is **Option D + Option 1**: an external container/wrapper object, used purely as metadata.
+
+### Consequences
+
+- Good, because `AIAgent` and `AgentSession` remain unchanged, avoiding any increase to the core framework surface area while still enabling extensible metadata.
+- Good, because an external wrapper (owned by hosting/protocol libraries or user code, not the `AIAgent` / `AgentSession` base classes) can internally use `AdditionalPropertiesDictionary` to stay consistent with existing patterns on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
+- Good, because metadata-only semantics keep a clean separation from per-run extensibility (`AgentRunOptions.AdditionalProperties`) and avoid unexpected side effects during agent execution.
+- Good, because no additional allocation occurs on `AIAgent` or `AgentSession` when no metadata is needed; external wrappers can be created only when metadata is required.
+- Bad, because callers and libraries must manage and pass around both the agent/session instance and its associated metadata wrapper, keeping them correctly associated.
+- Bad, because different hosting or protocol layers may define their own wrapper types, which can fragment the ecosystem unless conventions are agreed upon.
+
+## Pros and Cons of the Options
+
+### Option A — Public get-only property, auto-initialized
+
+The property is always non-null and ready to use. Users add metadata after construction.
+
+```csharp
+public abstract partial class AIAgent
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
+}
+
+public abstract partial class AgentSession
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
+}
+
+// Usage
+agent.AdditionalProperties["protocol"] = "A2A";
+agent.AdditionalProperties.Add<MyAgentCardInfo>(cardInfo);
+session.AdditionalProperties["tenant"] = tenantId;
+```
+
+- Good, because users never encounter `null` — no defensive null checks needed.
+- Good, because the dictionary reference cannot be replaced, preventing accidental data loss.
+- Good, because it is the simplest API surface to use.
+- Neutral, because it always allocates, even when no metadata is needed. The allocation cost is negligible.
+- Bad, because it cannot be set at construction time as a single object (users must populate it post-construction).
+
+### Option B — Public get/set nullable property
+
+Matches the existing pattern on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
+
+```csharp
+public abstract partial class AIAgent
+{
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+public abstract partial class AgentSession
+{
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+// Usage
+agent.AdditionalProperties ??= new();
+agent.AdditionalProperties["protocol"] = "A2A";
+session.AdditionalProperties ??= new();
+session.AdditionalProperties["tenant"] = tenantId;
+```
+
+- Good, because it is consistent with the existing `AdditionalProperties` pattern on `AgentRunOptions` and `AgentResponse`.
+- Good, because it avoids allocation when no metadata is needed.
+- Bad, because every consumer must null-check before reading or writing.
+- Bad, because the entire dictionary can be replaced, risking accidental loss of metadata set by other components (e.g., a hosting library sets metadata, then user code replaces the dictionary).
+
+### Option C — Constructor-injected with public get
+
+The dictionary is provided at construction time and exposed as get-only.
+
+```csharp
+public abstract partial class AIAgent
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; }
+
+    protected AIAgent(AdditionalPropertiesDictionary? additionalProperties = null)
+    {
+        this.AdditionalProperties = additionalProperties ?? new();
+    }
+}
+
+public abstract partial class AgentSession
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; }
+
+    protected AgentSession(AdditionalPropertiesDictionary? additionalProperties = null)
+    {
+        this.AdditionalProperties = additionalProperties ?? new();
+    }
+}
+```
+
+- Good, because an agent's metadata can be established before any code runs against it.
+- Bad, because `AdditionalPropertiesDictionary` has no read-only variant, so the constructor-injection pattern gives a false sense of immutability — callers can still mutate the dictionary contents after construction.
+- Bad, because it requires adding a constructor parameter to the abstract base classes, which is a source-breaking change for all existing `AIAgent` and `AgentSession` subclasses (even with a default value, it changes the constructor signature that derived classes chain to).
+- Bad, because it is more complex with little practical benefit over Option A, since post-construction mutation is equally possible.
+
+### Option D — External container/wrapper object
+
+Rather than adding `AdditionalProperties` to `AIAgent` or `AgentSession`, users wrap the agent or session in a container object that carries both the instance and any associated metadata. No changes to the base classes are required.
+
+```csharp
+public class AgentWithMetadata
+{
+    public required AIAgent Agent { get; init; }
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+public class SessionWithMetadata
+{
+    public required AgentSession Session { get; init; }
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+// Usage
+var wrapper = new AgentWithMetadata
+{
+    Agent = myAgent,
+    AdditionalProperties = new() { ["protocol"] = "A2A" }
+};
+```
+
+- Good, because it requires no changes to `AIAgent` or `AgentSession`, avoiding any risk of breaking existing implementations.
+- Good, because metadata is clearly external to the agent and session, eliminating any ambiguity about whether it might be passed down the execution stack.
+- Good, because the container pattern gives the user full control over the metadata lifecycle and serialization.
+- Bad, because it is not discoverable — users must know about the container convention; there is no built-in API surface guiding them.
+
+### Option 1 — Metadata only
+
+`AdditionalProperties` on `AIAgent` and `AgentSession` is descriptive metadata. It is **not** automatically propagated when the agent calls downstream services such as `IChatClient`.
+
+- Good, because it keeps a clean separation of concerns: agent/session-level metadata vs. per-run options.
+- Good, because it avoids unintended side effects — metadata added for discovery or hosting won't leak into LLM requests.
+- Good, because per-run extensibility is already served by `AgentRunOptions.AdditionalProperties` (see [ADR 0014](0014-feature-collections.md)), so there is no gap.
+- Neutral, because users who want to pass agent metadata to the chat client can still do so manually via `AgentRunOptions`.
+
+### Option 2 — Passed down the stack
+
+`AdditionalProperties` on `AIAgent` and `AgentSession` are automatically merged into `ChatOptions.AdditionalProperties` (or similar) when `ChatClientAgent` invokes the underlying `IChatClient`.
+
+- Good, because it provides an automatic way to send agent-level configuration to the LLM provider.
+- Bad, because it conflates metadata (describing the agent) with operational parameters (controlling LLM behavior), leading to potential confusion.
+- Bad, because it risks leaking unrelated metadata into LLM calls (e.g., hosting tags, discovery URLs).
+- Bad, because it would be `ChatClientAgent`-specific behavior on a base-class property, creating inconsistency for non-`ChatClientAgent` implementations.
+- Bad, because it duplicates the purpose of `AgentRunOptions.AdditionalProperties`, which already serves as the per-run extensibility point for passing data down the stack.
+
+## Serialization Considerations
+
+`AIAgent` instances are not typically serialized, so `AdditionalProperties` on `AIAgent` does not raise serialization concerns.
+
+`AgentSession` instances, however, are routinely serialized and deserialized — for example, to persist conversation state across application restarts. Adding `AdditionalProperties` to `AgentSession` introduces a serialization challenge: `AdditionalPropertiesDictionary` is a `Dictionary<string, object?>`, and `object?` values do not carry enough type information for the JSON deserializer to reconstruct the original CLR types.
+
+### Default behavior — JsonElement round-tripping
+
+By default, when an `AgentSession` with `AdditionalProperties` is serialized and later deserialized, any complex objects stored as values in the dictionary will be deserialized as `JsonElement` rather than their original types. This is the same behavior exhibited by `ChatMessage.AdditionalProperties` and other `AdditionalPropertiesDictionary` usages in `Microsoft.Extensions.AI`, and is the approach we will follow.
+
+### Custom serialization via JsonSerializerOptions
+
+`AIAgent.SerializeSessionAsync` and `AIAgent.DeserializeSessionAsync` already accept an optional `JsonSerializerOptions` parameter. Users who need strongly-typed round-tripping of `AdditionalProperties` values can supply custom options with appropriate converters or type info resolvers. This is non-trivial to implement but provides full control over deserialization behavior when needed.
+
+## More Information
+
+- [ADR 0014 — Feature Collections](0014-feature-collections.md) established that `AdditionalProperties` on `AgentRunOptions` serves as the per-run extensibility mechanism. The proposed agent-level and session-level properties serve a complementary, distinct purpose: static metadata describing the agent or session itself.
+- `AdditionalPropertiesDictionary` is defined in `Microsoft.Extensions.AI` and is already a dependency of `Microsoft.Agents.AI.Abstractions`. No new package references are needed.
+- Type-safe access is available via the existing `AdditionalPropertiesExtensions` helper methods (`Add<T>`, `TryGetValue<T>`, `Contains<T>`, `Remove<T>`), which use `typeof(T).FullName` as the dictionary key.

docs/decisions/0018-agentthread-serialization.md

@@ -0,0 +1,163 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+contact: westey-m
+date: 2026-02-25
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
+consulted: 
+informed:
+---
+
+# AgentSession serialization
+
+## Context and Problem Statement
+
+Serializing AgentSessions is done today by calling SerializeSession on the AIAgent instance and deserialization
+is done via the DeserializeSession method on the AIAgent instance.
+
+This approach has some drawbacks:
+
+1. It requires each AgentSession implementation to implement its own serialization logic. This can lead to inconsistencies and errors if not done correctly.
+1. It means that only one serialization format can be supported at a time. If we want to support multiple formats (e.g., JSON, XML, binary), we would need to implement separate serialization logic for each format.
+1. It is not possible to serialize and deserialize lists of AgentSessions, since each need to be handled individually.
+1. Users may not realise that they need to call these specific methods to serialize/deserialize AgentSessions.
+
+The reason why this approach was chosen initially is that AgentSessions may have behaviors that are attached to them and only the agent knows what behaviors to attach.
+These behaviors also have their own state that are attached to the AgentSession.
+The behaviors may have references to SDKs or other resources that cannot be created via standard deserialization mechanisms.
+E.g. an AgentSession may have a custom ChatMessageStore that knows how to store chat history in a specific storage backend and has a reference to the SDK client for that backend.
+When deserializing the AgentSession, we need to make sure that the ChatMessageStore is created with the correct SDK client.
+
+## Decision Drivers
+
+- A. Ability to continue to support custom behaviors (AIContextProviders / ChatHistoryProviders).
+- B. Ability to serialize and deserialize AgentSessions via standard serialization mechanisms, e.g. JsonSerializer.Serialize and JsonSerializer.Deserialize.
+- C. Ability for the caller to access custom providers.
+
+## Considered Options
+
+- Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
+- Option 2: Separate state from behavior, and only have state on AgentSession
+- Option 3: Keep the current approach of custom Serialize/Deserialize methods
+
+### Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
+
+Decision Drivers satisfied: A, B and C (C only partially)
+
+Have separate properties on the AgentSession for state and behavior and mark the behavior property with [JsonIgnore].
+After deserializing the AgentSession, the behavior is null and when the AgentSession is first used by the Agent, the behavior is created and attached to the AgentSession.
+
+This requires polymorphic deserialization to be supported, so that the correct AgentSession subclass and the correct behavior state is created during deserialization.
+Since the implementations for AgentSessions and their behaviors are not all known at compile time, we need a way to register custom AgentSession types and their corresponding behavior types for serialization with System.Text.Json on our JsonUtilities helpers.
+
+A drawback of this approach is that the AgentSession is in an incomplete state after deserialization until it is first used,
+so if a user was to call `GetService<MyBehavior>()` on the AgentSession before it is used by the Agent, it would return null.
+
+Behaviors like ChatMessageStore and AIContextProviders would need to change to support taking state as input and exposing state publicly.
+
+```csharp
+public class ChatClientAgentSession
+{
+    ...
+    public ChatMessageStoreState ChatMessageStoreState { get; }
+    public ChatMessageStore? ChatMessageStore { get; }
+    ...
+}
+
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonDerivedType(typeof(InMemoryChatMessageStoreState), nameof(InMemoryChatMessageStoreState))]
+public abstract class ChatMessageStoreState
+{
+}
+public class InMemoryChatMessageStoreState : ChatMessageStoreState
+{
+    public IList<ChatMessage> Messages { get; set; } = [];
+}
+
+public abstract class ChatMessageStore<TState>
+    where TState : ChatMessageStoreState
+{
+    ...
+    public abstract TState State { get; }
+    ...
+}
+
+public sealed class InMemoryChatMessageStore : ChatMessageStore<InMemoryChatMessageStoreState>, IList<ChatMessage>
+{
+    private readonly InMemoryChatMessageStoreState _state;
+
+    public InMemoryChatMessageStore(InMemoryChatMessageStoreState? state)
+    {
+        this._state = state ?? new InMemoryChatMessageStoreState();
+    }
+
+    public override InMemoryChatMessageStoreState State => this._state;
+
+    ...
+}
+```
+
+ChatClientAgent factories would need to change to support creating behaviors based on state:
+
+```csharp
+    public Func<ChatMessageStoreFactoryContext, ChatMessageStore>? ChatMessageStoreFactory { get; set; }
+
+    public class ChatMessageStoreFactoryContext
+    {
+        public ChatMessageStoreState? State { get; set; }
+    }
+```
+
+The run behavior of the ChatClientAgent would be as follows:
+
+1. If an AgentSession is provided, check if the ChatMessageStore property is null.
+1. If it is, check if the ChatMessageStoreState property is null.
+    1. If ChatMessageStoreState is null, check if there is a provided ChatMessageStoreFactory.
+        1. If there is, call it with a ChatMessageStoreFactoryContext containing null State to create a default ChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
+        2. If there is not, create a default InMemoryChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
+    1. If ChatMessageStoreState is not null, check if there is a provided ChatMessageStoreFactory.
+        1. If there is, call it with a ChatMessageStoreFactoryContext containing the State to create a ChatMessageStore behavior based on the state.
+        2. If there is not, create an InMemoryChatMessageStore behavior based on the State.
+
+### Option 2: Separate state from behavior, and only have state on AgentSession
+
+Decision Drivers satisfied: A, B and C.
+
+This is similar to Option 1 but instead of having a behavior property on the AgentSession, we only have a StateBag property on the AgentSession.
+Behaviors really make more sense to live with the agent rather than the Session, but state should live on the session.
+When the AgentSession is used by the Agent, the Agent runs the behaviors against the Session, and the behavior stores it's state on the Session StateBag.
+
+This means that users are unable to access the behavior from the AgentSession, e.g. via `AgentSession.GetService<TBehavior>()`.
+
+However, the behaviors can be public properties on the Agent or can be retrieved from the agent via `AIAgent.GetService<MyAIContextProvider>()`.
+
+```csharp
+public class AgentSession
+{
+    ...
+    public AgentSessionStateBag StateBag { get; protected set; } = new();
+    ...
+}
+```
+
+### Option 3: Keep the current approach of custom Serialize/Deserialize methods
+
+Decision Drivers satisfied: A and C
+
+This option keeps the current approach of having custom Serialize/Deserialize methods on the AgentSession and AIAgent.
+
+## Decision Outcome
+
+Chosen option:
+
+**Option 2** — separate state from behavior, with only state on the AgentSession — because it satisfies all decision drivers and provides the cleanest separation of concerns. Since not all AgentSession implementations have yet been cleanly separated from their behaviors, AIAgent.SerializeSession and AIAgent.DeserializeSession is kept for the time being, but most session types can be serialized and deserialized directly using JsonSerializer.
+
+### Consequences
+
+- Good, because providers are fully stateless — the same provider instance works correctly across any number of concurrent sessions without risk of state leakage.
+- Good, because `AgentSession` can be serialized and deserialized with standard `System.Text.Json` mechanisms, satisfying decision driver B.
+- Good, because the generic `StateBag` is extensible — new providers can store arbitrary state without requiring changes to the session class.
+- Good, because users can access providers via the agent (e.g. `agent.GetService<InMemoryChatHistoryProvider>()`) satisfying decision driver C.
+- Good, because sessions are always in a complete and valid state after deserialization — there is no "incomplete until first use" problem as in Option 1.
+- Neutral, because providers cannot be accessed directly from the session; callers must go through the agent. This is a minor usability trade-off but keeps the session focused on state only.
+- Bad, because each provider must be disciplined about using `ProviderSessionState<T>` and not storing session-specific data in instance fields. This is a correctness concern for custom provider implementers.

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/04-hosting/DurableAgents/`
+- 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/04-hosting/DurableAgents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/04-hosting/DurableAgents/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)

docs/features/vector-stores-and-embeddings/README.md

@@ -0,0 +1,390 @@
+# Vector Stores and Embeddings
+
+## Overview
+
+This feature ports the vector store abstractions, embedding generator abstractions, and their implementations from Semantic Kernel into Agent Framework. The ported code follows AF's coding standards, feels native to AF, and is structured to allow data models/schemas to be reusable across both frameworks. The embedding abstraction combines the best of SK's `EmbeddingGeneratorBase` and MEAI's `IEmbeddingGenerator<TInput, TEmbedding>`.
+
+| Capability | Description |
+| --- | --- |
+| Embedding generation | Generic embedding client abstraction supporting text, image, and audio inputs |
+| Vector store collections | CRUD operations on vector store collections (upsert, get, delete) |
+| Vector search | Unified search interface with `search_type` parameter (`"vector"`, `"keyword_hybrid"`) |
+| Data model decorator | `@vectorstoremodel` decorator for defining vector store data models (supports Pydantic, dataclasses, plain classes, dicts) |
+| Agent tools | `create_search_tool`, `create_upsert_tool`, `create_get_tool`, `create_delete_tool` for agent-usable vector store operations |
+| In-memory store | Zero-dependency vector store for testing and development |
+| 13+ connectors | Azure AI Search, Qdrant, Redis, PostgreSQL, MongoDB, Cosmos DB, Pinecone, Chroma, Weaviate, Oracle, SQL Server, FAISS |
+
+## Key Design Decisions
+
+### Embedding Abstractions (combining SK + MEAI)
+- **Both Protocol and Base class** (matching AF's `SupportsChatGetResponse` + `BaseChatClient` pattern):
+  - `SupportsGetEmbeddings` — Protocol for duck-typing
+  - `BaseEmbeddingClient` — ABC base class for implementations (similar to `BaseChatClient`)
+- **Generic input type** (`EmbeddingInputT`, default `str`) from MEAI — allows image/audio embeddings in the future
+- **Generic output type** (`EmbeddingT`, default `list[float]`) from MEAI — supports `list[float]`, `list[int]`, `bytes`, etc.
+- **Generic order**: `[EmbeddingInputT, EmbeddingT, EmbeddingOptionsT]` — options last, matching MEAI's `IEmbeddingGenerator<TInput, TEmbedding>` with options appended
+- **TypeVar naming convention**: Use `SuffixT` per AF standard (e.g., `EmbeddingInputT`, `EmbeddingT`, `ModelT`, `KeyT`)
+- `EmbeddingGenerationOptions` TypedDict (inspired by MEAI, matching AF's `ChatOptions` pattern) — `total=False`, includes `dimensions`, `model_id`. No `additional_properties` since each implementation extends with its own fields.
+- Protocol and base class are generic over input, output, and options: `SupportsGetEmbeddings[EmbeddingInputT, EmbeddingT, OptionsContraT]`, `BaseEmbeddingClient[EmbeddingInputT, EmbeddingT, OptionsCoT]`
+- **`Embedding[EmbeddingT]` type** in `_types.py` — a lightweight generic class (not Pydantic) with `vector: EmbeddingT`, `model_id: str | None`, `dimensions: int | None` (explicit or computed from vector), `created_at: datetime | None`, `additional_properties: dict[str, Any]`
+- **`GeneratedEmbeddings[EmbeddingT, EmbeddingOptionsT]` type** — a list-like container of `Embedding[EmbeddingT]` objects with `options: EmbeddingOptionsT | None` (stores the options used to generate), `usage: dict[str, Any] | None`, `additional_properties: dict[str, Any]`
+- **No numpy dependency** — return `list[float]` by default; users cast as needed
+
+### Vector Store Abstractions
+- **Port core abstractions without Pydantic for internal classes** — use plain classes
+- **Both Protocol and Base class** for vector store operations (matching AF pattern):
+  - `SupportsVectorUpsert` / `SupportsVectorSearch` — Protocols for duck-typing (follows `Supports<Capability>` naming convention)
+  - `BaseVectorCollection` / `BaseVectorSearch` — ABC base classes for implementations
+  - `BaseVectorStore` — ABC base class for store operations (factory for collections, no protocol needed)
+- **TypeVar naming convention**: `ModelT`, `KeyT`, `FilterT` (suffix T, per AF standard)
+- **Support Pydantic for user-facing data models** — the `@vectorstoremodel` decorator and `VectorStoreCollectionDefinition` should work with Pydantic models, dataclasses, plain classes, and dicts
+- **Remove SK-specific dependencies** — no `KernelBaseModel`, `KernelFunction`, `KernelParameterMetadata`, `kernel_function`, `PromptExecutionSettings`
+- **Embedding types in `_types.py`**, embedding protocol/base class in `_clients.py`
+- **All vector store specific types, enums, protocols, base classes** in `_vectors.py`
+- **Error handling** uses AF's exception hierarchy (e.g., `IntegrationException` variants)
+
+### Package Structure
+- **Embedding types** (`Embedding`, `GeneratedEmbeddings`, `EmbeddingGenerationOptions`) in `agent_framework/_types.py`
+- **Embedding protocol + base class** (`SupportsGetEmbeddings`, `BaseEmbeddingClient`) in `agent_framework/_clients.py`
+- **All vector store specific code** in a new `agent_framework/_vectors.py` module — this includes:
+  - Enums: `FieldTypes`, `IndexKind`, `DistanceFunction`
+  - `VectorStoreField`, `VectorStoreCollectionDefinition`
+  - `SearchOptions`, `SearchResponse`, `RecordFilterOptions`
+  - `@vectorstoremodel` decorator
+  - Serialization/deserialization protocols
+  - `VectorStoreRecordHandler`, `BaseVectorCollection`, `BaseVectorStore`, `BaseVectorSearch`
+  - `SupportsVectorUpsert`, `SupportsVectorSearch` protocols
+- **OpenAI embeddings** in `agent_framework/openai/` (built into core, like OpenAI chat)
+- **Azure OpenAI embeddings** in `agent_framework/azure/` (built into core, follows `AzureOpenAIChatClient` pattern)
+- **Each vector store connector** in its own AF package under `packages/`
+- **In-memory store** in core (no external deps)
+- **TextSearch and its implementations** (Brave, Google) — last phase, separate work
+
+## Naming: SK → AF
+
+### Names that change
+
+| SK Name | AF Name | Rationale |
+|---------|---------|-----------|
+| `VectorStoreCollection` | `BaseVectorCollection` | Drop redundant `Store`, add `Base` prefix per AF pattern |
+| `VectorStore` | `BaseVectorStore` | Add `Base` prefix per AF pattern |
+| `VectorSearch` | `BaseVectorSearch` | Add `Base` prefix per AF pattern |
+| `VectorSearchOptions` | `SearchOptions` | Shorter — context is already vector search |
+| `VectorSearchResult` | `SearchResponse` | Align with `ChatResponse`/`AgentResponse` |
+| `GetFilteredRecordOptions` | `RecordFilterOptions` | Shorter, more natural |
+| `EmbeddingGeneratorBase` | `BaseEmbeddingClient` | Matches AF `BaseChatClient` pattern |
+| `VectorStoreCollectionProtocol` | `SupportsVectorUpsert` | AF `Supports*` naming convention |
+| `VectorSearchProtocol` | `SupportsVectorSearch` | AF `Supports*` naming convention |
+| `__kernel_vectorstoremodel__` | `__vectorstoremodel__` | Drop SK `kernel` prefix |
+| `__kernel_vectorstoremodel_definition__` | `__vectorstoremodel_definition__` | Drop SK `kernel` prefix |
+| `search()` + `hybrid_search()` | `search(search_type=...)` | Single method with `Literal` parameter |
+| `SearchType` enum | `Literal["vector", "keyword_hybrid"]` | No enum, just a literal |
+| `KernelSearchResults` | `SearchResults` | Drop SK `Kernel` prefix (plural — container of `SearchResponse` items) |
+
+### Names that stay the same
+
+| Name | Location |
+|------|----------|
+| `@vectorstoremodel` | `_vectors.py` |
+| `VectorStoreField` | `_vectors.py` |
+| `VectorStoreCollectionDefinition` | `_vectors.py` |
+| `VectorStoreRecordHandler` | `_vectors.py` |
+| `FieldTypes` | `_vectors.py` |
+| `IndexKind` | `_vectors.py` |
+| `DistanceFunction` | `_vectors.py` |
+| `DISTANCE_FUNCTION_DIRECTION_HELPER` | `_vectors.py` |
+| `Embedding` | `_types.py` |
+| `GeneratedEmbeddings` | `_types.py` |
+| `EmbeddingGenerationOptions` | `_types.py` |
+| `SupportsGetEmbeddings` | `_clients.py` |
+
+### New AF-only names (no SK equivalent)
+
+| Name | Location | Purpose |
+|------|----------|---------|
+| `BaseEmbeddingClient` | `_clients.py` | ABC base for embedding implementations |
+| `EmbeddingInputT` | `_types.py` | TypeVar for generic embedding input (default `str`) |
+| `EmbeddingTelemetryLayer` | `observability.py` | MRO-based OTel tracing for embeddings |
+| `SupportsVectorUpsert` | `_vectors.py` | Protocol for collection CRUD |
+| `SupportsVectorSearch` | `_vectors.py` | Protocol for vector search |
+| `create_search_tool` | `_vectors.py` | Creates AF `FunctionTool` from vector search |
+
+## Source Files Reference (SK → AF mapping)
+
+### SK Source Files
+| SK File | Lines | Content |
+|---------|-------|---------|
+| `data/vector.py` | 2369 | All vector store abstractions, enums, decorator, search |
+| `data/_shared.py` | 184 | SearchOptions, KernelSearchResults, shared search types |
+| `data/text_search.py` | 349 | TextSearch base, TextSearchResult |
+| `connectors/ai/embedding_generator_base.py` | 50 | EmbeddingGeneratorBase ABC |
+| `connectors/in_memory.py` | 520 | InMemoryCollection, InMemoryStore |
+| `connectors/azure_ai_search.py` | 793 | Azure AI Search collection + store |
+| `connectors/azure_cosmos_db.py` | 1104 | Cosmos DB (Mongo + NoSQL) |
+| `connectors/redis.py` | 845 | Redis (Hashset + JSON) |
+| `connectors/qdrant.py` | 653 | Qdrant collection + store |
+| `connectors/postgres.py` | 987 | PostgreSQL collection + store |
+| `connectors/mongodb.py` | 633 | MongoDB Atlas collection + store |
+| `connectors/pinecone.py` | 691 | Pinecone collection + store |
+| `connectors/chroma.py` | 484 | Chroma collection + store |
+| `connectors/faiss.py` | 278 | FAISS (extends InMemory) |
+| `connectors/weaviate.py` | 804 | Weaviate collection + store |
+| `connectors/oracle.py` | 1267 | Oracle collection + store |
+| `connectors/sql_server.py` | 1132 | SQL Server collection + store |
+| `connectors/ai/open_ai/services/open_ai_text_embedding.py` | 91 | OpenAI embedding impl |
+| `connectors/ai/open_ai/services/open_ai_text_embedding_base.py` | 78 | OpenAI embedding base |
+| `connectors/brave.py` | ~200 | Brave TextSearch impl |
+| `connectors/google_search.py` | ~200 | Google TextSearch impl |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Embedding Abstractions & OpenAI Implementation ✅ DONE
+**Goal:** Establish the embedding generator abstraction and ship one working implementation.
+**Mergeable:** Yes — adds new types/protocols, no breaking changes.
+**Status:** Merged via PR #4153. Closes sub-issue #4163.
+
+#### 1.1 — Embedding types in `_types.py`
+- `EmbeddingInputT` TypeVar (default `str`) — generic input type for embedding generation
+- `EmbeddingT` TypeVar (default `list[float]`) — generic output embedding vector type
+- `Embedding[EmbeddingT]` generic class: `vector: EmbeddingT`, `model_id: str | None`, `dimensions: int | None` (explicit param or computed from vector length), `created_at: datetime | None`, `additional_properties: dict[str, Any]`
+- `GeneratedEmbeddings[EmbeddingT, EmbeddingOptionsT]` generic class: list-like container of `Embedding[EmbeddingT]` objects with `options: EmbeddingOptionsT | None` (the options used to generate), `usage: dict[str, Any] | None`, `additional_properties: dict[str, Any]`
+- `EmbeddingGenerationOptions` TypedDict (`total=False`): `dimensions: int`, `model_id: str` — follows the same pattern as `ChatOptions`. No `additional_properties` needed since it's a TypedDict and each implementation can extend with its own fields.
+
+#### 1.2 — Embedding generator protocol + base class in `_clients.py`
+- `SupportsGetEmbeddings(Protocol[EmbeddingInputT, EmbeddingT, OptionsContraT])`: generic over input, output, and options (all with defaults), `get_embeddings(values: Sequence[EmbeddingInputT], *, options: OptionsContraT | None = None) -> Awaitable[GeneratedEmbeddings[EmbeddingT]]`
+- `BaseEmbeddingClient(ABC, Generic[EmbeddingInputT, EmbeddingT, OptionsCoT])`: ABC base class mirroring `BaseChatClient` pattern
+  - `__init__` with `additional_properties`, etc.
+  - Abstract `get_embeddings(...)` for subclasses to implement directly (no `_inner_*` indirection — simpler than chat, no middleware needed)
+- `EmbeddingTelemetryLayer` in `observability.py` — MRO-based telemetry (no closure), `gen_ai.operation.name = "embeddings"`
+
+#### 1.3 — OpenAI embedding generator in `agent_framework/openai/` and `agent_framework/azure/`
+- `RawOpenAIEmbeddingClient` — implements `get_embeddings` via `_ensure_client()` factory
+- `OpenAIEmbeddingClient(OpenAIConfigMixin, EmbeddingTelemetryLayer[str, list[float], OptionsT], RawOpenAIEmbeddingClient[OptionsT])` — full client with config + telemetry layers
+- `OpenAIEmbeddingOptions(EmbeddingGenerationOptions)` — extends with `encoding_format`, `user`
+- `AzureOpenAIEmbeddingClient` in `agent_framework/azure/` — follows `AzureOpenAIChatClient` pattern with `AzureOpenAIConfigMixin`, `load_settings`, Entra ID credential support
+- `AzureOpenAISettings` extended with `embedding_deployment_name` (env var: `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`)
+
+#### 1.4 — Tests and samples
+- Unit tests for types, protocol, base class, OpenAI client, Azure OpenAI client
+- Integration tests for OpenAI and Azure OpenAI (gated behind credentials check, `@pytest.mark.flaky`)
+- Samples in `samples/02-agents/embeddings/` — `openai_embeddings.py`, `azure_openai_embeddings.py`
+
+---
+
+### Phase 2: Embedding Generators for Existing Providers
+**Goal:** Add embedding generators to all existing AF provider packages that have chat clients.
+**Mergeable:** Yes — each is independent, added to existing provider packages.
+
+#### 2.1 — Azure AI Inference embedding (in `packages/azure-ai/`)
+#### 2.2 — Ollama embedding (in `packages/ollama/`)
+#### 2.3 — Anthropic embedding (in `packages/anthropic/`)
+#### 2.4 — Bedrock embedding (in `packages/bedrock/`)
+
+---
+
+### Phase 3: Core Vector Store Abstractions
+**Goal:** Establish all vector store types, enums, the decorator, collection definition, and base classes.
+**Mergeable:** Yes — adds new abstractions, no breaking changes.
+
+#### 3.1 — Vector store enums and field types in `_vectors.py`
+- `FieldTypes` enum: `KEY`, `VECTOR`, `DATA`
+- `IndexKind` enum: `HNSW`, `FLAT`, `IVF_FLAT`, `DISK_ANN`, `QUANTIZED_FLAT`, `DYNAMIC`, `DEFAULT`
+- `DistanceFunction` enum: `COSINE_SIMILARITY`, `COSINE_DISTANCE`, `DOT_PROD`, `EUCLIDEAN_DISTANCE`, `EUCLIDEAN_SQUARED_DISTANCE`, `MANHATTAN`, `HAMMING`, `DEFAULT`
+- No `SearchType` enum — use `Literal["vector", "keyword_hybrid"]` instead, per AF convention of avoiding unnecessary imports
+- `VectorStoreField` plain class (not Pydantic)
+- `VectorStoreCollectionDefinition` class (not Pydantic internally, but supports Pydantic models as input)
+- `SearchOptions` plain class — includes `score_threshold: float | None` for filtering results by score (see note below)
+- `SearchResponse` generic class
+- `RecordFilterOptions` plain class
+- `DISTANCE_FUNCTION_DIRECTION_HELPER` dict
+
+#### 3.2 — `@vectorstoremodel` decorator
+- Port from SK, works with dataclasses, Pydantic models, plain classes, and dicts
+- Sets `__vectorstoremodel__` and `__vectorstoremodel_definition__` on the class
+- Remove SK-specific `kernel` prefix (`__kernel_vectorstoremodel__` → `__vectorstoremodel__`)
+
+#### 3.3 — Serialization/deserialization protocols
+- `SerializeMethodProtocol`, `ToDictFunctionProtocol`, `FromDictFunctionProtocol`, etc.
+- Port the record handler logic but without Pydantic base class — use plain class or ABC
+
+#### 3.4 — Vector store base classes in `_vectors.py`
+- `VectorStoreRecordHandler` — internal base class that handles serialization/deserialization between user data models and store-specific formats, plus embedding generation for vector fields. Both `BaseVectorCollection` and `BaseVectorSearch` extend this.
+- `BaseVectorCollection(VectorStoreRecordHandler)` — base for collections
+  - Uses `SupportsGetEmbeddings` instead of `EmbeddingGeneratorBase`
+  - Not a Pydantic model — use `__init__` with explicit params
+  - `upsert`, `get`, `delete`, `ensure_collection_exists`, `collection_exists`, `ensure_collection_deleted`
+  - Async context manager support
+- `BaseVectorStore` — base for stores
+  - `get_collection`, `list_collection_names`, `collection_exists`, `ensure_collection_deleted`
+  - Async context manager support
+
+#### 3.5 — Vector search base class
+- `BaseVectorSearch(VectorStoreRecordHandler)` — base for vector search
+  - Single `search(search_type=...)` method with `search_type: Literal["vector", "keyword_hybrid"]` parameter — no enum, just a literal
+  - `_inner_search` abstract method for implementations
+  - Filter building with lambda parser (AST-based)
+  - Vector generation from values using embedding generator
+
+#### 3.6 — Protocols for type checking
+- `SupportsVectorUpsert` — Protocol for upsert/get/delete operations
+- `SupportsVectorSearch` — Protocol for vector search (single `search()` with `search_type` parameter)
+- No separate `SupportsVectorHybridSearch` — search type is a parameter, not a separate capability
+- No protocol for `VectorStore` — it's a factory for collections, not a capability to duck-type against
+
+#### 3.7 — Exception types
+- Add vector store exceptions under `IntegrationException` or create new branch
+- `VectorStoreException`, `VectorStoreOperationException`, `VectorSearchException`, `VectorStoreModelException`, etc.
+
+#### 3.8 — `create_search_tool` on `BaseVectorSearch`
+- Method on `BaseVectorSearch` that creates an AF `FunctionTool` from the vector search
+- Wraps the single `search()` method, passing `search_type` parameter
+- Accepts: `name`, `description`, `search_type`, `top`, `skip`, `filter`, `string_mapper`
+- The tool takes a query string, vectorizes it, searches, and returns results as strings
+- Can also be a standalone factory function in `_vectors.py`
+
+#### 3.9 — Tests for all vector store abstractions
+- Unit tests for enums, field types, collection definition
+- Unit tests for decorator
+- Unit tests for serialization/deserialization
+- Unit tests for record handler
+
+---
+
+### Phase 4: In-Memory Vector Store
+**Goal:** Provide a zero-dependency vector store for testing and development.
+**Mergeable:** Yes — first usable vector store.
+
+#### 4.1 — Port `InMemoryCollection` and `InMemoryStore` into core
+- Place in `agent_framework/_vectors.py` (alongside the abstractions)
+- Supports vector search (cosine similarity, etc.)
+- No external dependencies
+
+#### 4.2 — Port FAISS extension (optional, can be separate package)
+- Extends InMemory with FAISS indexing
+
+#### 4.3 — Tests and sample code
+
+---
+
+### Phase 5: Vector Store Connectors — Tier 1 (High Priority)
+**Goal:** Ship the most commonly used vector store connectors.
+**Mergeable:** Yes — each connector is independent.
+
+Each connector follows the AF package structure:
+- New package under `packages/`
+- Own `pyproject.toml`, `tests/`, lazy loading in core
+
+#### 5.1 — Azure AI Search (`packages/azure-ai-search/`)
+- May extend existing package or be new
+- `AzureAISearchCollection`, `AzureAISearchStore`
+
+#### 5.2 — Qdrant (`packages/qdrant/`)
+- New package
+- `QdrantCollection`, `QdrantStore`
+
+#### 5.3 — Redis (`packages/redis/`)
+- May extend existing redis package
+- `RedisCollection` (JSON + Hashset variants), `RedisStore`
+
+#### 5.4 — PostgreSQL/pgvector (`packages/postgres/`)
+- New package
+- `PostgresCollection`, `PostgresStore`
+
+---
+
+### Phase 6: Vector Store Connectors — Tier 2
+**Goal:** Ship remaining vector store connectors.
+**Mergeable:** Yes — each connector is independent.
+
+#### 6.1 — MongoDB Atlas (`packages/mongodb/`)
+#### 6.2 — Azure Cosmos DB (`packages/azure-cosmos-db/`)
+- Cosmos Mongo + Cosmos NoSQL
+#### 6.3 — Pinecone (`packages/pinecone/`)
+#### 6.4 — Chroma (`packages/chroma/`)
+#### 6.5 — Weaviate (`packages/weaviate/`)
+
+---
+
+### Phase 7: Vector Store Connectors — Tier 3
+**Goal:** Ship niche or less common connectors.
+**Mergeable:** Yes — each connector is independent.
+
+#### 7.1 — Oracle (`packages/oracle/`)
+#### 7.2 — SQL Server (`packages/sql-server/`)
+#### 7.3 — FAISS (`packages/faiss/` or in core extending InMemory)
+
+> **Note:** When implementing any SQL-based connector (PostgreSQL, SQL Server, SQLite, Cosmos DB), review the .NET MEVD changes made by @roji (Shay Rojansky) in SK for design patterns, query building, filter translation, and feature parity: https://github.com/microsoft/semantic-kernel/pulls?q=is%3Apr+author%3Aroji+is%3Aclosed
+
+---
+
+### Phase 8: Vector Store CRUD Tools
+**Goal:** Provide a full set of agent-usable tools for CRUD operations on vector store collections.
+**Mergeable:** Yes — adds tools without changing existing APIs.
+
+#### 8.1 — `create_upsert_tool` — tool for upserting records into a collection
+#### 8.2 — `create_get_tool` — tool for retrieving records by key
+- Key-based lookup only (by primary key), not a search tool
+- Documentation must clearly distinguish this from `create_search_tool`: get_tool retrieves specific records by their known key, while search_tool performs similarity/filtered search across the collection
+- Consider if this overlaps with filtered search and document when to use which
+#### 8.3 — `create_delete_tool` — tool for deleting records by key
+#### 8.4 — Tests and samples for CRUD tools
+
+---
+
+### Phase 9: Additional Embedding Implementations (New Providers)
+**Goal:** Provide embedding generators for providers that don't yet have AF packages.
+**Mergeable:** Yes — each is independent, new packages.
+
+#### 9.1 — HuggingFace/ONNX embedding (new package or lab)
+#### 9.2 — Mistral AI embedding (new package)
+#### 9.3 — Google AI / Vertex AI embedding (new package)
+#### 9.4 — Nvidia embedding (new package)
+
+---
+
+### Phase 10: TextSearch Abstractions & Implementations (Separate Work)
+**Goal:** Port text search (non-vector) abstractions and implementations.
+**Mergeable:** Yes — independent of vector stores.
+
+#### 10.1 — TextSearch base class and types
+- `SearchOptions`, `SearchResponse`, `TextSearchResult`
+- `TextSearch` base class with `search()` method
+- `create_search_function()` for kernel integration (may need AF equivalent)
+
+#### 10.2 — Brave Search implementation
+#### 10.3 — Google Search implementation
+#### 10.4 — Vector store text search bridge (connecting VectorSearch to TextSearch interface)
+
+---
+
+## Key Considerations
+
+1. **No Pydantic for internal classes**: All AF internal classes should use plain classes. Pydantic is only used for user-facing input validation (e.g., vector store data models).
+
+2. **Protocol + Base class**: Follow AF's pattern of both a `Protocol` for duck-typing and a `Base` ABC for implementation, matching how `SupportsChatGetResponse` + `BaseChatClient` works.
+
+3. **Exception hierarchy**: Use AF's `IntegrationException` branch for vector store operations, since vector stores are external dependencies.
+
+4. **`from __future__ import annotations`**: Required in all files per AF coding standard.
+
+5. **No `**kwargs` escape hatches in public APIs**: For user-facing interfaces, use explicit named parameters per AF coding standard. Internal implementation details (e.g., cooperative multiple inheritance / MRO patterns) may use `**kwargs` where necessary, as long as they are not exposed in public signatures.
+
+6. **Lazy loading**: Connector packages use `__getattr__` lazy loading in core provider folders.
+
+7. **Reusable data models**: The `@vectorstoremodel` decorator and `VectorStoreCollectionDefinition` should be agnostic enough to work with both SK and AF. The core types (`FieldTypes`, `IndexKind`, `DistanceFunction`, `VectorStoreField`) should be identical or easily mapped.
+
+8. **`create_search_tool`**: The AF-native equivalent of SK's `create_search_function`. Instead of creating a `KernelFunction`, this creates an AF `FunctionTool` (via the `@tool` decorator pattern) from a vector search. This allows agents to use vector search as a tool during conversations. Design:
+   - `create_search_tool(name, description, search_type, ...)` → returns a `FunctionTool` that wraps `VectorSearch.search(search_type=...)`
+   - The tool accepts a query string, performs embedding + vector search, and returns results as strings
+   - Supports configurable string mappers, filter functions, top/skip defaults
+   - Lives in `_vectors.py` as a method on `BaseVectorSearch` and/or as a standalone factory function
+
+9. **CRUD tools**: A full set of create/read/update/delete tools for vector store collections, allowing agents to manage data in vector stores. Design:
+   - `create_upsert_tool(...)` → tool for upserting records
+   - `create_get_tool(...)` → tool for retrieving records by key
+   - `create_delete_tool(...)` → tool for deleting records
+   - These are separate from search and are placed in a later phase
+
+10. **Score threshold filtering**: `SearchOptions` includes `score_threshold: float | None` to filter search results by relevance score (ref: [SK .NET PR #13501](https://github.com/microsoft/semantic-kernel/pull/13501)). The semantics depend on the distance function: for similarity functions (cosine similarity, dot product), results *below* the threshold are filtered out; for distance functions (cosine distance, euclidean), results *above* the threshold are filtered out. Use `DISTANCE_FUNCTION_DIRECTION_HELPER` to determine direction. Connectors should implement this natively where the database supports it, falling back to client-side post-filtering otherwise.

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

@@ -19,8 +19,8 @@
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.5" />
-    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.5" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0-beta.1" />
+    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="2.0.0-beta.1" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.8" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
     <PackageVersion Include="Azure.Identity" Version="1.17.1" />
@@ -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.ClientModel" Version="1.9.0" />
     <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 -->
@@ -58,12 +58,17 @@
     <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
     <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
     <!-- Microsoft.AspNetCore.* -->
+    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
     <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 +76,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 +94,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.29" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -99,7 +104,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 +113,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.4.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.4.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.4.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" />
@@ -182,4 +187,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/README.md

@@ -1,26 +1,20 @@
 # Get Started with Microsoft Agent Framework for C# Developers
 
-## Samples
-
-- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
-
 ## Quickstart
 
 ### 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."));
@@ -28,9 +22,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 
 ## Examples & Samples
 
-- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started with Agents](./samples/02-agents/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./samples/02-agents/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./samples/03-workflows): advanced multi-agent patterns and workflow orchestration
 
 ## Agent Framework Documentation
 

dotnet/agent-framework-dotnet.slnx

@@ -5,216 +5,189 @@
     <BuildType Name="Release" />
   </Configurations>
   <Folder Name="/Samples/">
+    <File Path="samples/AGENTS.md" />
     <File Path="samples/README.md" />
   </Folder>
-  <Folder Name="/Samples/A2AClientServer/">
-    <File Path="samples/A2AClientServer/README.md" />
-    <Project Path="samples/A2AClientServer/A2AClient/A2AClient.csproj" />
-    <Project Path="samples/A2AClientServer/A2AServer/A2AServer.csproj" />
+  <Folder Name="/Samples/01-get-started/">
+    <Project Path="samples/01-get-started/01_hello_agent/01_hello_agent.csproj" />
+    <Project Path="samples/01-get-started/02_add_tools/02_add_tools.csproj" />
+    <Project Path="samples/01-get-started/03_multi_turn/03_multi_turn.csproj" />
+    <Project Path="samples/01-get-started/04_memory/04_memory.csproj" />
+    <Project Path="samples/01-get-started/05_first_workflow/05_first_workflow.csproj" />
+    <Project Path="samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj" />
   </Folder>
-  <Folder Name="/Samples/AgentWebChat/">
-    <Project Path="samples/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
-    <Project Path="samples/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
-    <Project Path="samples/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
-    <Project Path="samples/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
+  <Folder Name="/Samples/02-agents/">
+    <File Path="samples/02-agents/README.md" />
   </Folder>
-  <Folder Name="/Samples/AGUIClientServer/">
-    <Project Path="samples/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
-    <Project Path="samples/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
-    <Project Path="samples/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
+  <Folder Name="/Samples/02-agents/AgentProviders/">
+    <File Path="samples/02-agents/AgentProviders/README.md" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
   </Folder>
-  <Folder Name="/Samples/Durable/" />
-  <Folder Name="/Samples/Durable/Agents/" />
-  <Folder Name="/Samples/Durable/Agents/AzureFunctions/">
-    <File Path="samples/Durable/Agents/AzureFunctions/.editorconfig" />
-    <File Path="samples/Durable/Agents/AzureFunctions/README.md" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
+  <Folder Name="/Samples/02-agents/Agents/">
+    <File Path="samples/02-agents/Agents/README.md" />
+    <Project Path="samples/02-agents/Agents/Agent_Step01_UsingFunctionToolsWithApprovals/Agent_Step01_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step02_StructuredOutput/Agent_Step02_StructuredOutput.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step03_PersistedConversations/Agent_Step03_PersistedConversations.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step04_3rdPartyChatHistoryStorage/Agent_Step04_3rdPartyChatHistoryStorage.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step05_Observability/Agent_Step05_Observability.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step06_DependencyInjection/Agent_Step06_DependencyInjection.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step07_AsMcpTool/Agent_Step07_AsMcpTool.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step08_UsingImages/Agent_Step08_UsingImages.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step09_AsFunctionTool/Agent_Step09_AsFunctionTool.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step10_BackgroundResponsesWithToolsAndPersistence/Agent_Step10_BackgroundResponsesWithToolsAndPersistence.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step11_Middleware/Agent_Step11_Middleware.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step12_Plugins/Agent_Step12_Plugins.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step13_ChatReduction/Agent_Step13_ChatReduction.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step14_BackgroundResponses/Agent_Step14_BackgroundResponses.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step15_DeepResearch/Agent_Step15_DeepResearch.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
   </Folder>
-  <Folder Name="/Samples/Durable/Agents/ConsoleApps/">
-    <File Path="samples/Durable/Agents/ConsoleApps/README.md" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
+  <Folder Name="/Samples/02-agents/DeclarativeAgents/">
+    <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/">
-    <File Path="samples/GettingStarted/README.md" />
+  <Folder Name="/Samples/02-agents/AGUI/">
+    <File Path="samples/02-agents/AGUI/README.md" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/A2A/">
-    <File Path="samples/GettingStarted/A2A/README.md" />
-    <Project Path="samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step01_GettingStarted/">
+    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentProviders/">
-    <File Path="samples/GettingStarted/AgentProviders/README.md" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step02_BackendTools/">
+    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Agents/">
-    <File Path="samples/GettingStarted/Agents/README.md" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step01_Running/Agent_Step01_Running.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step02_MultiturnConversation/Agent_Step02_MultiturnConversation.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Agent_Step07_3rdPartyChatHistoryStorage.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step08_Observability/Agent_Step08_Observability.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Agent_Step09_DependencyInjection.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step11_UsingImages/Agent_Step11_UsingImages.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step12_AsFunctionTool/Agent_Step12_AsFunctionTool.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step13_BackgroundResponsesWithToolsAndPersistence/Agent_Step13_BackgroundResponsesWithToolsAndPersistence.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step14_Middleware/Agent_Step14_Middleware.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step15_Plugins/Agent_Step15_Plugins.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Agent_Step16_ChatReduction.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Agent_Step18_DeepResearch.csproj" />
-    <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 Name="/Samples/02-agents/AGUI/Step03_FrontendTools/">
+    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/DeclarativeAgents/">
-    <Project Path="samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step04_HumanInLoop/">
+    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/">
-    <File Path="samples/GettingStarted/AGUI/README.md" />
+  <Folder Name="/Samples/02-agents/AgentSkills/">
+    <File Path="samples/02-agents/AgentSkills/README.md" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step01_GettingStarted/">
-    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
+    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step02_BackendTools/">
-    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/DevUI/">
+    <File Path="samples/02-agents/DevUI/README.md" />
+    <Project Path="samples/02-agents/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step03_FrontendTools/">
-    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithAnthropic/">
+    <File Path="samples/02-agents/AgentWithAnthropic/README.md" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step04_HumanInLoop/">
-    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithMemory/">
+    <File Path="samples/02-agents/AgentWithMemory/README.md" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step05_StateManagement/">
-    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithOpenAI/">
+    <File Path="samples/02-agents/AgentWithOpenAI/README.md" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/DevUI/">
-    <File Path="samples/GettingStarted/DevUI/README.md" />
-    <Project Path="samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithRAG/">
+    <File Path="samples/02-agents/AgentWithRAG/README.md" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithAnthropic/">
-    <File Path="samples/GettingStarted/AgentWithAnthropic/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
+  <Folder Name="/Samples/02-agents/FoundryAgents/">
+    <File Path="samples/02-agents/FoundryAgents/README.md" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step16_FileSearch/FoundryAgents_Step16_FileSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step17_OpenAPITools/FoundryAgents_Step17_OpenAPITools.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step18_BingCustomSearch/FoundryAgents_Step18_BingCustomSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step19_SharePoint/FoundryAgents_Step19_SharePoint.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step20_MicrosoftFabric/FoundryAgents_Step20_MicrosoftFabric.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step21_WebSearch/FoundryAgents_Step21_WebSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step22_MemorySearch/FoundryAgents_Step22_MemorySearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step23_LocalMCP/FoundryAgents_Step23_LocalMCP.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithMemory/">
-    <File Path="samples/GettingStarted/AgentWithMemory/README.md" />
-    <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" />
+  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
+    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
-    <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+  <Folder Name="/Samples/02-agents/Observability/">
+    <Project Path="samples/02-agents/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
   </Folder>
-  <Folder Name="/Samples/Purview/" />
-  <Folder Name="/Samples/Purview/AgentWithPurview/">
-    <Project Path="samples/Purview/AgentWithPurview/AgentWithPurview.csproj" />
+  <Folder Name="/Samples/03-workflows/">
+    <File Path="samples/03-workflows/README.md" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithRAG/">
-    <File Path="samples/GettingStarted/AgentWithRAG/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
+  <Folder Name="/Samples/03-workflows/Concurrent/">
+    <Project Path="samples/03-workflows/Concurrent/Concurrent/Concurrent.csproj" />
+    <Project Path="samples/03-workflows/Concurrent/MapReduce/MapReduce.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/FoundryAgents/">
-    <File Path="samples/GettingStarted/FoundryAgents/README.md" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
-    <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" />
+  <Folder Name="/Samples/03-workflows/ConditionalEdges/">
+    <Project Path="samples/03-workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
+    <Project Path="samples/03-workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
+    <Project Path="samples/03-workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
-    <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
+  <Folder Name="/Samples/03-workflows/Declarative/">
+    <File Path="samples/03-workflows/Declarative/README.md" />
+    <Project Path="samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
+    <Project Path="samples/03-workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
+    <Project Path="samples/03-workflows/Declarative/DeepResearch/DeepResearch.csproj" />
+    <Project Path="samples/03-workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
+    <Project Path="samples/03-workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
+    <Project Path="samples/03-workflows/Declarative/FunctionTools/FunctionTools.csproj" />
+    <Project Path="samples/03-workflows/Declarative/GenerateCode/GenerateCode.csproj" />
+    <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
+    <Project Path="samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
+    <Project Path="samples/03-workflows/Declarative/ToolApproval/ToolApproval.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Observability/">
-    <Project Path="samples/GettingStarted/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/">
-    <File Path="samples/GettingStarted/Workflows/README.md" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Concurrent/">
-    <Project Path="samples/GettingStarted/Workflows/Concurrent/Concurrent/Concurrent.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Concurrent/MapReduce/MapReduce.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/ConditionalEdges/">
-    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/">
-    <File Path="samples/GettingStarted/Workflows/Declarative/README.md" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/DeepResearch/DeepResearch.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/FunctionTools/FunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/GenerateCode/GenerateCode.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/InputArguments/InputArguments.csproj" />
-    <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" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
+  <Folder Name="/Samples/03-workflows/Declarative/Examples/">
     <File Path="../workflow-samples/CustomerSupport.yaml" />
     <File Path="../workflow-samples/DeepResearch.yaml" />
     <File Path="../workflow-samples/Marketing.yaml" />
@@ -222,60 +195,114 @@
     <File Path="../workflow-samples/README.md" />
     <File Path="../workflow-samples/wttr.json" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/SharedStates/">
-    <Project Path="samples/GettingStarted/Workflows/SharedStates/SharedStates.csproj" />
+  <Folder Name="/Samples/03-workflows/SharedStates/">
+    <Project Path="samples/03-workflows/SharedStates/SharedStates.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Loop/">
-    <Project Path="samples/GettingStarted/Workflows/Loop/Loop.csproj" />
+  <Folder Name="/Samples/03-workflows/Loop/">
+    <Project Path="samples/03-workflows/Loop/Loop.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Agents/">
-    <Project Path="samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
+  <Folder Name="/Samples/03-workflows/Agents/">
+    <Project Path="samples/03-workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
+    <Project Path="samples/03-workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
+    <Project Path="samples/03-workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
+    <Project Path="samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Checkpoint/">
-    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
+  <Folder Name="/Samples/03-workflows/Checkpoint/">
+    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
+    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
+    <Project Path="samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/HumanInTheLoop/">
-    <Project Path="samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
+  <Folder Name="/Samples/03-workflows/HumanInTheLoop/">
+    <Project Path="samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Observability/">
-    <Project Path="samples/GettingStarted/Workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
+  <Folder Name="/Samples/03-workflows/Observability/">
+    <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
+    <Project Path="samples/03-workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
+    <Project Path="samples/03-workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
-    <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" />
+  <Folder Name="/Samples/03-workflows/Visualization/">
+    <Project Path="samples/03-workflows/Visualization/Visualization.csproj" />
   </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/_Foundational/">
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/02_Streaming/02_Streaming.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/03_AgentsInWorkflows/03_AgentsInWorkflows.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/04_AgentWorkflowPatterns/04_AgentWorkflowPatterns.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/05_MultiModelService/05_MultiModelService.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/06_SubWorkflows.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/07_MixedWorkflowAgentsAndExecutors/07_MixedWorkflowAgentsAndExecutors.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj" />
+  <Folder Name="/Samples/03-workflows/_StartHere/">
+    <Project Path="samples/03-workflows/_StartHere/01_Streaming/01_Streaming.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/02_AgentsInWorkflows/02_AgentsInWorkflows.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/04_MultiModelService/04_MultiModelService.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/05_SubWorkflows/05_SubWorkflows.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors/06_MixedWorkflowAgentsAndExecutors.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/07_WriterCriticWorkflow/07_WriterCriticWorkflow.csproj" />
   </Folder>
-  <Folder Name="/Samples/HostedAgents/">
-    <Project Path="samples/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
-    <Project Path="samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
-    <Project Path="samples/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
+  <Folder Name="/Samples/04-hosting/" />
+  <Folder Name="/Samples/04-hosting/DurableAgents/" />
+  <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
+    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
+    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/README.md" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
   </Folder>
-  <Folder Name="/Samples/M365Agent/">
-    <Project Path="samples/M365Agent/M365Agent.csproj" />
+  <Folder Name="/Samples/04-hosting/DurableAgents/ConsoleApps/">
+    <File Path="samples/04-hosting/DurableAgents/ConsoleApps/README.md" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/A2A/">
+    <File Path="samples/04-hosting/A2A/README.md" />
+    <Project Path="samples/04-hosting/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
+    <Project Path="samples/04-hosting/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
+  </Folder>  
+  <Folder Name="/Samples/05-end-to-end/">
+    <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
+    <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
+    <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
+    <Project Path="samples/05-end-to-end/A2AClientServer/A2AClient/A2AClient.csproj" />
+    <Project Path="samples/05-end-to-end/A2AClientServer/A2AServer/A2AServer.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/AgentWebChat/">
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/AGUIClientServer/">
+    <File Path="samples/05-end-to-end/AGUIClientServer/README.md" />
+    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
+    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
+    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/HostedAgents/">
+    <Project Path="samples/05-end-to-end/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
+    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
+    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/AspNetAgentAuthorization/">
+    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/docker-compose.yml" />
+    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/README.md" />
+    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/Service/Service.csproj" />
+    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj" />
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
     <File Path=".gitignore" />
+    <File Path="AGENTS.md" />
     <File Path="Directory.Build.props" />
     <File Path="Directory.Build.targets" />
     <File Path="Directory.Packages.props" />
     <File Path="global.json" />
     <File Path="nuget.config" />
+    <File Path="README.md" />
   </Folder>
   <Folder Name="/Solution Items/.github/" />
   <Folder Name="/Solution Items/.github/upgrades/" />
@@ -307,6 +334,10 @@
     <File Path="../docs/decisions/0012-python-typeddict-options.md" />
     <File Path="../docs/decisions/0013-python-get-response-simplification.md" />
     <File Path="../docs/decisions/0014-feature-collections.md" />
+    <File Path="../docs/decisions/0015-agent-run-context.md" />
+    <File Path="../docs/decisions/0016-python-context-middleware.md" />
+    <File Path="../docs/decisions/0017-agent-additional-properties.md" />
+    <File Path="../docs/decisions/0018-agentthread-serialization.md" />
     <File Path="../docs/decisions/adr-short-template.md" />
     <File Path="../docs/decisions/adr-template.md" />
     <File Path="../docs/decisions/README.md" />
@@ -371,6 +402,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 +424,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 +436,6 @@
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
@@ -406,6 +443,8 @@
     <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.FoundryMemory/Microsoft.Agents.AI.FoundryMemory.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" />
@@ -416,9 +455,10 @@
     <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.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
     <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
   </Folder>
   <Folder Name="/Tests/" />
@@ -428,8 +468,9 @@
     <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.FoundryMemory.IntegrationTests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
@@ -443,13 +484,14 @@
     <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.FoundryMemory.UnitTests/Microsoft.Agents.AI.FoundryMemory.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" />
@@ -459,6 +501,7 @@
     <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" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/Microsoft.Agents.AI.Workflows.Generators.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.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>3</RCNumber>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260304.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260304.1</PackageVersion>
+    <GitTag>1.0.0-rc3</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/01-get-started/01_hello_agent/01_hello_agent.csproj

@@ -15,7 +15,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/01-get-started/01_hello_agent/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/01-get-started/02_add_tools/02_add_tools.csproj

@@ -15,7 +15,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/01-get-started/02_add_tools/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/01-get-started/03_multi_turn/03_multi_turn.csproj

@@ -15,7 +15,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/01-get-started/03_multi_turn/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/01-get-started/04_memory/04_memory.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.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/01-get-started/04_memory/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 IReadOnlyList<string>? _stateKeys;
         private readonly IChatClient _chatClient;
 
-        public UserInfoMemory(IChatClient chatClient, UserInfo? userInfo = null)
+        public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = 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 IReadOnlyList<string> StateKeys => this._stateKeys ??= [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/01-get-started/05_first_workflow/05_first_workflow.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj

@@ -0,0 +1,31 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>HostedAgent</AssemblyName>
+    <RootNamespace>HostedAgent</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>

dotnet/samples/01-get-started/06_host_your_agent/Program.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to host an AI agent with Azure Functions (DurableAgents).
+//
+// Prerequisites:
+//   - Azure Functions Core Tools
+//   - Azure OpenAI resource
+//
+// Environment variables:
+//   AZURE_OPENAI_ENDPOINT
+//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-4o-mini")
+//
+// Run with: func start
+// Then call: POST http://localhost:7071/api/agents/HostedAgent/run
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+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";
+
+// Set up an AI agent following the standard Microsoft Agent Framework pattern.
+// 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 a helpful assistant hosted in Azure Functions.",
+        name: "HostedAgent");
+
+// Configure the function app to host the AI agent.
+// This will automatically generate HTTP API endpoints for the agent.
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableAgents(options => options.AddAIAgent(agent, timeToLive: TimeSpan.FromHours(1)))
+    .Build();
+app.Run();

dotnet/samples/02-agents/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/02-agents/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/02-agents/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/02-agents/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/02-agents/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/02-agents/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/02-agents/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/02-agents/AgentProviders/Agent_With_Anthropic/Program.cs

@@ -7,7 +7,7 @@ using Anthropic.Foundry;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 
-string deploymentName = Environment.GetEnvironmentVariable("ANTHROPIC_DEPLOYMENT_NAME") ?? "claude-haiku-4-5";
+string deploymentName = Environment.GetEnvironmentVariable("ANTHROPIC_CHAT_MODEL_NAME") ?? "claude-haiku-4-5";
 
 // The resource is the subdomain name / first name coming before '.services.ai.azure.com' in the endpoint Uri
 // ie: https://(resource name).services.ai.azure.com/anthropic/v1/chat/completions
@@ -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/02-agents/AgentProviders/Agent_With_Anthropic/README.md

@@ -22,7 +22,7 @@ Set the following environment variables:
 
 ```powershell
 $env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
-$env:ANTHROPIC_DEPLOYMENT_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
+$env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```
 
 ### For Azure Foundry with API Key
@@ -35,7 +35,7 @@ Set the following environment variables:
 ```powershell
 $env:ANTHROPIC_RESOURCE="your-foundry-resource-name"  # Replace with your Azure Foundry resource name (subdomain before .services.ai.azure.com)
 $env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
-$env:ANTHROPIC_DEPLOYMENT_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
+$env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```
 
 ### For Azure Foundry with Azure CLI
@@ -47,7 +47,7 @@ Set the following environment variables:
 
 ```powershell
 $env:ANTHROPIC_RESOURCE="your-foundry-resource-name"  # Replace with your Azure Foundry resource name (subdomain before .services.ai.azure.com)
-$env:ANTHROPIC_DEPLOYMENT_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
+$env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```
 
 **Note**: When using Azure Foundry with Azure CLI, make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).