Initial plan

Fix readme path
Merge branch 'crickman/dotnet-sample-improvements' of https://github.com/microsoft/agent-framework into crickman/dotnet-sample-improvements
2026-06-16 21:04:09 +08:00 · 2026-02-23 16:16:37 +00:00 · 2026-02-22 12:36:55 -08:00 · 2026-02-21 12:50:15 -08:00 · 2026-02-21 12:45:32 -08:00 · 2026-02-21 12:39:18 -08:00
1466 changed files with 26310 additions and 8156 deletions
@@ -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/**

@@ -7,6 +7,13 @@ name: dotnet-build-and-test

 on:
  workflow_dispatch:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., a commit SHA from a PR)"
+        required: false
+        type: string
+        default: ""
  pull_request:
    branches: ["main", "feature*"]
  merge_group:
@@ -39,6 +46,8 @@ jobs:
      cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
    steps:
      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
      - uses: dorny/paths-filter@v3
        id: filter
        with:
@@ -76,6 +85,7 @@ jobs:
    steps:
      - uses: actions/checkout@v6
        with:
+            ref: ${{ inputs.checkout-ref }}
            persist-credentials: false
            sparse-checkout: |
              .
@@ -0,0 +1,106 @@
+#
+# This workflow allows manually running integration tests against an open PR or a branch.
+# Go to Actions → "Integration Tests (Manual)" → Run workflow → enter a PR number or branch name.
+#
+# It reuses the existing dotnet-build-and-test and python-merge-tests workflows,
+# passing a ref so they check out and test the correct code.
+#
+
+name: Integration Tests (Manual)
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr-number:
+        description: "PR number to run integration tests against (leave empty if using branch)"
+        required: false
+        type: string
+        default: ""
+      branch:
+        description: "Branch name to run integration tests against (leave empty if using PR number)"
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+  pull-requests: read
+  id-token: write
+
+concurrency:
+  group: integration-tests-manual-${{ github.event.inputs.pr-number || github.event.inputs.branch }}
+  cancel-in-progress: true
+
+jobs:
+  resolve-ref:
+    name: Resolve ref
+    runs-on: ubuntu-latest
+    outputs:
+      checkout-ref: ${{ steps.resolve.outputs.checkout-ref }}
+    steps:
+      - name: Resolve checkout ref
+        id: resolve
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.inputs.pr-number }}
+          BRANCH: ${{ github.event.inputs.branch }}
+          REPO: ${{ github.repository }}
+          REPO_OWNER: ${{ github.repository_owner }}
+        run: |
+          if [ -n "$PR_NUMBER" ] && [ -n "$BRANCH" ]; then
+            echo "::error::Please provide either a PR number or a branch name, not both."
+            exit 1
+          fi
+
+          if [ -z "$PR_NUMBER" ] && [ -z "$BRANCH" ]; then
+            echo "::error::Please provide either a PR number or a branch name."
+            exit 1
+          fi
+
+          if [ -n "$PR_NUMBER" ]; then
+            if ! echo "$PR_NUMBER" | grep -Eq '^[0-9]+$'; then
+              echo "::error::Invalid PR number. Only numeric values are allowed."
+              exit 1
+            fi
+
+            PR_DATA=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json state,headRepository,headRepositoryOwner)
+            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
+            HEAD_OWNER=$(echo "$PR_DATA" | jq -r '.headRepositoryOwner.login')
+
+            if [ "$PR_STATE" != "OPEN" ]; then
+              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
+              exit 1
+            fi
+
+            if [ "$HEAD_OWNER" != "$REPO_OWNER" ]; then
+              echo "::error::PR #$PR_NUMBER is from a fork ($HEAD_OWNER). Running integration tests against fork PRs is not allowed for security reasons."
+              exit 1
+            fi
+
+            echo "checkout-ref=refs/pull/$PR_NUMBER/head" >> "$GITHUB_OUTPUT"
+            echo "Running integration tests for PR #$PR_NUMBER"
+          else
+            if ! echo "$BRANCH" | grep -Eq '^[a-zA-Z0-9_./-]+$'; then
+              echo "::error::Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes are allowed."
+              exit 1
+            fi
+
+            echo "checkout-ref=$BRANCH" >> "$GITHUB_OUTPUT"
+            echo "Running integration tests for branch $BRANCH"
+          fi
+
+  dotnet-integration-tests:
+    name: .NET Integration Tests
+    needs: resolve-ref
+    uses: ./.github/workflows/dotnet-build-and-test.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit
+
+  python-integration-tests:
+    name: Python Integration Tests
+    needs: resolve-ref
+    uses: ./.github/workflows/python-merge-tests.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit
@@ -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,24 +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",
    "packages.core.agent_framework",
    "packages.core.agent_framework._workflows",
    "packages.purview.agent_framework_purview",
-    # Add more modules here as coverage improves:
-    # "packages.azure-ai-search.agent_framework_azure_ai_search",
-    # "packages.anthropic.agent_framework_anthropic",
+    "packages.anthropic.agent_framework_anthropic",
+    "packages.azure-ai-search.agent_framework_azure_ai_search",
+    "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
 }


@@ -62,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()
@@ -79,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")
@@ -93,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
@@ -114,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:
@@ -130,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% ❌".
@@ -144,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,
@@ -152,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).
@@ -165,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}"

@@ -187,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

@@ -2,6 +2,13 @@ name: Python - Merge - Tests

 on:
  workflow_dispatch:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., a commit SHA from a PR)"
+        required: false
+        type: string
+        default: ""
  pull_request:
    branches: ["main"]
  merge_group:
@@ -29,6 +36,8 @@ jobs:
      pythonChanges: ${{ steps.filter.outputs.python}}
    steps:
      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
      - uses: dorny/paths-filter@v3
        id: filter
        with:
@@ -76,6 +85,8 @@ jobs:
        working-directory: python
    steps:
      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -135,6 +146,8 @@ jobs:
        working-directory: python
    steps:
      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
      - name: Set up python and install the project
        id: python-setup
        uses: ./.github/actions/python-setup
@@ -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/03-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/02-agents/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/02-agents/providers/) | [.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/02-agents/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."));
@@ -165,9 +169,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram

 ### .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

@@ -1072,6 +1072,50 @@ Rationale for B1 over B2: Simpler is better. The whole state dict is passed to e
 > **Note on trust:** Since all `ContextProvider` instances reason over conversation messages (which may contain sensitive user data), they should be **trusted by default**. This is also why we allow all plugins to see all state - if a plugin is untrusted, it shouldn't be in the pipeline at all. The whole state dict is passed rather than isolated slices because plugins that handle messages already have access to the full conversation context.


+### Addendum (2026-02-17): Provider-scoped hook state and default source IDs
+
+This addendum introduces a **breaking change** that supersedes earlier references in this ADR where hooks received the
+entire `session.state` object as their `state` parameter.
+
+#### Hook state contract
+
+- `before_run` and `after_run` now receive a **provider-scoped** mutable state dict.
+- The framework passes `session.state.setdefault(provider.source_id, {})` to hook `state`.
+- Cross-provider/global inspection remains available through `session.state` on `AgentSession`.
+
+#### Session requirement and fallback behavior
+
+- Provider hooks must use session-backed scoped state; there is no ad-hoc `{}` fallback state.
+- If providers run without a caller-supplied session, the framework creates an internal run-scoped `AgentSession` and
+  passes provider-scoped state from that session.
+
+#### Migration guidance
+
+Migrate provider implementations and samples from nested access to scoped access:
+
+- `state[self.source_id]["key"]` → `state["key"]`
+- `state.setdefault(self.source_id, {})["key"]` → `state["key"]`
+
+#### DEFAULT_SOURCE_ID standardization
+
+Aligned with and extending [PR #3944](https://github.com/microsoft/agent-framework/pull/3944), all built-in/connector
+providers in this surface now define a `DEFAULT_SOURCE_ID` and allow constructor override via `source_id`.
+
+Naming convention:
+
+- snake_case
+- close to the provider class name
+- history providers may use `*_memory` where differentiation is useful
+
+Defaults introduced by this change:
+
+- `InMemoryHistoryProvider.DEFAULT_SOURCE_ID = "in_memory"`
+- `Mem0ContextProvider.DEFAULT_SOURCE_ID = "mem0"`
+- `RedisContextProvider.DEFAULT_SOURCE_ID = "redis"`
+- `RedisHistoryProvider.DEFAULT_SOURCE_ID = "redis_memory"`
+- `AzureAISearchContextProvider.DEFAULT_SOURCE_ID = "azure_ai_search"`
+
+
 ## Comparison to .NET Implementation

 The .NET Agent Framework provides equivalent functionality through a different structure. Both implementations achieve the same goals using idioms natural to their respective languages.
@@ -0,0 +1,48 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on durable agents documentation.
+
+## Scope
+
+This directory contains feature documentation for the durable agents integration. The source code and samples live elsewhere:
+
+- .NET implementation: `dotnet/src/Microsoft.Agents.AI.DurableTask/` and `dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/`
+- Python implementation: `python/packages/durabletask/` and `python/packages/azurefunctions/` (package `agent-framework-azurefunctions`)
+- .NET samples: `dotnet/samples/Durable/Agents/`
+- Python samples: `python/samples/04-hosting/durabletask/`
+- Official docs (Microsoft Learn): <https://learn.microsoft.com/agent-framework/integrations/azure-functions>
+
+## Document structure
+
+| File | Purpose |
+| --- | --- |
+| `README.md` | Main technical overview: architecture, hosting models, orchestration patterns, and links to samples. |
+| `durable-agents-ttl.md` | Deep-dive on session Time-To-Live (TTL) configuration and behavior. |
+
+Add new sibling documents when a topic is too detailed for the README (e.g., a new feature like reliable streaming or MCP tool exposure). Keep the README focused on orientation and link out to siblings for depth.
+
+## Writing guidelines
+
+- **Audience**: Developers already familiar with the Microsoft Agent Framework who want to understand what durability adds and how to use it.
+- **Host-agnostic first**: Durable agents work in console apps, Azure Functions, and any Durable Task–compatible host. Show host-agnostic patterns (plain orchestration functions, `IServiceCollection` registration) before Azure Functions–specific patterns. Avoid giving the impression that Azure Functions is the only hosting option.
+- **Both languages**: Always include C# and Python examples side by side. Keep them equivalent in functionality.
+- **Callout syntax**: Use GitHub-flavored callouts (`> [!NOTE]`, `> [!IMPORTANT]`, `> [!WARNING]`) rather than bold-text callouts (`> **Note:** ...`).
+- **Line length**: Do not wrap long lines. Rely on text viewers / renderers for line wrapping.
+- **Tables**: Use spaces around pipes in separator rows (`| --- |` not `|---|`).
+- **Code snippets**: Keep them minimal and self-contained. Omit boilerplate (using statements, environment variable reads) unless the snippet is specifically about setup.
+- **Cross-references**: Link to Microsoft Learn for conceptual background (Durable Entities, Durable Task Scheduler, Azure Functions). Link to sibling docs within this directory for feature deep-dives.
+
+## Linting
+
+Run markdownlint on all documents before committing, with line-length checks disabled:
+
+```bash
+markdownlint docs/features/durable-agents/ --disable MD013
+```
+
+## When to update these docs
+
+- A new durable agent feature is added (e.g., a new orchestration pattern, hosting model, or configuration option).
+- The public API surface changes in a way that affects how developers use durable agents.
+- New sample directories are added — update the sample links in README.md.
+- The official Microsoft Learn documentation is restructured — update external links.
@@ -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)
@@ -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`.
@@ -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) |
@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -1,5 +1,6 @@
 {
    "dotnet.defaultSolution": "agent-framework-dotnet.slnx",
    "git.openRepositoryInParentFolders": "always",
-    "chat.agent.enabled": true
+    "chat.agent.enabled": true,
+    "dotnet.automaticallySyncWithActiveItem": true
 }
@@ -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
@@ -42,7 +42,7 @@
    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.3" />
    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
    <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.1" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.3" />
    <PackageVersion Include="System.Text.Json" Version="10.0.3" />
    <PackageVersion Include="System.Threading.Channels" Version="10.0.3" />
    <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
@@ -63,6 +63,9 @@
    <!-- Microsoft.Extensions.* -->
    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.3.0" />
    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.3.0" />
    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
@@ -99,7 +102,7 @@
    <PackageVersion Include="A2A" Version="0.3.3-preview" />
    <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
    <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.8.0-preview.1" />
    <!-- Inference SDKs -->
    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5.1" />
    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
@@ -108,10 +111,10 @@
    <!-- Identity -->
    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
    <!-- Workflows -->
-    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.1.2.3" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.1.2.3" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.1.2.3" />
-    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.5.0-build.20251008-1002" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.8.1" />
    <!-- Durable Task -->
    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.18.0" />
    <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.18.0" />
@@ -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

@@ -7,214 +7,179 @@
  <Folder Name="/Samples/">
    <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_Step18_FileSearch/FoundryAgents_Step18_FileSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step19_OpenAPITools/FoundryAgents_Step19_OpenAPITools.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/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,51 +187,96 @@
    <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_AgentOrchestration_Chaining/01_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/02_AgentOrchestration_Concurrency/02_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/03_AgentOrchestration_Conditionals/03_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/04_AgentOrchestration_HITL/04_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/05_LongRunningTools/05_LongRunningTools.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/06_AgentAsMcpTool/06_AgentAsMcpTool.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/07_ReliableStreaming/07_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="/Solution Items/">
    <File Path=".editorconfig" />
@@ -405,7 +415,6 @@
    <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
    <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
    <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
    <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
@@ -413,19 +422,21 @@
    <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
    <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.FoundryMemory/Microsoft.Agents.AI.FoundryMemory.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
    <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
    <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
  </Folder>
  <Folder Name="/Tests/" />
@@ -435,11 +446,12 @@
    <Project Path="tests/AzureAI.IntegrationTests/AzureAI.IntegrationTests.csproj" />
    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
    <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
    <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj" />
@@ -450,18 +462,19 @@
    <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.UnitTests/Microsoft.Agents.AI.FoundryMemory.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
@@ -2,9 +2,11 @@
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
    <VersionPrefix>1.0.0</VersionPrefix>
-    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260212.1</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260212.1</PackageVersion>
-    <GitTag>1.0.0-preview.260212.1</GitTag>
+    <RCNumber>1</RCNumber>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260219.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260219.1</PackageVersion>
+    <GitTag>1.0.0-rc1</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -9,7 +9,7 @@
  </PropertyGroup>

  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
  </ItemGroup>

 </Project>
@@ -36,7 +36,7 @@
  </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" />
+    <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>
@@ -10,7 +10,7 @@ This sample demonstrates how to use the Durable Agent Framework (DAFx) to create

 ## Environment Setup

-See the [README.md](../README.md) file in the parent directory for more information on how to configure the environment, including how to install and run common sample dependencies.
+See the [README.md](../../04-hosting/DurableAgents/AzureFunctions/README.md) file in the parent directory for more information on how to configure the environment, including how to install and run common sample dependencies.

 ## Running the Sample

--- a/Show More
+++ b/Show More