Add circular edges sample.

Removed unused using statement.
Removed unused reference.
2026-06-16 21:04:09 +08:00 · 2026-02-23 14:13:30 -08:00 · 2026-02-23 13:04:24 -08:00 · 2026-02-23 12:02:37 -08:00 · 2026-02-23 11:49:29 -08:00 · 2026-02-23 11:19:28 -08:00
1894 changed files with 82845 additions and 101419 deletions
@@ -1,19 +1,69 @@
 # GitHub Copilot Instructions

-Microsoft Agent Framework - a multi-language framework for building, orchestrating, and deploying AI agents.
+This repository contains both Python and C# code.
+All python code resides under the `python/` directory.
+All C# code resides under the `dotnet/` directory.

-## Repository Structure
+The purpose of the code is to provide a framework for building AI agents.

- `python/` - Python implementation → see [python/AGENTS.md](../python/AGENTS.md)
- `dotnet/` - C#/.NET implementation → see [dotnet/AGENTS.md](../dotnet/AGENTS.md)
- `docs/` - Design documents and architectural decision records
+When contributing to this repository, please follow these guidelines:

-## Architectural Decision Records (ADRs)
+## C# Code Guidelines

-ADRs in `docs/decisions/` capture significant design decisions and their rationale. They document considered alternatives, trade-offs, and the reasoning behind choices.
+Here are some general guidelines that apply to all code.

-**Templates:**
- `adr-template.md` - Full template with detailed sections
- `adr-short-template.md` - Abbreviated template for simpler decisions
+- The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
+- All public methods and classes should have XML documentation comments.
+- After adding, modifying or deleting code, run `dotnet build`, and then fix any reported build errors.
+- After adding or modifying code, run `dotnet format` to automatically fix any formatting errors.

-When proposing architectural changes, create an ADR to capture options considered and the decision rationale. See [docs/decisions/README.md](../docs/decisions/README.md) for the full process.
+### C# Sample Code Guidelines
+
+Sample code is located in the `dotnet/samples` directory.
+
+When adding a new sample, follow these steps:
+
+- The sample should be a standalone .net project in one of the subdirectories of the samples directory.
+- The directory name should be the same as the project name.
+- The directory should contain a README.md file that explains what the sample does and how to run it.
+- The README.md file should follow the same format as other samples.
+- The csproj file should match the directory name.
+- The csproj file should be configured in the same way as other samples.
+- The project should preferably contain a single Program.cs file that contains all the sample code.
+- The sample should be added to the solution file in the samples directory.
+- The sample should be tested to ensure it works as expected.
+- A reference to the new samples should be added to the README.md file in the parent directory of the new sample.
+
+The sample code should follow these guidelines:
+
+- Configuration settings should be read from environment variables, e.g. `var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");`.
+- Environment variables should use upper snake_case naming convention.
+- Secrets should not be hardcoded in the code or committed to the repository.
+- The code should be well-documented with comments explaining the purpose of each step.
+- The code should be simple and to the point, avoiding unnecessary complexity.
+- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions".
+- Ensure that all private classes are sealed
+- Use the Async suffix on the name of all async methods that return a Task or ValueTask.
+- Prefer defining variables using types rather than var, to help users understand the types involved.
+- Follow the patterns in the samples in the same directories where new samples are being added.
+- The structure of the sample should be as follows:
+  - The top of the Program.cs should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
+  - Then add a comment describing what the sample is demonstrating.
+  - Then add the necessary using statements.
+  - Then add the main code logic.
+  - Finally, add any helper methods or classes at the bottom of the file.
+
+### C# Unit Test Guidelines
+
+Unit tests are located in the `dotnet/tests` directory in projects with a `.UnitTests.csproj` suffix.
+
+Unit tests should follow these guidelines:
+
+- Use `this.` for accessing class members
+- Add Arrange, Act and Assert comments for each test
+- Ensure that all private classes, that are not subclassed, are sealed
+- Use the Async suffix on the name of all async methods
+- Use the Moq library for mocking objects where possible
+- Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway.
+- Avoid adding excessive comments to tests. Instead favour clear easy to understand code.
+- Follow the patterns in the unit tests in the same project or classes to which new tests are being added
@@ -1,13 +1,10 @@
 #!/usr/bin/env python3
 # Copyright (c) Microsoft. All rights reserved.
-"""Check Python test coverage against threshold for enforced targets.
+"""Check Python test coverage against threshold for enforced modules.

 This script parses a Cobertura XML coverage report and enforces a minimum
-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.
+coverage threshold on specific modules. Non-enforced modules are reported
+for visibility but don't block the build.

 Usage:
    python python-check-coverage.py <coverage-xml-path> <threshold>
@@ -21,31 +18,22 @@ import xml.etree.ElementTree as ET
 from dataclasses import dataclass

 # =============================================================================
-# ENFORCED TARGETS CONFIGURATION
+# ENFORCED MODULES CONFIGURATION
 # =============================================================================
-# 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.
+# 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.
 #
-# 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")
+# 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.
 # =============================================================================
-ENFORCED_TARGETS: set[str] = {
-    # Packages
+ENFORCED_MODULES: set[str] = {
    "packages.azure-ai.agent_framework_azure_ai",
-    "packages.core.agent_framework",
-    "packages.core.agent_framework._workflows",
-    "packages.purview.agent_framework_purview",
-    "packages.anthropic.agent_framework_anthropic",
-    "packages.azure-ai-search.agent_framework_azure_ai_search",
-    "packages.core.agent_framework.azure",
-    "packages.core.agent_framework.openai",
-    # Individual files (if you want to enforce specific files instead of whole packages)
-    "packages/core/agent_framework/observability.py",
-    # Add more targets here as coverage improves
+    # Add more modules here as coverage improves:
+    # "packages.core.agent_framework",
+    # "packages.core.agent_framework._workflows",
+    # "packages.anthropic.agent_framework_anthropic",
 }


@@ -72,21 +60,14 @@ class PackageCoverage:
        return self.branch_rate * 100


-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]:
+def parse_coverage_xml(xml_path: str) -> tuple[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, files_dict, overall_line_rate, overall_branch_rate).
+        A tuple of (packages_dict, overall_line_rate, overall_branch_rate).
    """
    tree = ET.parse(xml_path)
    root = tree.getroot()
@@ -96,7 +77,6 @@ def parse_coverage_xml(
    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")
@@ -111,43 +91,19 @@ def parse_coverage_xml(
        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
@@ -156,33 +112,14 @@ def parse_coverage_xml(
        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,
        )

-    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
+    return packages, overall_line_rate, overall_branch_rate


 def format_coverage_value(coverage: float, threshold: float, is_enforced: bool) -> str:
@@ -191,7 +128,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 target is enforced.
+        is_enforced: Whether this module is enforced.

    Returns:
        Formatted string like "85.5%" or "85.5% ✅" or "75.0% ❌".
@@ -205,7 +142,6 @@ 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,
@@ -214,7 +150,6 @@ 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).
@@ -228,25 +163,21 @@ 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 package targets first, then alphabetically
+    # Sort: enforced modules first, then alphabetically
    sorted_packages = sorted(
        packages.values(),
-        key=lambda p: (p.name not in ENFORCED_TARGETS, p.name),
+        key=lambda p: (p.name not in ENFORCED_MODULES, p.name),
    )

    for pkg in sorted_packages:
-        is_enforced = normalize_coverage_path(pkg.name) in enforced_targets
+        is_enforced = pkg.name in ENFORCED_MODULES
        enforced_marker = "[ENFORCED] " if is_enforced else ""
-        line_cov = format_coverage_value(
-            pkg.line_coverage_percent, threshold, is_enforced
-        )
+        line_cov = format_coverage_value(pkg.line_coverage_percent, threshold, is_enforced)
        lines_info = f"{pkg.lines_covered}/{pkg.lines_valid}"
        package_label = f"{enforced_marker}{pkg.name}"

@@ -254,98 +185,50 @@ 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 targets meet the coverage threshold.
+    """Check if all enforced modules meet the coverage threshold.

    Args:
        xml_path: Path to the Cobertura XML coverage report.
        threshold: Minimum required coverage percentage.

    Returns:
-        True if all enforced targets pass, False otherwise.
+        True if all enforced modules pass, False otherwise.
    """
-    packages, files, overall_line_rate, overall_branch_rate = parse_coverage_xml(
-        xml_path
-    )
+    packages, overall_line_rate, overall_branch_rate = parse_coverage_xml(xml_path)

-    print_coverage_table(
-        packages, files, threshold, overall_line_rate, overall_branch_rate
-    )
+    print_coverage_table(packages, threshold, overall_line_rate, overall_branch_rate)

-    # Check enforced targets
-    failed_targets: list[str] = []
-    missing_targets: list[str] = []
+    # Check enforced modules
+    failed_modules: list[str] = []
+    missing_modules: list[str] = []

-    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)
+    for module_name in ENFORCED_MODULES:
+        if module_name not in packages:
+            missing_modules.append(module_name)
            continue

-        if target_coverage.line_coverage_percent < threshold:
-            failed_targets.append(
-                f"{target_name} ({target_coverage.line_coverage_percent:.1f}%)"
-            )
+        pkg = packages[module_name]
+        if pkg.line_coverage_percent < threshold:
+            failed_modules.append(f"{module_name} ({pkg.line_coverage_percent:.1f}%)")

    # Report results
-    if missing_targets:
-        print(
-            f"\n❌ FAILED: Enforced targets not found in coverage report: {', '.join(missing_targets)}"
-        )
+    if missing_modules:
+        print(f"\n❌ FAILED: Enforced modules not found in coverage report: {', '.join(missing_modules)}")
        return False

-    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.")
+    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.")
        return False

-    if ENFORCED_TARGETS:
-        found_enforced = [
-            target
-            for target in ENFORCED_TARGETS
-            if target in packages or normalize_coverage_path(target) in files
-        ]
+    if ENFORCED_MODULES:
+        found_enforced = [m for m in ENFORCED_MODULES if m in packages]
        if found_enforced:
-            print(
-                f"\n✅ PASSED: All enforced targets meet the {threshold}% coverage threshold."
-            )
+            print(f"\n✅ PASSED: All enforced modules meet the {threshold}% coverage threshold.")

    return True

@@ -12,13 +12,13 @@ env:
  UV_CACHE_DIR: /tmp/.uv-cache

 jobs:
-  pre-commit-hooks:
-    name: Pre-commit Hooks
+  pre-commit:
+    name: Checks
    if: "!cancelled()"
    strategy:
      fail-fast: false
      matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.14"]
    runs-on: ubuntu-latest
    continue-on-error: true
    defaults:
@@ -37,106 +37,16 @@ jobs:
          python-version: ${{ matrix.python-version }}
          os: ${{ runner.os }}
        env:
+          # Configure a constant location for the uv cache
          UV_CACHE_DIR: /tmp/.uv-cache
      - uses: actions/cache@v5
        with:
-          path: ~/.cache/prek
-          key: prek|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
-      - uses: j178/prek-action@v1
-        name: Run Pre-commit Hooks (excluding poe-check)
-        env:
-          SKIP: poe-check
+          path: ~/.cache/pre-commit
+          key: pre-commit|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
+      - uses: pre-commit/action@v3.0.1
+        name: Run Pre-Commit Hooks
        with:
-          extra-args: --cd python --all-files
-
-  package-checks:
-    name: Package Checks
-    if: "!cancelled()"
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.10"]
-    runs-on: ubuntu-latest
-    continue-on-error: true
-    defaults:
-      run:
-        working-directory: ./python
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ matrix.python-version }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
-      - name: Run fmt, lint, pyright in parallel across packages
-        run: uv run poe check-packages
-
-  samples-markdown:
-    name: Samples & Markdown
-    if: "!cancelled()"
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.10"]
-    runs-on: ubuntu-latest
-    continue-on-error: true
-    defaults:
-      run:
-        working-directory: ./python
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ matrix.python-version }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
-      - name: Run samples lint
-        run: uv run poe samples-lint
-      - name: Run samples syntax check
-        run: uv run poe samples-syntax
-      - name: Run markdown code lint
-        run: uv run poe markdown-code-lint
-
-  mypy:
-    name: Mypy Checks
-    if: "!cancelled()"
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.10"]
-    runs-on: ubuntu-latest
-    continue-on-error: true
-    defaults:
-      run:
-        working-directory: ./python
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ matrix.python-version }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
+          extra_args: --config python/.pre-commit-config.yaml --all-files
      - name: Run Mypy
        env:
          GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}
@@ -96,7 +96,8 @@ jobs:
        uses: ./.github/actions/azure-functions-integration-setup
        id: azure-functions-setup
      - name: Test with pytest
-        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        timeout-minutes: 10
+        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout 900 --retries 3 --retry-delay 10
        working-directory: ./python
      - name: Test core samples
        timeout-minutes: 10
@@ -152,8 +153,8 @@ jobs:
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: Test with pytest
-        timeout-minutes: 15
-        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        timeout-minutes: 10
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
        working-directory: ./python
      - name: Test Azure AI samples
        timeout-minutes: 10
@@ -199,6 +199,8 @@ temp*/
 .tmp/
 .temp/

+agents.md
+
 # AI
 .claude/
 WARP.md
@@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 ### ✨ **Highlights**

 - **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/)
+  - [Python workflows](./python/samples/getting_started/workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/)
 - **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
  - [Labs directory](./python/packages/lab/)
 - **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
@@ -73,11 +73,11 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 - **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
 - **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
+  - [Python observability](./python/samples/getting_started/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
 - **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
-  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/)
+  - [Python examples](./python/samples/getting_started/agents/) | [.NET examples](./dotnet/samples/GettingStarted/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/getting_started/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)

 ### 💬 **We want your feedback!**

@@ -125,13 +125,12 @@ Create a simple Agent, using OpenAI Responses, that writes a haiku about the Mic

 ```c#
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-using Microsoft.Agents.AI;
+using System;
 using OpenAI;
-using OpenAI.Responses;

 // Replace the <apikey> with your OpenAI API key.
 var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient("gpt-4o-mini")
+    .GetOpenAIResponseClient("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."));
@@ -143,17 +142,14 @@ 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.ClientModel.Primitives;
-using Azure.Identity;
-using Microsoft.Agents.AI;
+using System;
 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") })
-    .GetResponsesClient("gpt-4o-mini")
+    .GetOpenAIResponseClient("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."));
@@ -163,9 +159,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram

 ### Python

- [Getting Started with Agents](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
- [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.)
- [Getting Started with Workflows](./python/samples/03-workflows): workflow creation and integration with agents
+- [Getting Started with Agents](./python/samples/getting_started/agents): basic agent creation and tool usage
+- [Chat Client Examples](./python/samples/getting_started/chat_client): direct chat client usage patterns
+- [Getting Started with Workflows](./python/samples/getting_started/workflows): basic workflow creation and integration with agents

 ### .NET

@@ -1,3 +1,3 @@
 # Declarative Agents

-This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/02-agents/declarative/).
+This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/getting_started/declarative/).
@@ -126,4 +126,4 @@ response = await client.get_response(

 Chosen option: **"Option 2: TypedDict with Generic Type Parameters"**, because it provides full type safety, excellent IDE support with autocompletion, and allows users to extend provider-specific options for their use cases. Extended this Generic to ChatAgents in order to also properly type the options used in agent construction and run methods.

-See [typed_options.py](../../python/samples/02-agents/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.
+See [typed_options.py](../../python/samples/getting_started/chat_client/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.
@@ -1,147 +0,0 @@
---
-status: proposed
-contact: westey-m
-date: 2026-01-27
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
-consulted: 
-informed: 
---
-
-# AgentRunContext for Agent Run
-
-## Context and Problem Statement
-
-During an agent run, various components involved in the execution (middleware, filters, tools, nested agents, etc.) may need access to contextual information about the current run, such as:
-
-1. The agent that is executing the run
-2. The session associated with the run
-3. The request messages passed to the agent
-4. The run options controlling the agent's behavior
-
-Additionally, some components may need to modify this context during execution, for example:
-
- Replacing the session with a different one
- Modifying the request messages before they reach the agent core
- Updating or replacing the run options entirely
-
-Currently, there is no standardized way to access or modify this context from arbitrary code that executes during an agent run, especially from deeply nested call stacks where the context is not explicitly passed.
-
-## Sample Scenario
-
-When using an Agent as an AIFunction developers may want to pass context from the parent agent run to the child agent run. For example, the developer may want to copy chat history to the child agent, or share the same session across both agents.
-
-To enable these scenarios, we need a way to access the parent agent run context, including e.g. the parent agent itself, the parent agent session, and the parent run options from function tool calls.
-
-```csharp
-    public static AIFunction AsAIFunctionWithSessionPropagation(this ChatClientAgent agent, AIFunctionFactoryOptions? options = null)
-    {
-        Throw.IfNull(agent);
-
-        [Description("Invoke an agent to retrieve some information.")]
-        async Task<string> InvokeAgentAsync(
-            [Description("Input query to invoke the agent.")] string query,
-            CancellationToken cancellationToken)
-        {
-            // Get the session from the parent agent and pass it to the child agent.
-            var session = AIAgent.CurrentRunContext?.Session;
-
-            // Alternatively, the developer may want to create a new session but copy over the chat history from the parent agent.
-            // var parentChatHistory = AIAgent.CurrentRunContext?.Session?.GetService<IList<ChatMessage>>();
-            // if (parentChatHistory != null)
-            // {
-            //     var chp = new InMemoryChatHistoryProvider();
-            //     foreach (var message in parentChatHistory)
-            //     {
-            //         chp.Add(message);
-            //     }
-            //     session = agent.GetNewSession(chp);
-            // }
-
-            var response = await agent.RunAsync(query, session: session, cancellationToken: cancellationToken).ConfigureAwait(false);
-            return response.Text;
-        }
-
-        options ??= new();
-        options.Name ??= SanitizeAgentName(agent.Name);
-        options.Description ??= agent.Description;
-
-        return AIFunctionFactory.Create(InvokeAgentAsync, options);
-    }
-```
-
-## Decision Drivers
-
- Components executing during an agent run need access to run context without explicit parameter passing through every layer
- Context should flow naturally across async calls without manual propagation
- The design should allow modification of context properties by agent decorators (e.g., replacing options or session)
- Solution should be consistent with patterns used in similar frameworks (e.g., `FunctionInvokingChatClient.CurrentContext` `HttpContext.Current`, `Activity.Current`)
-
-## Considered Options
-
- **Option 1**: Pass context explicitly through all method signatures
- **Option 2**: Use `AsyncLocal<T>` to provide ambient context accessible anywhere during the run
- **Option 3**: Use a combination of explicit parameters for `RunCoreAsync` and `AsyncLocal<T>` for ambient access
-
-## Decision Outcome
-
-Chosen option: **Option 3** - Combination of explicit parameters and AsyncLocal ambient access.
-
-This approach provides the best of both worlds:
-
-1. **Explicit parameters are passed to `RunCoreAsync`**: The core agent implementation receives the parameters explicitly, making it clear what data is available and enabling easy unit testing. Any modification of these in a decorator will require calling `RunAsync` on the inner agent with the updated parameters, which would result in the inner agent creating a new `AgentRunContext` instance.
-
-   ```csharp
-    public async Task<AgentResponse> RunAsync(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-
-        CurrentRunContext = new(this, session, messages as IReadOnlyCollection<ChatMessage> ?? messages.ToList(), options);
-        return await this.RunCoreAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-    }
-   ```
-
-2. **`AsyncLocal<AgentRunContext?>` for ambient access**: The context is stored in an `AsyncLocal<T>` field, making it accessible from any code executing during the agent run via a static property.
-
-    The main scenario for this is to allow deeply nested components (e.g., tools, chat client middleware) to access the context without needing to pass it through every method signature. These are external components that cannot easily be modified to accept additional parameters. For internal components, we prefer passing any parameters explicitly.
-
-   ```csharp
-   public static AgentRunContext? CurrentRunContext
-   {
-       get => s_currentContext.Value;
-       protected set => s_currentContext.Value = value;
-   }
-   ```
-
-### AgentRunContext Design
-
-The `AgentRunContext` class encapsulates all run-related state:
-
-```csharp
-public class AgentRunContext
-{
-    public AgentRunContext(
-        AIAgent agent,
-        AgentSession? session,
-        IReadOnlyCollection<ChatMessage> requestMessages,
-        AgentRunOptions? agentRunOptions)
-
-    public AIAgent Agent { get; }
-    public AgentSession? Session { get; }
-    public IReadOnlyCollection<ChatMessage> RequestMessages { get; }
-    public AgentRunOptions? RunOptions { get; }
-}
-```
-
-Key design decisions:
-
- **All properties are read-only**: While some of the sub-properties on the provided properties (like `AgentRunOptions.AllowBackgroundResponses`) may be mutable, the `AgentRunContext` itself is immutable and we want to discourage anyone modifying the values in the context.  Modifying the context is unlikely to result in the desired behavior, as the values will typically already have been used by the time any custom code accesses them.
-
-### Benefits
-
-1. **Ambient Access**: Any code executing during the run can access context via `AIAgent.CurrentRunContext` without needing explicit parameters
-2. **Async Flow**: `AsyncLocal<T>` automatically flows across async/await boundaries
-3. **Modifiability**: Components can modify or replace session, messages, or options as needed
-4. **Testability**: The explicit parameter to `RunCoreAsync` makes unit testing straightforward
@@ -1,658 +0,0 @@
---
-status: proposed
-contact: sergeymenshykh
-date: 2026-01-22
-deciders: rbarreto, westey-m, stephentoub
-informed: {}
---
-
-# Structured Output
-
-Structured output is a valuable aspect of any agent system, since it forces an agent to produce output in a required format that may include required fields.
-This allows easily turning unstructured data into structured data using a general-purpose language model.
-
-## Context and Problem Statement
-
-Structured output is currently supported only by `ChatClientAgent` and can be configured in two ways:
-
-**Approach 1: ResponseFormat + Deserialize**
-
-Specify the SO type schema via the `ChatClientAgent{Run}Options.ChatOptions.ResponseFormat` property at agent creation or invocation time, then use `JsonSerializer.Deserialize<T>` to extract the structured data from the response text.
-
-	```csharp
-	// SO type can be provided at agent creation time
-	ChatClientAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-	{
-		Name = "...",
-		ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-	});
-
-	AgentResponse response = await agent.RunAsync("...");
-
-	PersonInfo personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
-
-	Console.WriteLine($"Name: {personInfo.Name}");
-	Console.WriteLine($"Age: {personInfo.Age}");
-	Console.WriteLine($"Occupation: {personInfo.Occupation}");
-
-	// Alternatively, SO type can be provided at agent invocation time
-	response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
-	{
-		ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-	});
-
-	personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
-
-	Console.WriteLine($"Name: {personInfo.Name}");
-	Console.WriteLine($"Age: {personInfo.Age}");
-	Console.WriteLine($"Occupation: {personInfo.Occupation}");
-	```
-
-**Approach 2: Generic RunAsync<T>**
-
-Supply the SO type as a generic parameter to `RunAsync<T>` and access the parsed result directly via the `Result` property.
-
-	```csharp
-	ChatClientAgent agent = ...;
-	
-	AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("...");
-
-	Console.WriteLine($"Name: {response.Result.Name}");
-	Console.WriteLine($"Age: {response.Result.Age}");
-	Console.WriteLine($"Occupation: {response.Result.Occupation}");
-	```
-	Note: `RunAsync<T>` is an instance method of `ChatClientAgent` and not part of the `AIAgent` base class since not all agents support structured output.
-
-Approach 1 is perceived as cumbersome by the community, as it requires additional effort when using primitive or collection types - the SO schema may need to be wrapped in an artificial JSON object. Otherwise, the caller will encounter an error like _Invalid schema for response_format 'Movie': schema must be a JSON Schema of 'type: "object"', got 'type: "array"'_. 
-This occurs because OpenAI and compatible APIs require a JSON object as the root schema.
-
-Approach 1 is also necessary in scenarios where (a) agents can only be configured with SO at creation time (such as with `AIProjectClient`), (b) the SO type is not known at compile time, or (c) the JSON schema is represented as text (for declarative agents) or as a `JsonElement`.
-
-Approach 2 is more convenient and works seamlessly with primitives and collections. However, it requires the SO type to be known at compile time, making it less flexible.
-
-Additionally, since the `RunAsync<T>` methods are instance methods of `ChatClientAgent` and are not part of the `AIAgent` base class, applying decorators like `OpenTelemetryAgent` on top of `ChatClientAgent` prevents users from accessing `RunAsync<T>`, meaning structured output is not available with decorated agents.
-
-Given the different scenarios above in which structured output can be used, there is no one-size-fits-all solution. Each approach has its own advantages and limitations,
-and the two can complement each other to provide a comprehensive structured output experience across various use cases.
-
-## Approaches Overview
-
-1. SO usage via `ResponseFormat` property
-2. SO usage via `RunAsync<T>` generic method
-
-## 1. SO usage via `ResponseFormat` property
-
-This approach should be used in the following scenarios:
- - 1.1 SO result as text is sufficient as is, and deserialization is not required
- - 1.2 SO for inter-agent collaboration
- - 1.3 SO can only be configured at agent creation time (such as with `AIProjectClient`)
- - 1.4 SO type is not known at compile time and represented by System.Type
- - 1.5 SO is represented by JSON schema and there's no corresponding .NET type either at compile time or at runtime
- - 1.6 SO in streaming scenarios, where the SO response is produced in parts
-
-**Note: Primitives and arrays are not supported by this approach.**
-
-When a caller provides a schema via `ResponseFormat`, they are explicitly telling the framework what schema to use. The framework passes that schema through as-is and
-is not responsible for transforming it. Because the framework does not own the schema, it cannot wrap primitives or arrays into a JSON object to satisfy API requirements,
-nor can it unwrap the response afterward - the caller controls the schema and is responsible for ensuring it is compatible with the underlying API.
-
-This is in contrast to the `RunAsync<T>` approach (section 2), where the caller provides a type `T` and says "make it work." In that case, the caller does not
-dictate the schema - the framework infers the schema from `T`, owns the end-to-end pipeline (schema generation, API invocation, and deserialization), and can
-therefore wrap and unwrap primitives and arrays transparently.
-
-Additionally, in streaming scenarios (1.6), the framework cannot reliably unwrap a response it did not wrap, since it has no way of knowing whether the caller wrapped the schema.Wrapping and unwrapping can only be done safely when the framework owns the entire lifecycle - from schema creation through deserialization — which is only the case with `RunAsync<T>`.
-
-If a caller needs to work with primitives or arrays via the `ResponseFormat` approach, they can easily create a wrapper type around them:
-
-```csharp
-public class MovieListWrapper
-{
-    public List<string> Movies { get; set; }
-}
-```
-
-### 1.1 SO result as text is sufficient as is, and deserialization is not required
-
-In this scenario, the caller only needs the raw JSON text returned by the model and does not need to deserialize it into a .NET type.
-The SO schema is specified via `ResponseFormat` at agent creation or invocation time, and the response text is consumed directly from the `AgentResponse`.
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent();
-
-AgentRunOptions runOptions = new()
-{
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
-};
-
-AgentResponse response = await agent.RunAsync("...", options: runOptions);
-
-Console.WriteLine(response.Text);
-```
-
-### 1.2 SO for inter-agent collaboration
-
-This scenario assumes a multi-agent setup where agents collaborate by passing messages to each other.
-One agent produces structured output as text that is then passed directly as input to the next agent, without intermediate deserialization.
-
-```csharp
-// First agent extracts structured data from unstructured input
-AIAgent extractionAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    Name = "ExtractionAgent",
-    ChatOptions = new() 
-    { 
-        Instructions = "Extract person information from the provided text.",
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() 
-    }
-});
-
-AgentResponse extractionResponse = await extractionAgent.RunAsync("John Smith is a 35-year-old software engineer.");
-
-// Pass the message with structured output text directly to the next agent
-ChatMessage soMessage = extractionResponse.Messages.Last();
-
-AIAgent summaryAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    Name = "SummaryAgent",
-    ChatOptions = new() { Instructions = "Given the following structured person data, write a short professional bio." }
-});
-
-AgentResponse summaryResponse = await summaryAgent.RunAsync(soMessage);
-
-Console.WriteLine(summaryResponse);
-```
-
-### 1.3 SO configured at agent creation time
-
-In this scenario, the SO schema can only be configured at agent creation time (such as with `AIProjectClient`) and cannot be changed on a per-run basis.
-The caller specifies the `ResponseFormat` when creating the agent, and all subsequent invocations use the same schema.
-
-```csharp
-AIProjectClient client = ...;
-
-AIAgent agent = await client.CreateAIAgentAsync(model: "<model>", new ChatClientAgentOptions()
-{
-    Name = "...",
-    ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-});
-
-AgentResponse response = await agent.RunAsync("Please provide information about John Smith.");
-
-PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text, JsonSerializerOptions.Web)!;
-
-Console.WriteLine($"Name: {personInfo.Name}");
-Console.WriteLine($"Age: {personInfo.Age}");
-Console.WriteLine($"Occupation: {personInfo.Occupation}");
-```
-
-### 1.4 SO type not known at compile time and represented by System.Type
-
-In this scenario, the SO type is not known at compile time and is provided as a `System.Type` at runtime. This is useful for dynamic scenarios where the schema is determined programmatically, 
-such as when building tooling or frameworks that work with user-defined types.
-
-```csharp
-Type soType = GetStructuredOutputTypeFromConfiguration(); // e.g., typeof(PersonInfo)
-
-ChatResponseFormat responseFormat = ChatResponseFormat.ForJsonSchema(soType);
-
-AgentResponse response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
-{
-    ChatOptions = new() { ResponseFormat = responseFormat }
-});
-
-PersonInfo personInfo = (PersonInfo)JsonSerializer.Deserialize(response.Text, soType, JsonSerializerOptions.Web)!;
-```
-
-### 1.5 SO represented by JSON schema with no corresponding .NET type
-
-In this scenario, the SO schema is represented as raw JSON schema text or a `JsonElement`, and there is no corresponding .NET type available at compile time or runtime.
-This is typical for declarative agents or scenarios where schemas are loaded from external configuration.
-
-```csharp
-// JSON schema provided as a string, e.g., loaded from a configuration file
-string jsonSchema = """
-{
-    "type": "object",
-    "properties": {
-        "name": { "type": "string" },
-        "age": { "type": "integer" },
-        "occupation": { "type": "string" }
-    },
-    "required": ["name", "age", "occupation"]
-}
-""";
-
-ChatResponseFormat responseFormat = ChatResponseFormat.ForJsonSchema(
-    jsonSchemaName: "PersonInfo",
-    jsonSchema: BinaryData.FromString(jsonSchema));
-
-AgentResponse response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
-{
-    ChatOptions = new() { ResponseFormat = responseFormat }
-});
-
-// Consume the SO result as text since there's no .NET type to deserialize into
-Console.WriteLine(response.Text);
-```
-
-### 1.6 SO in streaming scenarios
-
-In this scenario, the SO response is produced incrementally in parts via streaming. The caller specifies the `ResponseFormat` and consumes the response chunks as they arrive.
-Deserialization is performed after all chunks have been received.
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    Name = "HelpfulAssistant",
-    ChatOptions = new()
-    {
-        Instructions = "You are a helpful assistant.",
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
-    }
-});
-
-IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
-
-AgentResponse response = await updates.ToAgentResponseAsync();
-
-// Deserialize the complete SO result after streaming is finished
-PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text)!;
-```
-
-## 2. SO usage via `RunAsync<T>` generic method
-
-This approach provides a convenient way to work with structured output on a per-run basis when the target type is known at compile time and a typed instance of the result
-is required.
-
-### Decision Drivers
-
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-### Considered Options
-
-1. `RunAsync<T>` as an instance method of `AIAgent` class delegating to virtual `RunCoreAsync<T>`
-2. `RunAsync<T>` as an extension method using feature collection
-3. `RunAsync<T>` as a method of the new `ITypedAIAgent` interface
-4. `RunAsync<T>` as an instance method of `AIAgent` class working via the new `AgentRunOptions.ResponseFormat` property
-
-### 1. `RunAsync<T>` as an instance method of `AIAgent` class delegating to virtual `RunCoreAsync<T>`
-
-This option adds the `RunAsync<T>` method directly to the `AIAgent` base class.
-
-```csharp
-public abstract class AIAgent
-{
-	public Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-		=> this.RunCoreAsync<T>(messages, session, serializerOptions, options, cancellationToken);
-
-    protected virtual Task<AgentResponse<T>> RunCoreAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        throw new NotSupportedException($"The agent of type '{this.GetType().FullName}' does not support typed responses.");
-    }
-}
-```
-
-Agents with native SO support override the `RunCoreAsync<T>` method to provide their implementation. If not overridden, the method throws a `NotSupportedException`.
-
-Users will call the generic `RunAsync<T>` method directly on the agent:
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-```
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
- The `AIAgent.RunAsync<T>` method is easily discoverable.
- Both the SO decorator and `ChatClientAgent` have compile-time access to the type `T`, allowing them to use the native `IChatClient.GetResponseAsync<T>` API, which handles primitives and collections seamlessly.
-
-Cons:
- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
- All `AIAgent` decorators must override `RunCoreAsync<T>` to properly handle `RunAsync<T>` calls.
-
-### 2. `RunAsync<T>` as an extension method using feature collection
-
-This option uses the Agent Framework feature collection (implemented via `AgentRunOptions.AdditionalProperties`) to pass a `StructuredOutputFeature` to agents, signaling that SO is requested.
-
-Agents with native SO support check for this feature. If present, they read the target type, build the schema, invoke the underlying API, and store the response back in the feature.
-```csharp
-public class StructuredOutputFeature
-{
-    public StructuredOutputFeature(Type outputType)
-    {
-        this.OutputType = outputType;
-    }
-
-    [JsonIgnore]
-    public Type OutputType { get; set; }
-
-    public JsonSerializerOptions? SerializerOptions { get; set; }
-
-    public AgentResponse? Response { get; set; }
-}
-```
-
-The `RunAsync<T>` extension method for `AIAgent` adds this feature to the collection.
-```csharp
-public static async Task<AgentResponse<T>> RunAsync<T>(
-    this AIAgent agent,
-    IEnumerable<ChatMessage> messages,
-    AgentSession? session = null,
-    JsonSerializerOptions? serializerOptions = null,
-    AgentRunOptions? options = null,
-    CancellationToken cancellationToken = default)
-{
-    // Create the structured output feature.
-    StructuredOutputFeature structuredOutputFeature = new(typeof(T))
-    {
-        SerializerOptions = serializerOptions,
-    };
-
-    // Register it in the feature collection.
-    ((options ??= new AgentRunOptions()).AdditionalProperties ??= []).Add(typeof(StructuredOutputFeature).FullName!, structuredOutputFeature);
-
-    var response = await agent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-    if (structuredOutputFeature.Response is not null)
-    {
-        return new StructuredOutputResponse<T>(structuredOutputFeature.Response, response, serializerOptions);
-    }
-
-    throw new InvalidOperationException("No structured output response was generated by the agent.");
-}
-```
-
-Users will call the `RunAsync<T>` extension method directly on the agent:
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-```
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
- The `RunAsync<T>` extension method is easily discoverable.
- The `AIAgent` public API surface remains unchanged.
- No changes required to `AIAgent` decorators.
-
-Cons:
- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
-
-### 3. `RunAsync<T>` as a method of the new `ITypedAIAgent` interface
-
-This option defines a new `ITypedAIAgent` interface that agents with SO support implement. Agents without SO support do not implement it, allowing users to check for SO capability via interface detection.
-
-The interface:
-```csharp
-public interface ITypedAIAgent
-{
-    Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default);
-
-    ...
-}
-```
-
-Agents with SO support implement this interface:
-```csharp
-public sealed partial class ChatClientAgent : AIAgent, ITypedAIAgent
-{
-    public async Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        ...
-    }
-}
-```
-
-However, `ChatClientAgent` presents a challenge: it can work with chat clients that either support or do not support SO. Implementing the interface does not guarantee 
-the underlying chat client supports SO, which undermines the core idea of using interface detection to determine SO capability.
-
-Additionally, to allow users to access interface methods on decorated agents, all decorators must implement `ITypedAIAgent`. This makes it difficult for users to 
-determine whether the underlying agent actually supports SO, further weakening the purpose of this approach.
-
-Furthermore, users would have to probe the agent type to check if it implements the `ITypedAIAgent` interface and cast it accordingly to access the `RunAsync<T>` methods.
-This adds friction to the user experience. A `RunAsync<T>` extension method for `AIAgent` could be provided to alleviate that.
-
-Given these drawbacks, this option is more complex to implement than the others without providing clear benefits.
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
- Both the SO decorator and `ChatClientAgent` have compile-time access to the type `T`, allowing them to use the native `IChatClient.GetResponseAsync<T>` API, which handles primitives and collections seamlessly.
-
-Cons:
- `ChatClientAgent` implementing `ITypedAIAgent` may be misleading when the underlying chat client does not support SO.
- All `AIAgent` decorators must implement `ITypedAIAgent` to handle `RunAsync<T>` calls.
- Decorators implementing the interface may mislead users into thinking the underlying agent natively supports SO.
- Agents must implement all members of `ITypedAIAgent`, not just a core method.
- Users must check the agent type and cast to `ITypedAIAgent` to access `RunAsync<T>`.
-
-### 4. `RunAsync<T>` as an instance method of `AIAgent` class working via the new `AgentRunOptions.ResponseFormat` property
-
-This option adds a `ResponseFormat` property of type `ChatResponseFormat` to `AgentRunOptions`. Agents that support SO check for the presence of 
-this property in the options passed to `RunAsync` to determine whether structured output is requested. If present, they use the schema from `ResponseFormat` 
-to invoke the underlying API and obtain the SO response.
-
-```csharp
-public class AgentRunOptions
-{
-    public ChatResponseFormat? ResponseFormat { get; set; }
-}
-```
-
-Additionally, a generic `RunAsync<T>` method is added to `AIAgent` that initializes the `ResponseFormat` based on the type `T` and delegates to the non-generic `RunAsync`.
-
-```csharp
-public abstract class AIAgent
-{
-	public async Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;
-
-        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
-
-        options = options?.Clone() ?? new AgentRunOptions();
-        options.ResponseFormat = responseFormat;
-
-        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-        return new AgentResponse<T>(response, serializerOptions);
-    }
-}
-```
-
-Users call the generic `RunAsync<T>` method directly on the agent:
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-```
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
- The `AIAgent.RunAsync<T>` method is easily discoverable.
- No changes required to `AIAgent` decorators
-
-Cons:
- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
-
-### Decision Table
-
-|  | Option 1: Instance method + RunCoreAsync<T> | Option 2: Extension method + feature collection | Option 3: ITypedAIAgent Interface | Option 4: Instance method + AgentRunOptions.ResponseFormat |
-|---|---|---|---|---|
-| Discoverability | ✅ `RunAsync<T>` easily discoverable | ✅ `RunAsync<T>` easily discoverable | ❌ Requires type check and cast | ✅ `RunAsync<T>` easily discoverable |
-| Decorator changes | ❌ All decorators must override `RunCoreAsync<T>` | ✅ No changes required | ❌ All decorators must implement `ITypedAIAgent` | ✅ No changes required to decorators |
-| Primitives/collections handling | ✅ Native support via `IChatClient.GetResponseAsync<T>` | ❌ Must wrap/unwrap internally | ✅ Native support via `IChatClient.GetResponseAsync<T>` | ❌ Must wrap/unwrap internally |
-| Misleading API exposure | ❌ Agents without SO still expose `RunAsync<T>` | ❌ Agents without SO still expose `RunAsync<T>` | ❌ Interface on `ChatClientAgent` may be misleading | ❌ Agents without SO still expose `RunAsync<T>` |
-| Implementation burden | ❌ Decorators must override method | ❌ Must handle schema wrapping | ❌ Agents must implement all interface members | ✅ Delegates to existing `RunAsync` via `ResponseFormat` |
-
-## Cross-Cutting Aspects
-
-1. **The `useJsonSchemaResponseFormat` parameter**: The `ChatClientAgent.RunAsync<T>` method has this parameter to enable structured output on LLMs that do not natively support it.
-  It works by adding a user message like "Respond with a JSON value conforming to the following schema:" along with the JSON schema. However, this approach has not been reliable historically. The recommendation is not to carry this parameter forward, regardless of which option is chosen.
-
-2. **Primitives and array types handling**: There are a few options for how primitive and array types can be handled in the Agent Framework:
-
-   1. **Never wrap**, regardless of whether the schema is provided via `ResponseFormat` or `RunAsync<T>`.
-       - Pro: No changes needed; user has full control.
-       - Pro: No issues with unwrapping in streaming scenarios.
-       - Con: User must wrap manually.
-
-   2. **Always wrap**, regardless of whether the schema is provided via `ResponseFormat` or `RunAsync<T>`.
-       - Pro: Consistent wrapping behavior; no manual wrapping needed.
-       - Con: Inconsistent unwrapping behavior; it may be unexpected to have SO result wrapped when schema is provided via `ResponseFormat`.
-       - Con: Impossible to know if SO result is wrapped to unwrap it in streaming scenarios.
-
-   3. **Wrap only for `RunAsync<T>`** and do not wrap the schema provided via `ResponseFormat`.
-       - Pro: No unexpectedly wrapped result when schema is provided via `ResponseFormat`.
-       - Pro: Solves the problem with unwrapping in streaming scenarios.
-
-   4. **User decides** whether to wrap schema provided via `ResponseFormat` using a new `wrapPrimitivesAndArrays` property of `ChatResponseFormatJson`. For SO provided via `RunAsync<T>`, AF always wraps.
-       - Pro: No manual wrapping needed; just flip a switch.
-       - Pro: Solves the problem with unwrapping in streaming scenarios.
-       - Con: Extends the public API surface.
-
-3. **Structured output for agents without native SO support**: Some AI agents in AF do not support structured output natively. This is either because it is not part of the protocol (e.g., A2A agent) or because the agents use LLMs without structured output capabilities.
-   To address this gap, AF can provide the `StructuredOutputAgent` decorator. This decorator wraps any `AIAgent` and adds structured output support by obtaining the text response from the decorated agent and delegating it to a configured chat client for JSON transformation.
-   
-   ```csharp
-   public class StructuredOutputAgent : DelegatingAIAgent
-   {
-        private readonly IChatClient _chatClient;
-
-        public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient)
-            : base(innerAgent)
-        {
-            this._chatClient = Throw.IfNull(chatClient);
-        }
-
-        protected override async Task<AgentResponse<T>> RunCoreAsync<T>(
-            IEnumerable<ChatMessage> messages,
-            AgentSession? session = null,
-            JsonSerializerOptions? serializerOptions = null,
-            AgentRunOptions? options = null,
-            CancellationToken cancellationToken = default)
-        {
-            // Run the inner agent first, to get back the text response we want to convert.
-            var textResponse = await this.InnerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-            // Invoke the chat client to transform the text output into structured data.
-            ChatResponse<T> soResponse = await this._chatClient.GetResponseAsync<T>(
-                messages:
-                [
-                    new ChatMessage(ChatRole.System, "You are a json expert and when provided with any text, will convert it to the requested json format."),
-                    new ChatMessage(ChatRole.User, textResponse.Text)
-                ],
-                serializerOptions: serializerOptions ?? AgentJsonUtilities.DefaultOptions,
-                cancellationToken: cancellationToken).ConfigureAwait(false);
-
-            return new StructuredOutputAgentResponse(soResponse, textResponse);
-        }
-   }
-   ```
-
-   The decorator preserves the original response from the decorated agent and surfaces it via the `OriginalResponse` property on the returned `StructuredOutputAgentResponse`.
-   This allows users to access both the original unstructured response and the new structured response when using this decorator.
-   ```csharp
-   public class StructuredOutputAgentResponse : AgentResponse
-   {
-       internal StructuredOutputAgentResponse(ChatResponse chatResponse, AgentResponse agentResponse) : base(chatResponse)
-       {
-           this.OriginalResponse = agentResponse;
-       }
-       
-       public AgentResponse OriginalResponse { get; }
-    }
-   ```
-   
-   The decorator can be registered during the agent configuration step using the `UseStructuredOutput` extension method on `AIAgentBuilder`.
-
-   ```csharp
-   IChatClient meaiChatClient = chatClient.AsIChatClient();
-
-   AIAgent baseAgent = meaiChatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-   // Register the StructuredOutputAgent decorator during agent building
-   AIAgent agent = baseAgent
-       .AsBuilder()
-       .UseStructuredOutput(meaiChatClient)
-       .Build();
-
-   AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-
-   Console.WriteLine($"Name: {response.Result.Name}");
-   Console.WriteLine($"Age: {response.Result.Age}");
-   Console.WriteLine($"Occupation: {response.Result.Occupation}");
-   
-   var originalResponse = ((StructuredOutputAgentResponse)response.RawRepresentation!).OriginalResponse;
-   Console.WriteLine($"Original unstructured response: {originalResponse.Text}");
-
-   ```
-
-## Decision Outcome
-
-It was decided to keep both approaches for structured output - via `ResponseFormat` and via `RunAsync<T>` since they serve different scenarios and use cases.
-
-For the `RunAsync<T>` approach, option 4 was selected, which adds a generic `RunAsync<T>` method to `AIAgent` that works via the new `AgentRunOptions.ResponseFormat` property.
-This was chosen for its simplicity and because no changes are required to existing `AIAgent` decorators.
-
-For cross-cutting aspects, the `useJsonSchemaResponseFormat` parameter will not be carried forward due to reliability issues.
-
-For handling primitives and array types, option 3 was selected: wrap only for `RunAsync<T>` and do not wrap the schema provided via `ResponseFormat`.
-This avoids the issues described in the Approach 1 section note.
-
-Finally, it was decided not to include the `StructuredOutputAgent` decorator in the framework, since the reliability of producing structured output via an additional
-LLM call may not be sufficient for all scenarios. Instead, this pattern is provided as a sample to demonstrate how structured output can be achieved for agents without native support,
-giving users a reference implementation they can adapt to their own requirements.
@@ -1,48 +0,0 @@
-# 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.
@@ -1,239 +0,0 @@
-# Durable agents
-
-## Overview
-
-Durable agents extend the standard Microsoft Agent Framework with **durable state management** powered by the Durable Task framework. An ordinary Agent Framework agent runs in-process: its conversation history lives in memory and is lost when the process ends. A durable agent persists conversation history and execution state in external storage so that sessions survive process restarts, failures, and scale-out events.
-
-| Capability | Ordinary agent | Durable agent |
-| --- | --- | --- |
-| Conversation history | In-memory only | Durably persisted |
-| Failure recovery | State lost on crash | Automatically resumed |
-| Multi-instance scale-out | Not supported | Any worker can resume a session |
-| Multi-agent orchestrations | Manual coordination | Deterministic, checkpointed workflows |
-| Human-in-the-loop | Must keep process alive | Can wait days/weeks with zero compute |
-| Hosting | Any process | Console app, Azure Functions, or any Durable Task–compatible host |
-
-> [!NOTE]
-> For a step-by-step tutorial and deployment guidance, see [Azure Functions (Durable)](https://learn.microsoft.com/agent-framework/integrations/azure-functions) on Microsoft Learn.
-
-## How durable agents work
-
-Durable agents are implemented on top of [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities) (also called "virtual actors"). Each **agent session** maps to one entity instance whose state contains the full conversation history. When you send a message to a durable agent, the following happens:
-
-1. The message is dispatched to the entity identified by an `AgentSessionId` (a composite of the agent name and a unique session key).
-2. The entity loads its persisted `DurableAgentState`, which includes the complete conversation history.
-3. The entity invokes the underlying `AIAgent` with the full conversation history, collects the response, and appends both the request and the response to the state.
-4. The updated state is persisted back to durable storage automatically.
-
-Because the entity framework serializes access to each entity instance, concurrent messages to the same session are processed one at a time, eliminating race conditions.
-
-### Agent session identity
-
-Every durable agent session is identified by an `AgentSessionId`, which has two components:
-
- **Name** – the registered name of the agent (case-insensitive).
- **Key** – a unique session key (case-sensitive), typically a GUID.
-
-The session ID is mapped to an underlying Durable Task entity ID with a `dafx-` prefix (e.g., `dafx-joker`). This naming convention is consistent across both .NET and Python implementations.
-
-## Architecture
-
-### .NET
-
-The .NET implementation consists of two NuGet packages:
-
-| Package | Purpose |
-| --- | --- |
-| `Microsoft.Agents.AI.DurableTask` | Core durable agent types: `DurableAIAgent`, `AgentEntity`, `DurableAgentSession`, `AgentSessionId`, `DurableAgentsOptions`, and the state model. |
-| `Microsoft.Agents.AI.Hosting.AzureFunctions` | Azure Functions hosting integration: auto-generated HTTP endpoints, MCP tool triggers, entity function triggers, and the `ConfigureDurableAgents` extension method on `FunctionsApplicationBuilder`. |
-
-Key types:
-
- **`DurableAIAgent`** – A subclass of `AIAgent` used *inside orchestrations*. Obtained via `context.GetAgent("agentName")`, it routes `RunAsync` calls through the orchestration's entity APIs so that each call is checkpointed.
- **`DurableAIAgentProxy`** – A subclass of `AIAgent` used *outside orchestrations* (e.g., from HTTP triggers or console apps). It signals the entity via `DurableTaskClient` and polls for the response.
- **`AgentEntity`** – The `TaskEntity<DurableAgentState>` that hosts the real agent. It loads the registered `AIAgent` by name, wraps it in an `EntityAgentWrapper`, feeds it the full conversation history, and persists the result.
- **`DurableAgentSession`** – An `AgentSession` subclass that carries the `AgentSessionId`.
- **`DurableAgentsOptions`** – Builder for registering agents and configuring TTL.
-
-### Python
-
-The core Python implementation is in the `agent-framework-durabletask` package (`python/packages/durabletask`). Azure Functions hosting (including `AgentFunctionApp`) is in the separate `agent-framework-azurefunctions` package (`python/packages/azurefunctions`).
-
-Key types:
-
- **`DurableAIAgent`** – A generic proxy (`DurableAIAgent[TaskT]`) implementing `SupportsAgentRun`. Returns a `TaskT` from `run()` — either an `AgentResponse` (client context) or a `DurableAgentTask` (orchestration context, must be `yield`ed).
- **`DurableAIAgentWorker`** – Wraps a `TaskHubGrpcWorker` and registers agents as durable entities via `add_agent()`.
- **`DurableAIAgentClient`** – Wraps a `TaskHubGrpcClient` for external callers. `get_agent()` returns a `DurableAIAgent[AgentResponse]`.
- **`DurableAIAgentOrchestrationContext`** – Wraps an `OrchestrationContext` for use inside orchestrations. `get_agent()` returns a `DurableAIAgent[DurableAgentTask]`.
- **`AgentEntity`** – Platform-agnostic agent execution logic that manages state, invokes the agent, handles streaming, and calls response callbacks.
-
-## Hosting models
-
-### Azure Functions
-
-The recommended production hosting model. A single call to `ConfigureDurableAgents` (C#) or `AgentFunctionApp` (Python) automatically:
-
- Registers agent entities with the Durable Task worker.
- Generates HTTP endpoints at `/api/agents/{agentName}/run` for each registered agent.
- Supports `thread_id` query parameter / JSON field and the `x-ms-thread-id` response header for session continuity.
- Supports fire-and-forget via the `x-ms-wait-for-response: false` header (returns HTTP 202).
- Optionally exposes agents as MCP tools.
-
-**C# example:**
-
-```csharp
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
-    .Build();
-app.Run();
-```
-
-**Python example:**
-
-```python
-app = AgentFunctionApp(agents=[agent])
-```
-
-### Console apps / generic hosts
-
-For self-hosted or non-serverless scenarios, register durable agents via `IServiceCollection.ConfigureDurableAgents` (.NET) or `DurableAIAgentWorker` (Python) with explicit Durable Task worker and client configuration.
-
-**C# example:**
-
-```csharp
-IHost host = Host.CreateDefaultBuilder(args)
-    .ConfigureServices(services =>
-    {
-        services.ConfigureDurableAgents(
-            options => options.AddAIAgent(agent),
-            workerBuilder: b => b.UseDurableTaskScheduler(connectionString),
-            clientBuilder: b => b.UseDurableTaskScheduler(connectionString));
-    })
-    .Build();
-```
-
-**Python example:**
-
-```python
-worker = DurableAIAgentWorker(TaskHubGrpcWorker(host_address="localhost:4001"))
-worker.add_agent(agent)
-worker.start()
-```
-
-## Deterministic multi-agent orchestrations
-
-Durable agents can be composed into deterministic, checkpointed workflows using Durable Task orchestrations. The orchestration framework replays orchestrator code on failure, so completed agent calls are not re-executed.
-
-### Patterns
-
-| Pattern | Description |
-| --- | --- |
-| **Sequential (chaining)** | Call agents one after another, passing outputs forward. |
-| **Parallel (fan-out/fan-in)** | Run multiple agents concurrently and aggregate results. |
-| **Conditional** | Branch orchestration logic based on structured agent output. |
-| **Human-in-the-loop** | Pause for external events (approvals, feedback) with optional timeouts. |
-
-### Using agents in orchestrations
-
-Inside an orchestration function, obtain a `DurableAIAgent` via the orchestration context. Each agent gets its own session (created with `CreateSessionAsync` / `create_session`), and you can call the same agent multiple times on the same session to maintain conversation context across sequential invocations.
-
-**C#:**
-
-```csharp
-static async Task<string> WritingOrchestration(TaskOrchestrationContext context)
-{
-    // Get a durable agent reference — works in any host (console app, Azure Functions, etc.)
-    DurableAIAgent writer = context.GetAgent("WriterAgent");
-
-    // Create a session to maintain conversation context across multiple calls
-    AgentSession session = await writer.CreateSessionAsync();
-
-    // First call: generate an initial draft
-    AgentResponse<TextResponse> draft = await writer.RunAsync<TextResponse>(
-        message: "Write a concise inspirational sentence about learning.",
-        session: session);
-
-    // Second call: refine the draft — the agent sees the full conversation history
-    AgentResponse<TextResponse> refined = await writer.RunAsync<TextResponse>(
-        message: $"Improve this further while keeping it under 25 words: {draft.Result.Text}",
-        session: session);
-
-    return refined.Result.Text;
-}
-```
-
-**Python:**
-
-```python
-def writing_orchestration(context, _):
-    agent_ctx = DurableAIAgentOrchestrationContext(context)
-
-    # Get a durable agent reference — works in any host (standalone worker, Azure Functions, etc.)
-    writer = agent_ctx.get_agent("WriterAgent")
-
-    # Create a session to maintain conversation context across multiple calls
-    session = writer.create_session()
-
-    # First call: generate an initial draft
-    draft = yield writer.run(
-        messages="Write a concise inspirational sentence about learning.",
-        session=session,
-    )
-
-    # Second call: refine the draft — the agent sees the full conversation history
-    refined = yield writer.run(
-        messages=f"Improve this further while keeping it under 25 words: {draft.text}",
-        session=session,
-    )
-
-    return refined.text
-```
-
-> [!IMPORTANT]
-> In .NET, `DurableAIAgent.RunAsync<T>` deliberately avoids `ConfigureAwait(false)` because the Durable Task Framework uses a custom synchronization context — all continuations must run on the orchestration thread.
-
-## Streaming and response callbacks
-
-Durable agents do not support true end-to-end streaming because entity operations are request/response. However, **reliable streaming** is supported via response callbacks:
-
- **`IAgentResponseHandler`** (.NET) or **`AgentResponseCallbackProtocol`** (Python) – Implement this interface to receive streaming updates as the underlying agent generates them (e.g., push tokens to a Redis Stream for client consumption).
- The entity still returns the complete `AgentResponse` after the stream is fully consumed.
- Clients can reconnect and resume reading from a cursor-based stream (e.g., Redis Streams) without losing messages.
-
-See the **Reliable Streaming** samples for a complete implementation using Redis Streams.
-
-## Session TTL (Time-To-Live)
-
-Durable agent sessions support automatic cleanup via configurable TTL. See [Session TTL](durable-agents-ttl.md) for details on configuration, behavior, and best practices.
-
-## Observability
-
-When using the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) as the durable backend, you get built-in observability through its dashboard:
-
- **Conversation history** – View complete chat history for each agent session.
- **Orchestration visualization** – See multi-agent execution flows, including parallel branches and conditional logic.
- **Performance metrics** – Monitor agent response times, token usage, and orchestration duration.
- **Debugging** – Trace tool invocations and external event handling.
-
-## Samples
-
- **.NET** – [Console app samples](../../../dotnet/samples/Durable/Agents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/Durable/Agents/AzureFunctions/) covering single-agent, chaining, concurrency, conditionals, human-in-the-loop, long-running tools, MCP tool exposure, and reliable streaming.
- **Python** – [Durable Task samples](../../../python/samples/04-hosting/durabletask/) covering single-agent, multi-agent, streaming, chaining, concurrency, conditionals, and human-in-the-loop.
-
-## Packages
-
-| Language | Package | Source |
-| --- | --- | --- |
-| .NET | `Microsoft.Agents.AI.DurableTask` | [`dotnet/src/Microsoft.Agents.AI.DurableTask`](../../../dotnet/src/Microsoft.Agents.AI.DurableTask) |
-| .NET | `Microsoft.Agents.AI.Hosting.AzureFunctions` | [`dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions`](../../../dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions) |
-| Python | `agent-framework-durabletask` | [`python/packages/durabletask`](../../../python/packages/durabletask) |
-| Python | `agent-framework-azurefunctions` | [`python/packages/azurefunctions`](../../../python/packages/azurefunctions) |
-
-## Further reading
-
- [Azure Functions (Durable) — Microsoft Learn](https://learn.microsoft.com/agent-framework/integrations/azure-functions)
- [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler)
- [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities)
- [Session TTL](durable-agents-ttl.md)
@@ -1,85 +0,0 @@
---
-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`.
@@ -1,31 +0,0 @@
---
-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,82 +0,0 @@
---
-name: verify-dotnet-samples
-description: How to build, run and verify the .NET sample projects in the Agent Framework repository. Use this when a user wants to verify that the samples still function as expected.
---
-
-# Verifying .NET Sample Projects
-
-## Sample Pre-requisites
-
-We should only support verifying samples that:
-1. Use environment variables for configuration.
-2. Have no complex setup requirements, e.g., where multiple applications need to be run together, or where we need to launch a browser, etc.
-
-Always report to the user which samples were run and which were not, and why.
-
-## Verifying a sample
-
-Samples should be verified to ensure that they actually work as intended and that their output matches what is expected.
-For each sample that is run, output should be produced that shows the result and explains the reasoning about what output
-was expected, what was produced, and why it didn't match what the sample was expected to produce.
-
-Steps to verify a sample:
-1. Read the code for the sample
-1. Check what environment variables are required for the sample
-1. Check if each environment variable has been set
-1. If there are any missing, give the user a list of missing environment variables to set and terminate
-1. Summarize what the expected output of the sample should be
-1. Run the sample
-1. Show the user any output from the sample run as it gets produced, so that they can see the run progress
-1. Check the output of the run against expectations
-1. After running all requested samples, produce output for each sample that was verified:
-  1. If expectations were matched, output the following:
-     ```text
-     [Sample Name] Succeeded
-     ```
-  1. If expectations were not matched, output the following:
-     ```text
-     [Sample Name] Failed
-     Actual Output:
-     [What the sample produced]
-     Expected Output:
-     [Explanation of what was expected and why the actual output didn't match expectations]
-     ```
-
-## Environment Variables
-
-Most samples use environment variables to configure settings.
-
-```csharp
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-```
-
-To run a sample, the environment variables should be set first.
-Before running a sample, check whether each environment variable in the sample has a value and
-then give the user a list of environment variables to set.
-
-You can provide the user some examples of how to set the variables like this:
-
-```bash
-export AZURE_OPENAI_ENDPOINT="https://my-openai-instance.openai.azure.com/"
-export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-To check if a variable has a value use e.g.:
-
-```bash
-echo $AZURE_OPENAI_ENDPOINT
-```
-
-## How to Run a Sample (General Pattern)
-
-```bash
-cd dotnet/samples/<category>/<sample-dir>
-dotnet run
-```
-
-For multi-targeted projects (e.g., Durable console apps), specify the framework:
-
-```bash
-dotnet run --framework net10.0
-```
@@ -1,6 +1,5 @@
 {
    "dotnet.defaultSolution": "agent-framework-dotnet.slnx",
    "git.openRepositoryInParentFolders": "always",
-    "chat.agent.enabled": true,
-    "dotnet.automaticallySyncWithActiveItem": true
+    "chat.agent.enabled": true
 }
@@ -1,65 +0,0 @@
-# AGENTS.md
-
-Instructions for AI coding agents working in the .NET codebase.
-
-## Build, Test, and Lint Commands
-
-See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects.
-
-## Project Structure
-
-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`, `AIFunction`, `ChatMessage`, and `AIContent`.
-
-## Key Conventions
-
- **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`
- **Private classes**: Should be `sealed` unless subclassed
- **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
-4. Main code logic
-5. Helper methods at bottom
-
-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
- Reference the sample in the parent directory's README.md
@@ -33,18 +33,18 @@
    <!-- Newtonsoft.Json -->
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
    <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.3" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.2" />
    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
    <PackageVersion Include="System.ClientModel" Version="1.8.1" />
    <PackageVersion Include="System.CodeDom" Version="10.0.0" />
    <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.3" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.2" />
    <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.3" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.3" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.3" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.1" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.2" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.2" />
    <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
    <PackageVersion Include="System.Net.Security" Version="4.3.2" />
    <!-- OpenTelemetry -->
@@ -61,12 +61,9 @@
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
    <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.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.AI" Version="10.2.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.2.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.2.0-preview.1.26063.2" />
    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
@@ -74,11 +71,11 @@
    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.3" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.2" />
    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.3" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.2" />
    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -92,7 +89,7 @@
    <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
    <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
    <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.23" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.18" />
    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
    <!-- M365 Agents SDK -->
    <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -102,7 +99,7 @@
    <PackageVersion Include="A2A" Version="0.3.3-preview" />
    <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
    <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="0.8.0-preview.1" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
    <!-- Inference SDKs -->
    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5.1" />
    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
@@ -111,19 +108,19 @@
    <!-- Identity -->
    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
    <!-- Workflows -->
-    <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" />
+    <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" />
    <!-- Durable Task -->
-    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.18.0" />
-    <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.18.0" />
-    <PackageVersion Include="Microsoft.DurableTask.Worker" Version="1.18.0" />
-    <PackageVersion Include="Microsoft.DurableTask.Worker.AzureManaged" Version="1.18.0" />
+    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.19.1" />
+    <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.19.0" />
+    <PackageVersion Include="Microsoft.DurableTask.Worker" Version="1.19.0" />
+    <PackageVersion Include="Microsoft.DurableTask.Worker.AzureManaged" Version="1.19.0" />
    <!-- Azure Functions -->
    <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="2.50.0" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="2.50.0" />
-    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.11.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.13.1" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" Version="1.0.1" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.3.0" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
@@ -11,16 +11,16 @@
 ### Basic Agent - .NET

 ```c#
+using System;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI.Responses;

 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")!;

 var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetResponsesClient(deploymentName)
+    .GetOpenAIResponseClient(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."));
@@ -47,6 +47,20 @@
    <Project Path="samples/Durable/Agents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
    <Project Path="samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
  </Folder>
+  <Folder Name="/Samples/Durable/Workflows/">
+    <Project Path="samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges/03_ConditionalEdges.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/04_WorkflowAndAgents/04_WorkflowAndAgents.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/05_WorkflowEvents/05_WorkflowEvents.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/06_WorkflowSharedState/06_WorkflowSharedState.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/07_SubWorkflows/07_SubWorkflows.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/08_WorkflowLoop/08_WorkflowLoop.csproj" />
+  </Folder>
+  <Folder Name="/Samples/Durable/Workflows/AzureFunctions/">
+    <Project Path="samples/Durable/Workflow/AzureFunctions/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
+    <Project Path="samples/Durable/Workflow/AzureFunctions/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
+  </Folder>
  <Folder Name="/Samples/GettingStarted/">
    <File Path="samples/GettingStarted/README.md" />
  </Folder>
@@ -81,7 +95,7 @@
    <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_Step07_3rdPartyThreadStorage/Agent_Step07_3rdPartyThreadStorage.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" />
@@ -131,7 +145,6 @@
    <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>
  <Folder Name="/Samples/GettingStarted/AgentWithMemory/">
    <File Path="samples/GettingStarted/AgentWithMemory/README.md" />
@@ -176,10 +189,6 @@
    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step19_OpenAPITools/FoundryAgents_Step19_OpenAPITools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step18_FileSearch/FoundryAgents_Step18_FileSearch.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj" />
  </Folder>
  <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
    <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
@@ -217,7 +226,6 @@
    <Project Path="samples/GettingStarted/Workflows/Declarative/Marketing/Marketing.csproj" />
    <Project Path="samples/GettingStarted/Workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
    <Project Path="samples/GettingStarted/Workflows/Declarative/ToolApproval/ToolApproval.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
  </Folder>
  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
    <File Path="../workflow-samples/CustomerSupport.yaml" />
@@ -376,10 +384,6 @@
    <File Path="src/Shared/Demos/README.md" />
    <File Path="src/Shared/Demos/SampleEnvironment.cs" />
  </Folder>
-  <Folder Name="/Solution Items/src/Shared/DiagnosticIds/">
-    <File Path="src/Shared/DiagnosticIds/DiagnosticsIds.cs" />
-    <File Path="src/Shared/DiagnosticIds/README.md" />
-  </Folder>
  <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
    <File Path="src/Shared/IntegrationTests/AnthropicConfiguration.cs" />
    <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
@@ -398,9 +402,6 @@
    <File Path="src/Shared/Throw/README.md" />
    <File Path="src/Shared/Throw/Throw.cs" />
  </Folder>
-  <Folder Name="/Solution Items/src/Shared/StructuredOutput/">
-    <File Path="src/Shared/StructuredOutput/StructuredOutputSchemaUtilities.cs" />
-  </Folder>
  <Folder Name="/Solution Items/tests/">
    <File Path="tests/.editorconfig" />
    <File Path="tests/Directory.Build.props" />
@@ -410,6 +411,7 @@
    <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" />
@@ -417,7 +419,6 @@
    <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" />
@@ -429,8 +430,8 @@
    <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows.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.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
    <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
  </Folder>
  <Folder Name="/Tests/" />
@@ -440,8 +441,8 @@
    <Project Path="tests/AzureAI.IntegrationTests/AzureAI.IntegrationTests.csproj" />
    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.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.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.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" />
@@ -455,13 +456,13 @@
    <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
@@ -25,7 +25,6 @@
      "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
-      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
      "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj"
    ]
@@ -20,10 +20,4 @@
  <ItemGroup Condition="'$(InjectSharedFoundryAgents)' == 'true'">
    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Foundry\Agents\*.cs" LinkBase="Shared\Foundry" />
  </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedStructuredOutput)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\StructuredOutput\*.cs" LinkBase="Shared\StructuredOutput" />
-  </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedDiagnosticIds)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\DiagnosticIds\*.cs" LinkBase="Shared\DiagnosticIds" />
-  </ItemGroup>
 </Project>
@@ -2,11 +2,9 @@
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
    <VersionPrefix>1.0.0</VersionPrefix>
-    <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>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260128.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260128.1</PackageVersion>
+    <GitTag>1.0.0-preview.260128.1</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -42,7 +42,7 @@ public static class Program
        // Create the Host agent
        var hostAgent = new HostClientAgent(loggerFactory);
        await hostAgent.InitializeAgentAsync(modelId, apiKey, agentUrls!.Split(";"));
-        AgentSession session = await hostAgent.Agent!.CreateSessionAsync(cancellationToken);
+        AgentSession session = await hostAgent.Agent!.GetNewSessionAsync(cancellationToken);
        try
        {
            while (true)
@@ -14,10 +14,7 @@ internal static class HostAgentFactory
 {
    internal static async Task<(AIAgent, AgentCard)> CreateFoundryHostAgentAsync(string agentType, string model, string endpoint, string assistantId, IList<AITool>? tools = null)
    {
-        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
+        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
        PersistentAgent persistentAgent = await persistentAgentsClient.Administration.GetAgentAsync(assistantId);

        AIAgent agent = await persistentAgentsClient
@@ -88,7 +88,7 @@ public static class Program
            description: "AG-UI Client Agent",
            tools: [changeBackground, readClientClimateSensors]);

-        AgentSession session = await agent.CreateSessionAsync(cancellationToken);
+        AgentSession session = await agent.GetNewSessionAsync(cancellationToken);
        List<ChatMessage> messages = [new(ChatRole.System, "You are a helpful assistant.")];
        try
        {
@@ -24,9 +24,6 @@ internal static class ChatClientAgentFactory
        string endpoint = configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
        s_deploymentName = configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

-        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
        s_azureOpenAIClient = new AzureOpenAIClient(
            new Uri(endpoint),
            new DefaultAzureCredential());
@@ -78,7 +78,7 @@ internal sealed class SharedStateAgent : DelegatingAIAgent

        var response = allUpdates.ToAgentResponse();

-        if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
+        if (response.TryDeserialize(this._jsonSerializerOptions, out JsonElement stateSnapshot))
        {
            byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
                stateSnapshot,
@@ -103,25 +103,4 @@ internal sealed class SharedStateAgent : DelegatingAIAgent
            yield return update;
        }
    }
-
-    private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
-    {
-        try
-        {
-            T? result = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
-            if (result is null)
-            {
-                structuredOutput = default!;
-                return false;
-            }
-
-            structuredOutput = result;
-            return true;
-        }
-        catch
-        {
-            structuredOutput = default!;
-            return false;
-        }
-    }
 }
@@ -19,9 +19,6 @@ string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new In
 string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

 // Create the AI agent with tools
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 var agent = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
@@ -19,9 +19,6 @@ string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new In
 string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

 // Create the AI agent
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient azureOpenAIClient = new(
    new Uri(endpoint),
    new DefaultAzureCredential());
@@ -70,7 +70,7 @@ var knightsKnavesAgentBuilder = builder.AddAIAgent("knights-and-knaves", (sp, ke
        If the user asks a general question about their surrounding, make something up which is consistent with the scenario.
        """, "Narrator");

-    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAIAgent(name: key);
+    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAgent(name: key);
 });

 // Workflow consisting of multiple specialized agents
@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -19,12 +17,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 const string JokerName = "Joker";
@@ -19,7 +19,7 @@ public static class FunctionTriggers
    public static async Task<string> RunOrchestrationAsync([OrchestrationTrigger] TaskOrchestrationContext context)
    {
        DurableAIAgent writer = context.GetAgent("WriterAgent");
-        AgentSession writerSession = await writer.CreateSessionAsync();
+        AgentSession writerSession = await writer.GetNewSessionAsync();

        AgentResponse<TextResponse> initial = await writer.RunAsync<TextResponse>(
            message: "Write a concise inspirational sentence about learning.",
@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -19,12 +17,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Single agent used by the orchestration to demonstrate sequential calls on the same session.
 const string WriterName = "WriterAgent";
@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -19,12 +17,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Two agents used by the orchestration to demonstrate concurrent execution.
 const string PhysicistName = "PhysicistAgent";
@@ -21,7 +21,7 @@ public static class FunctionTriggers

        // Get the spam detection agent
        DurableAIAgent spamDetectionAgent = context.GetAgent("SpamDetectionAgent");
-        AgentSession spamSession = await spamDetectionAgent.CreateSessionAsync();
+        AgentSession spamSession = await spamDetectionAgent.GetNewSessionAsync();

        // Step 1: Check if the email is spam
        AgentResponse<DetectionResult> spamDetectionResponse = await spamDetectionAgent.RunAsync<DetectionResult>(
@@ -43,7 +43,7 @@ public static class FunctionTriggers

        // Generate and send response for legitimate email
        DurableAIAgent emailAssistantAgent = context.GetAgent("EmailAssistantAgent");
-        AgentSession emailSession = await emailAssistantAgent.CreateSessionAsync();
+        AgentSession emailSession = await emailAssistantAgent.GetNewSessionAsync();

        AgentResponse<EmailResponse> emailAssistantResponse = await emailAssistantAgent.RunAsync<EmailResponse>(
            message:
@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -19,12 +17,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Two agents used by the orchestration to demonstrate conditional logic.
 const string SpamDetectionName = "SpamDetectionAgent";
@@ -24,7 +24,7 @@ public static class FunctionTriggers

        // Get the writer agent
        DurableAIAgent writerAgent = context.GetAgent("WriterAgent");
-        AgentSession writerSession = await writerAgent.CreateSessionAsync();
+        AgentSession writerSession = await writerAgent.GetNewSessionAsync();

        // Set initial status
        context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");
@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -19,12 +17,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Single agent used by the orchestration to demonstrate human-in-the-loop workflow.
 const string WriterName = "WriterAgent";
@@ -20,7 +20,7 @@ public static class FunctionTriggers

        // Get the writer agent
        DurableAIAgent writerAgent = context.GetAgent("Writer");
-        AgentSession writerSession = await writerAgent.CreateSessionAsync();
+        AgentSession writerSession = await writerAgent.GetNewSessionAsync();

        // Set initial status
        context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");
@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -23,12 +21,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Agent used by the orchestration to write content.
 const string WriterAgentName = "Writer";
@@ -5,8 +5,6 @@
 // generate a remote MCP endpoint for the app at /runtime/webhooks/mcp with a agent-specific
 // query tool name.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -25,12 +23,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Define three AI agents we are going to use in this application.
 AIAgent agent1 = client.GetChatClient(deploymentName).AsAIAgent("You are good at telling jokes.", "Joker");
@@ -95,7 +95,7 @@ public sealed class FunctionTriggers
        AIAgent agentProxy = durableClient.AsDurableAgentProxy(context, "TravelPlanner");

        // Create a new agent session
-        AgentSession session = await agentProxy.CreateSessionAsync(cancellationToken);
+        AgentSession session = await agentProxy.GetNewSessionAsync(cancellationToken);
        string agentSessionId = session.GetService<AgentSessionId>().ToString();

        this._logger.LogInformation("Creating new agent session: {AgentSessionId}", agentSessionId);
@@ -8,8 +8,6 @@
 // This pattern is inspired by OpenAI's background mode for the Responses API, which allows clients
 // to disconnect and reconnect to ongoing agent responses without losing messages.

-#pragma warning disable IDE0002 // Simplify Member Access
-
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -40,12 +38,9 @@ int redisStreamTtlMinutes = int.TryParse(

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Travel Planner agent instructions - designed to produce longer responses for demonstrating streaming.
 const string TravelPlannerName = "TravelPlanner";
@@ -25,12 +25,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 const string JokerName = "Joker";
@@ -64,7 +61,7 @@ Console.WriteLine("Enter a message for the Joker agent (or 'exit' to quit):");
 Console.WriteLine();

 // Create a session for the conversation
-AgentSession session = await agentProxy.CreateSessionAsync();
+AgentSession session = await agentProxy.GetNewSessionAsync();

 while (true)
 {
@@ -29,12 +29,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Single agent used by the orchestration to demonstrate sequential calls on the same session.
 const string WriterName = "WriterAgent";
@@ -50,7 +47,7 @@ AIAgent writerAgent = client.GetChatClient(deploymentName).AsAIAgent(WriterInstr
 static async Task<string> RunOrchestratorAsync(TaskOrchestrationContext context)
 {
    DurableAIAgent writer = context.GetAgent("WriterAgent");
-    AgentSession writerSession = await writer.CreateSessionAsync();
+    AgentSession writerSession = await writer.GetNewSessionAsync();

    AgentResponse<TextResponse> initial = await writer.RunAsync<TextResponse>(
        message: "Write a concise inspirational sentence about learning.",
@@ -29,12 +29,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Two agents used by the orchestration to demonstrate concurrent execution.
 const string PhysicistName = "PhysicistAgent";
@@ -28,12 +28,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Spam detection agent
 const string SpamDetectionAgentName = "SpamDetectionAgent";
@@ -59,7 +56,7 @@ static async Task<string> RunOrchestratorAsync(TaskOrchestrationContext context,
 {
    // Get the spam detection agent
    DurableAIAgent spamDetectionAgent = context.GetAgent(SpamDetectionAgentName);
-    AgentSession spamSession = await spamDetectionAgent.CreateSessionAsync();
+    AgentSession spamSession = await spamDetectionAgent.GetNewSessionAsync();

    // Step 1: Check if the email is spam
    AgentResponse<DetectionResult> spamDetectionResponse = await spamDetectionAgent.RunAsync<DetectionResult>(
@@ -81,7 +78,7 @@ static async Task<string> RunOrchestratorAsync(TaskOrchestrationContext context,

    // Generate and send response for legitimate email
    DurableAIAgent emailAssistantAgent = context.GetAgent(EmailAssistantAgentName);
-    AgentSession emailSession = await emailAssistantAgent.CreateSessionAsync();
+    AgentSession emailSession = await emailAssistantAgent.GetNewSessionAsync();

    AgentResponse<EmailResponse> emailAssistantResponse = await emailAssistantAgent.RunAsync<EmailResponse>(
        message:
@@ -29,12 +29,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Single agent used by the orchestration to demonstrate human-in-the-loop workflow.
 const string WriterName = "WriterAgent";
@@ -51,7 +48,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
 {
    // Get the writer agent
    DurableAIAgent writerAgent = context.GetAgent("WriterAgent");
-    AgentSession writerSession = await writerAgent.CreateSessionAsync();
+    AgentSession writerSession = await writerAgent.GetNewSessionAsync();

    // Set initial status
    context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");
@@ -30,12 +30,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Agent used by the orchestration to write content.
 const string WriterAgentName = "Writer";
@@ -62,7 +59,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
 {
    // Get the writer agent
    DurableAIAgent writerAgent = context.GetAgent(WriterAgentName);
-    AgentSession writerSession = await writerAgent.CreateSessionAsync();
+    AgentSession writerSession = await writerAgent.GetNewSessionAsync();

    // Set initial status
    context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");
@@ -302,7 +299,7 @@ Console.WriteLine("Enter a topic for the Publisher agent to write about (or 'exi
 Console.WriteLine();

 // Create a session for the conversation
-AgentSession session = await agentProxy.CreateSessionAsync();
+AgentSession session = await agentProxy.GetNewSessionAsync();

 using CancellationTokenSource cts = new();
 Console.CancelKeyPress += (sender, e) =>
@@ -38,12 +38,9 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC

 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());

 // Travel Planner agent instructions - designed to produce longer responses for demonstrating streaming.
 const string TravelPlannerName = "TravelPlanner";
@@ -308,7 +305,7 @@ if (string.IsNullOrWhiteSpace(prompt) || prompt.Equals("exit", StringComparison.
 }

 // Create a new agent session
-AgentSession session = await agentProxy.CreateSessionAsync();
+AgentSession session = await agentProxy.GetNewSessionAsync();
 AgentSessionId sessionId = session.GetService<AgentSessionId>();
 string conversationId = sessionId.ToString();

@@ -0,0 +1,42 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>SingleAgent</AssemblyName>
+    <RootNamespace>SingleAgent</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,215 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace SequentialWorkflow;
+
+/// <summary>
+/// Looks up an order by its ID and return an Order object.
+/// </summary>
+internal sealed class OrderLookup() : Executor<string, Order>("OrderLookup")
+{
+    public override async ValueTask<Order> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] OrderLookup: Starting lookup for order '{message}'");
+        Console.ResetColor();
+
+        // Simulate database lookup with delay
+        await Task.Delay(TimeSpan.FromMicroseconds(100), cancellationToken);
+
+        Order order = new(
+            Id: message,
+            OrderDate: DateTime.UtcNow.AddDays(-1),
+            IsCancelled: false,
+            Customer: new Customer(Name: "Jerry", Email: "jerry@example.com"));
+
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine($"│ [Activity] OrderLookup: Found order '{message}' for customer '{order.Customer.Name}'");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return order;
+    }
+}
+
+/// <summary>
+/// Cancels an order.
+/// </summary>
+internal sealed class OrderCancel() : Executor<Order, Order>("OrderCancel")
+{
+    public override async ValueTask<Order> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] OrderCancel: Starting cancellation for order '{message.Id}'");
+        Console.ResetColor();
+
+        // Simulate a slow cancellation process (e.g., calling external payment system)
+        for (int i = 1; i <= 3; i++)
+        {
+            await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+            Console.ForegroundColor = ConsoleColor.DarkYellow;
+            Console.WriteLine("│ [Activity] OrderCancel: Processing...");
+            Console.ResetColor();
+        }
+
+        Order cancelledOrder = message with { IsCancelled = true };
+
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"│ [Activity] OrderCancel: ✓ Order '{cancelledOrder.Id}' has been cancelled");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return cancelledOrder;
+    }
+}
+
+/// <summary>
+/// Sends a cancellation confirmation email to the customer.
+/// </summary>
+internal sealed class SendEmail() : Executor<Order, string>("SendEmail")
+{
+    public override ValueTask<string> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] SendEmail: Sending email to '{message.Customer.Email}'...");
+        Console.ResetColor();
+
+        string result = $"Cancellation email sent for order {message.Id} to {message.Customer.Email}.";
+
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("│ [Activity] SendEmail: ✓ Email sent successfully!");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(result);
+    }
+}
+
+internal sealed record Order(string Id, DateTime OrderDate, bool IsCancelled, Customer Customer);
+
+internal sealed record Customer(string Name, string Email);
+
+/// <summary>
+/// Represents a batch cancellation request with multiple order IDs and a reason.
+/// This demonstrates using a complex typed object as workflow input.
+/// </summary>
+#pragma warning disable CA1812 // Instantiated via JSON deserialization at runtime
+internal sealed record BatchCancelRequest(string[] OrderIds, string Reason, bool NotifyCustomers);
+#pragma warning restore CA1812
+
+/// <summary>
+/// Represents the result of processing a batch cancellation.
+/// </summary>
+internal sealed record BatchCancelResult(int TotalOrders, int CancelledCount, string Reason);
+
+/// <summary>
+/// Generates a status report for an order.
+/// </summary>
+internal sealed class StatusReport() : Executor<Order, string>("StatusReport")
+{
+    public override ValueTask<string> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] StatusReport: Generating report for order '{message.Id}'");
+        Console.ResetColor();
+
+        string status = message.IsCancelled ? "Cancelled" : "Active";
+        string result = $"Order {message.Id} for {message.Customer.Name}: Status={status}, Date={message.OrderDate:yyyy-MM-dd}";
+
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine($"│ [Activity] StatusReport: ✓ {result}");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(result);
+    }
+}
+
+/// <summary>
+/// Processes a batch cancellation request. Accepts a complex <see cref="BatchCancelRequest"/> object
+/// as input, demonstrating how workflows can receive structured JSON input.
+/// </summary>
+internal sealed class BatchCancelProcessor() : Executor<BatchCancelRequest, BatchCancelResult>("BatchCancelProcessor")
+{
+    public override async ValueTask<BatchCancelResult> HandleAsync(
+        BatchCancelRequest message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] BatchCancelProcessor: Processing {message.OrderIds.Length} orders");
+        Console.WriteLine($"│ [Activity] BatchCancelProcessor: Reason: {message.Reason}");
+        Console.WriteLine($"│ [Activity] BatchCancelProcessor: Notify customers: {message.NotifyCustomers}");
+        Console.ResetColor();
+
+        // Simulate processing each order
+        int cancelledCount = 0;
+        foreach (string orderId in message.OrderIds)
+        {
+            await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+            cancelledCount++;
+            Console.ForegroundColor = ConsoleColor.DarkYellow;
+            Console.WriteLine($"│ [Activity] BatchCancelProcessor: ✓ Cancelled order '{orderId}'");
+            Console.ResetColor();
+        }
+
+        BatchCancelResult result = new(message.OrderIds.Length, cancelledCount, message.Reason);
+
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"│ [Activity] BatchCancelProcessor: ✓ Batch complete: {cancelledCount}/{message.OrderIds.Length} cancelled");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return result;
+    }
+}
+
+/// <summary>
+/// Generates a summary of the batch cancellation.
+/// </summary>
+internal sealed class BatchCancelSummary() : Executor<BatchCancelResult, string>("BatchCancelSummary")
+{
+    public override ValueTask<string> HandleAsync(
+        BatchCancelResult message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine("│ [Activity] BatchCancelSummary: Generating summary");
+        Console.ResetColor();
+
+        string result = $"Batch cancellation complete: {message.CancelledCount}/{message.TotalOrders} orders cancelled. Reason: {message.Reason}";
+
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine($"│ [Activity] BatchCancelSummary: ✓ {result}");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(result);
+    }
+}
@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates three workflows that share executors.
+// The CancelOrder workflow cancels an order and notifies the customer.
+// The OrderStatus workflow looks up an order and generates a status report.
+// The BatchCancelOrders workflow accepts a complex JSON input to cancel multiple orders.
+// Both CancelOrder and OrderStatus reuse the same OrderLookup executor, demonstrating executor sharing.
+
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+using SequentialWorkflow;
+
+// Define executors for all workflows
+OrderLookup orderLookup = new();
+OrderCancel orderCancel = new();
+SendEmail sendEmail = new();
+StatusReport statusReport = new();
+BatchCancelProcessor batchCancelProcessor = new();
+BatchCancelSummary batchCancelSummary = new();
+
+// Build the CancelOrder workflow: OrderLookup -> OrderCancel -> SendEmail
+Workflow cancelOrder = new WorkflowBuilder(orderLookup)
+    .WithName("CancelOrder")
+    .WithDescription("Cancel an order and notify the customer")
+    .AddEdge(orderLookup, orderCancel)
+    .AddEdge(orderCancel, sendEmail)
+    .Build();
+
+// Build the OrderStatus workflow: OrderLookup -> StatusReport
+// This workflow shares the OrderLookup executor with the CancelOrder workflow.
+Workflow orderStatus = new WorkflowBuilder(orderLookup)
+    .WithName("OrderStatus")
+    .WithDescription("Look up an order and generate a status report")
+    .AddEdge(orderLookup, statusReport)
+    .Build();
+
+// Build the BatchCancelOrders workflow: BatchCancelProcessor -> BatchCancelSummary
+// This workflow demonstrates using a complex JSON object as the workflow input.
+Workflow batchCancelOrders = new WorkflowBuilder(batchCancelProcessor)
+    .WithName("BatchCancelOrders")
+    .WithDescription("Cancel multiple orders in a batch using a complex JSON input")
+    .AddEdge(batchCancelProcessor, batchCancelSummary)
+    .Build();
+
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableWorkflows(workflows => workflows.AddWorkflows(cancelOrder, orderStatus, batchCancelOrders))
+    .Build();
+app.Run();
@@ -0,0 +1,100 @@
+# Sequential Workflow Sample
+
+This sample demonstrates how to use the Microsoft Agent Framework to create an Azure Functions app that hosts durable workflows with sequential executor chains. It showcases two workflows that share a common executor, demonstrating executor reuse across workflows.
+
+## Key Concepts Demonstrated
+
+- Defining workflows with sequential executor chains using `WorkflowBuilder`
+- Sharing executors across multiple workflows (the `OrderLookup` executor is used by both workflows)
+- Registering workflows with the Function app using `ConfigureDurableWorkflows`
+- Durable orchestration ensuring workflows survive process restarts and failures
+- Starting workflows via HTTP requests
+- Viewing workflow execution history and status in the Durable Task Scheduler (DTS) dashboard
+
+## Workflows
+
+This sample defines two workflows:
+
+1. **CancelOrder**: `OrderLookup` → `OrderCancel` → `SendEmail` — Looks up an order, cancels it, and sends a confirmation email.
+2. **OrderStatus**: `OrderLookup` → `StatusReport` — Looks up an order and generates a status report.
+
+Both workflows share the `OrderLookup` executor, which is registered only once by the framework.
+
+## 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.
+
+## Running the Sample
+
+With the environment setup and function app running, you can test the sample by sending HTTP requests to the workflow endpoints.
+
+You can use the `demo.http` file to trigger the workflows, or a command line tool like `curl` as shown below:
+
+### Cancel an Order
+
+Bash (Linux/macOS/WSL):
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/CancelOrder/run \
+    -H "Content-Type: text/plain" \
+    -d "12345"
+```
+
+PowerShell:
+
+```powershell
+Invoke-RestMethod -Method Post `
+    -Uri http://localhost:7071/api/workflows/CancelOrder/run `
+    -ContentType text/plain `
+    -Body "12345"
+```
+
+The response will confirm the workflow orchestration has started:
+
+```text
+Workflow orchestration started for CancelOrder. Orchestration runId: abc123def456
+```
+
+> **Tip:** You can provide a custom run ID by appending a `runId` query parameter:
+>
+> ```bash
+> curl -X POST "http://localhost:7071/api/workflows/CancelOrder/run?runId=my-order-123" \
+>     -H "Content-Type: text/plain" \
+>     -d "12345"
+> ```
+>
+> If not provided, a unique run ID is auto-generated.
+
+In the function app logs, you will see the sequential execution of each executor:
+
+```text
+│ [Activity] OrderLookup: Starting lookup for order '12345'
+│ [Activity] OrderLookup: Found order '12345' for customer 'Jerry'
+│ [Activity] OrderCancel: Starting cancellation for order '12345'
+│ [Activity] OrderCancel: ✓ Order '12345' has been cancelled
+│ [Activity] SendEmail: Sending email to 'jerry@example.com'...
+│ [Activity] SendEmail: ✓ Email sent successfully!
+```
+
+### Get Order Status
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/OrderStatus/run \
+    -H "Content-Type: text/plain" \
+    -d "12345"
+```
+
+The `OrderStatus` workflow reuses the same `OrderLookup` executor and then generates a status report:
+
+```text
+│ [Activity] OrderLookup: Starting lookup for order '12345'
+│ [Activity] OrderLookup: Found order '12345' for customer 'Jerry'
+│ [Activity] StatusReport: Generating report for order '12345'
+│ [Activity] StatusReport: ✓ Order 12345 for Jerry: Status=Active, Date=2025-01-01
+```
+
+### Viewing Workflows in the DTS Dashboard
+
+After running a workflow, you can navigate to the Durable Task Scheduler (DTS) dashboard to visualize the completed orchestration, inspect inputs/outputs for each step, and view execution history.
+
+If you are using the DTS emulator, the dashboard is available at `http://localhost:8082`.
@@ -0,0 +1,26 @@
+# Default endpoint address for local testing
+@authority=http://localhost:7071
+
+### Cancel an order
+POST {{authority}}/api/workflows/CancelOrder/run
+Content-Type: text/plain
+
+12345
+
+### Cancel an order with a custom run ID
+POST {{authority}}/api/workflows/CancelOrder/run?runId=my-custom-id-123
+Content-Type: text/plain
+
+99999
+
+### Get order status (shares OrderLookup executor with CancelOrder)
+POST {{authority}}/api/workflows/OrderStatus/run
+Content-Type: text/plain
+
+12345
+
+### Batch cancel orders with a complex JSON input
+POST {{authority}}/api/workflows/BatchCancelOrders/run
+Content-Type: application/json
+
+{"orderIds": ["1001", "1002", "1003"], "reason": "Customer requested cancellation", "notifyCustomers": true}
@@ -0,0 +1,20 @@
+{
+  "version": "2.0",
+  "logging": {
+    "logLevel": {
+      "Microsoft.Agents.AI.DurableTask": "Information",
+      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
+      "DurableTask": "Information",
+      "Microsoft.DurableTask": "Information"
+    }
+  },
+  "extensions": {
+    "durableTask": {
+      "hubName": "default",
+      "storageProvider": {
+        "type": "AzureManaged",
+        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
+      }
+    }
+  }
+}
@@ -0,0 +1,42 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>SingleAgent</AssemblyName>
+    <RootNamespace>SingleAgent</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowConcurrency;
+
+/// <summary>
+/// Parses and validates the incoming question before sending to AI agents.
+/// </summary>
+internal sealed class ParseQuestionExecutor() : Executor<string, string>("ParseQuestion")
+{
+    public override ValueTask<string> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine("│ [ParseQuestion] Preparing question for AI agents...");
+
+        string formattedQuestion = message.Trim();
+        if (!formattedQuestion.EndsWith('?'))
+        {
+            formattedQuestion += "?";
+        }
+
+        Console.WriteLine($"│ [ParseQuestion] Question: \"{formattedQuestion}\"");
+        Console.WriteLine("│ [ParseQuestion] → Sending to Physicist and Chemist in PARALLEL...");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(formattedQuestion);
+    }
+}
+
+/// <summary>
+/// Aggregates responses from all AI agents into a comprehensive answer.
+/// This is the Fan-in point where parallel results are collected.
+/// </summary>
+internal sealed class AggregatorExecutor() : Executor<string[], string>("Aggregator")
+{
+    public override ValueTask<string> HandleAsync(
+        string[] message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Aggregator] 📋 Received {message.Length} AI agent responses");
+        Console.WriteLine("│ [Aggregator] Combining into comprehensive answer...");
+        Console.WriteLine("│ [Aggregator] ✓ Aggregation complete!");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        string aggregatedResult = "═══════════════════════════════════════════════════════════════\n" +
+                                 "                    AI EXPERT PANEL RESPONSES\n" +
+                                 "═══════════════════════════════════════════════════════════════\n\n";
+
+        for (int i = 0; i < message.Length; i++)
+        {
+            string expertLabel = i == 0 ? "⚛️ PHYSICIST" : "🧪 CHEMIST";
+            aggregatedResult += $"{expertLabel}:\n{message[i]}\n\n";
+        }
+
+        aggregatedResult += "═══════════════════════════════════════════════════════════════\n" +
+                          $"Summary: Received perspectives from {message.Length} AI experts.\n" +
+                          "═══════════════════════════════════════════════════════════════";
+
+        return ValueTask.FromResult(aggregatedResult);
+    }
+}
@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+using OpenAI.Chat;
+using WorkflowConcurrency;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT is not set.");
+string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+
+// Create Azure OpenAI client
+AzureOpenAIClient openAiClient = !string.IsNullOrEmpty(azureOpenAiKey)
+    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+ChatClient chatClient = openAiClient.GetChatClient(deploymentName);
+
+// Define the 4 executors for the workflow
+ParseQuestionExecutor parseQuestion = new();
+AIAgent physicist = chatClient.AsAIAgent("You are a physics expert. Be concise (2-3 sentences).", "Physicist");
+AIAgent chemist = chatClient.AsAIAgent("You are a chemistry expert. Be concise (2-3 sentences).", "Chemist");
+AggregatorExecutor aggregator = new();
+
+// Build workflow: ParseQuestion -> [Physicist, Chemist] (parallel) -> Aggregator
+Workflow workflow = new WorkflowBuilder(parseQuestion)
+    .WithName("ExpertReview")
+    .AddFanOutEdge(parseQuestion, [physicist, chemist])
+    .AddFanInEdge([physicist, chemist], aggregator)
+    .Build();
+
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableWorkflows(workflows => workflows.AddWorkflows(workflow))
+    .Build();
+app.Run();
@@ -0,0 +1,90 @@
+# Concurrent Workflow Sample
+
+This sample demonstrates how to use the Microsoft Agent Framework to create an Azure Functions app that orchestrates concurrent execution of multiple AI agents using the fan-out/fan-in pattern within a durable workflow.
+
+## Key Concepts Demonstrated
+
+- Defining workflows with fan-out/fan-in edges for parallel execution using `WorkflowBuilder`
+- Mixing custom executors with AI agents in a single workflow
+- Concurrent execution of multiple AI agents (physics and chemistry experts)
+- Response aggregation from parallel branches into a unified result
+- Durable orchestration with automatic checkpointing and resumption from failures
+- Viewing workflow execution history and status in the Durable Task Scheduler (DTS) dashboard
+
+## Workflow
+
+This sample defines a single workflow:
+
+**ExpertReview**: `ParseQuestion` → [`Physicist`, `Chemist`] (parallel) → `Aggregator`
+
+1. **ParseQuestion** — A custom executor that validates and formats the incoming question.
+2. **Physicist** and **Chemist** — AI agents that run concurrently, each providing an expert perspective.
+3. **Aggregator** — A custom executor that combines the parallel responses into a comprehensive answer.
+
+## 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.
+
+This sample requires Azure OpenAI. Set the following environment variables:
+
+- `AZURE_OPENAI_ENDPOINT` — Your Azure OpenAI endpoint URL.
+- `AZURE_OPENAI_DEPLOYMENT` — The name of your chat model deployment.
+- `AZURE_OPENAI_KEY` (optional) — Your Azure OpenAI API key. If not set, Azure CLI credentials are used.
+
+## Running the Sample
+
+With the environment setup and function app running, you can test the sample by sending an HTTP request with a science question to the workflow endpoint.
+
+You can use the `demo.http` file to trigger the workflow, or a command line tool like `curl` as shown below:
+
+Bash (Linux/macOS/WSL):
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/ExpertReview/run \
+    -H "Content-Type: text/plain" \
+    -d "What is temperature?"
+```
+
+PowerShell:
+
+```powershell
+Invoke-RestMethod -Method Post `
+    -Uri http://localhost:7071/api/workflows/ExpertReview/run `
+    -ContentType text/plain `
+    -Body "What is temperature?"
+```
+
+The response will confirm the workflow orchestration has started:
+
+```text
+Workflow orchestration started for ExpertReview. Orchestration runId: abc123def456
+```
+
+> **Tip:** You can provide a custom run ID by appending a `runId` query parameter:
+>
+> ```bash
+> curl -X POST "http://localhost:7071/api/workflows/ExpertReview/run?runId=my-review-123" \
+>     -H "Content-Type: text/plain" \
+>     -d "What is temperature?"
+> ```
+>
+> If not provided, a unique run ID is auto-generated.
+
+In the function app logs, you will see the fan-out/fan-in execution pattern:
+
+```text
+│ [ParseQuestion] Preparing question for AI agents...
+│ [ParseQuestion] Question: "What is temperature?"
+│ [ParseQuestion] → Sending to Physicist and Chemist in PARALLEL...
+│ [Aggregator] 📋 Received 2 AI agent responses
+│ [Aggregator] Combining into comprehensive answer...
+│ [Aggregator] ✓ Aggregation complete!
+```
+
+The Physicist and Chemist AI agents execute concurrently, and the Aggregator combines their responses into a formatted expert panel result.
+
+### Viewing Workflows in the DTS Dashboard
+
+After running a workflow, you can navigate to the Durable Task Scheduler (DTS) dashboard to visualize the completed orchestration, inspect inputs/outputs for each step, and view execution history.
+
+If you are using the DTS emulator, the dashboard is available at `http://localhost:8082`.
@@ -0,0 +1,14 @@
+# Default endpoint address for local testing
+@authority=http://localhost:7071
+
+### Prompt the agent
+POST {{authority}}/api/workflows/ExpertReview/run
+Content-Type: text/plain
+
+What is temperature?
+
+### Start with a custom run ID
+POST {{authority}}/api/workflows/ExpertReview/run?runId=my-review-123
+Content-Type: text/plain
+
+What is gravity?
@@ -0,0 +1,20 @@
+{
+  "version": "2.0",
+  "logging": {
+    "logLevel": {
+      "Microsoft.Agents.AI.DurableTask": "Information",
+      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
+      "DurableTask": "Information",
+      "Microsoft.DurableTask": "Information"
+    }
+  },
+  "extensions": {
+    "durableTask": {
+      "hubName": "default",
+      "storageProvider": {
+        "type": "AzureManaged",
+        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
+      }
+    }
+  }
+}
@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>SequentialWorkflow</AssemblyName>
+    <RootNamespace>SequentialWorkflow</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace SequentialWorkflow;
+
+/// <summary>
+/// Represents a request to cancel an order.
+/// </summary>
+/// <param name="OrderId">The ID of the order to cancel.</param>
+/// <param name="Reason">The reason for cancellation.</param>
+internal sealed record OrderCancelRequest(string OrderId, string Reason);
+
+/// <summary>
+/// Looks up an order by its ID and return an Order object.
+/// </summary>
+internal sealed class OrderLookup() : Executor<OrderCancelRequest, Order>("OrderLookup")
+{
+    public override async ValueTask<Order> HandleAsync(
+        OrderCancelRequest message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] OrderLookup: Starting lookup for order '{message.OrderId}'");
+        Console.WriteLine($"│ [Activity] OrderLookup: Cancellation reason: '{message.Reason}'");
+        Console.ResetColor();
+
+        // Simulate database lookup with delay
+        await Task.Delay(TimeSpan.FromMicroseconds(100), cancellationToken);
+
+        Order order = new(
+            Id: message.OrderId,
+            OrderDate: DateTime.UtcNow.AddDays(-1),
+            IsCancelled: false,
+            CancelReason: message.Reason,
+            Customer: new Customer(Name: "Jerry", Email: "jerry@example.com"));
+
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine($"│ [Activity] OrderLookup: Found order '{message.OrderId}' for customer '{order.Customer.Name}'");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return order;
+    }
+}
+
+/// <summary>
+/// Cancels an order.
+/// </summary>
+internal sealed class OrderCancel() : Executor<Order, Order>("OrderCancel")
+{
+    public override async ValueTask<Order> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // Log that this activity is executing (not replaying)
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] OrderCancel: Starting cancellation for order '{message.Id}'");
+        Console.ResetColor();
+
+        // Simulate a slow cancellation process (e.g., calling external payment system)
+        for (int i = 1; i <= 3; i++)
+        {
+            await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+            Console.ForegroundColor = ConsoleColor.DarkYellow;
+            Console.WriteLine("│ [Activity] OrderCancel: Processing...");
+            Console.ResetColor();
+        }
+
+        Order cancelledOrder = message with { IsCancelled = true };
+
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"│ [Activity] OrderCancel: ✓ Order '{cancelledOrder.Id}' has been cancelled");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return cancelledOrder;
+    }
+}
+
+/// <summary>
+/// Sends a cancellation confirmation email to the customer.
+/// </summary>
+internal sealed class SendEmail() : Executor<Order, string>("SendEmail")
+{
+    public override ValueTask<string> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Activity] SendEmail: Sending email to '{message.Customer.Email}'...");
+        Console.ResetColor();
+
+        string result = $"Cancellation email sent for order {message.Id} to {message.Customer.Email}.";
+
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("│ [Activity] SendEmail: ✓ Email sent successfully!");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(result);
+    }
+}
+
+internal sealed record Order(string Id, DateTime OrderDate, bool IsCancelled, string? CancelReason, Customer Customer);
+
+internal sealed record Customer(string Name, string Email);
@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using SequentialWorkflow;
+
+// Get DTS connection string from environment variable
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+
+// Define executors for the workflow
+OrderLookup orderLookup = new();
+OrderCancel orderCancel = new();
+SendEmail sendEmail = new();
+
+// Build the CancelOrder workflow: OrderLookup -> OrderCancel -> SendEmail
+Workflow cancelOrder = new WorkflowBuilder(orderLookup)
+    .WithName("CancelOrder")
+    .WithDescription("Cancel an order and notify the customer")
+    .AddEdge(orderLookup, orderCancel)
+    .AddEdge(orderCancel, sendEmail)
+    .Build();
+
+IHost host = Host.CreateDefaultBuilder(args)
+.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+.ConfigureServices(services =>
+{
+    services.ConfigureDurableWorkflows(
+        workflowOptions => workflowOptions.AddWorkflow(cancelOrder),
+        workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+        clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+})
+.Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Durable Workflow Sample");
+Console.WriteLine("Workflow: OrderLookup -> OrderCancel -> SendEmail");
+Console.WriteLine();
+Console.WriteLine("Enter an order ID (or 'exit'):");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        OrderCancelRequest request = new(OrderId: input, Reason: "Customer requested cancellation");
+        await StartNewWorkflowAsync(request, cancelOrder, workflowClient);
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
+
+// Start a new workflow using IWorkflowClient with typed input
+static async Task StartNewWorkflowAsync(OrderCancelRequest request, Workflow workflow, IWorkflowClient client)
+{
+    Console.WriteLine($"Starting workflow for order '{request.OrderId}' (Reason: {request.Reason})...");
+
+    // RunAsync returns IWorkflowRun, cast to IAwaitableWorkflowRun for completion waiting
+    IAwaitableWorkflowRun run = (IAwaitableWorkflowRun)await client.RunAsync(workflow, request);
+    Console.WriteLine($"Run ID: {run.RunId}");
+
+    try
+    {
+        Console.WriteLine("Waiting for workflow to complete...");
+        string? result = await run.WaitForCompletionAsync<string>();
+        Console.WriteLine($"Workflow completed. {result}");
+    }
+    catch (InvalidOperationException ex)
+    {
+        Console.WriteLine($"Failed: {ex.Message}");
+    }
+}
@@ -0,0 +1,83 @@
+# Sequential Workflow Sample
+
+This sample demonstrates how to run a sequential workflow as a durable orchestration from a console application using the Durable Task Framework. It showcases the **durability** aspect - if the process crashes mid-execution, the workflow automatically resumes without re-executing completed activities.
+
+## Key Concepts Demonstrated
+
+- Building a sequential workflow with the `WorkflowBuilder` API
+- Using `ConfigureDurableWorkflows` to register workflows with dependency injection
+- Running workflows with `IWorkflowClient`
+- **Durability**: Automatic resume of interrupted workflows
+- **Activity caching**: Completed activities are not re-executed on replay
+
+## Overview
+
+The sample implements an order cancellation workflow with three executors:
+
+```
+OrderLookup --> OrderCancel --> SendEmail
+```
+
+| Executor | Description |
+|----------|-------------|
+| OrderLookup | Looks up an order by ID |
+| OrderCancel | Marks the order as cancelled |
+| SendEmail | Sends a cancellation confirmation email |
+
+## Durability Demonstration
+
+The key feature of Durable Task Framework is **durability**:
+
+- **Activity results are persisted**: When an activity completes, its result is saved
+- **Orchestrations replay**: On restart, the orchestration replays from the beginning
+- **Completed activities skip execution**: The framework uses cached results
+- **Automatic resume**: The worker automatically picks up pending work on startup
+
+### Try It Yourself
+
+> **Tip:** To give yourself more time to stop the application during `OrderCancel`, consider increasing the loop iteration count or `Task.Delay` duration in the `OrderCancel` executor in `OrderCancelExecutors.cs`.
+
+1. Start the application and enter an order ID (e.g., `12345`)
+2. Wait for `OrderLookup` to complete, then stop the app (Ctrl+C) during `OrderCancel`
+3. Restart the application
+4. Observe:
+   - `OrderLookup` is **NOT** re-executed (result was cached)
+   - `OrderCancel` **restarts** (it didn't complete before the interruption)
+   - `SendEmail` runs after `OrderCancel` completes
+
+## Environment Setup
+
+See the [README.md](../README.md) file in the parent directory for information on configuring the environment, including how to install and run the Durable Task Scheduler.
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow
+dotnet run --framework net10.0
+```
+
+### Sample Output
+
+```text
+Durable Workflow Sample
+Workflow: OrderLookup -> OrderCancel -> SendEmail
+
+Enter an order ID (or 'exit'):
+> 12345
+Starting workflow for order: 12345
+Run ID: abc123...
+
+[OrderLookup] Looking up order '12345'...
+[OrderLookup] Found order for customer 'Jerry'
+
+[OrderCancel] Cancelling order '12345'...
+[OrderCancel] Order cancelled successfully
+
+[SendEmail] Sending email to 'jerry@example.com'...
+[SendEmail] Email sent successfully
+
+Workflow completed!
+
+> exit
+```
+
@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>WorkflowConcurrency</AssemblyName>
+    <RootNamespace>WorkflowConcurrency</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowConcurrency;
+
+/// <summary>
+/// Parses and validates the incoming question before sending to AI agents.
+/// </summary>
+internal sealed class ParseQuestionExecutor() : Executor<string, string>("ParseQuestion")
+{
+    public override ValueTask<string> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine("│ [ParseQuestion] Preparing question for AI agents...");
+
+        string formattedQuestion = message.Trim();
+        if (!formattedQuestion.EndsWith('?'))
+        {
+            formattedQuestion += "?";
+        }
+
+        Console.WriteLine($"│ [ParseQuestion] Question: \"{formattedQuestion}\"");
+        Console.WriteLine("│ [ParseQuestion] → Sending to Physicist and Chemist in PARALLEL...");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(formattedQuestion);
+    }
+}
+
+/// <summary>
+/// Aggregates responses from all AI agents into a comprehensive answer.
+/// This is the Fan-in point where parallel results are collected.
+/// </summary>
+internal sealed class AggregatorExecutor() : Executor<string[], string>("Aggregator")
+{
+    public override ValueTask<string> HandleAsync(
+        string[] message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Aggregator] 📋 Received {message.Length} AI agent responses");
+        Console.WriteLine("│ [Aggregator] Combining into comprehensive answer...");
+        Console.WriteLine("│ [Aggregator] ✓ Aggregation complete!");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        string aggregatedResult = "═══════════════════════════════════════════════════════════════\n" +
+                                 "                    AI EXPERT PANEL RESPONSES\n" +
+                                 "═══════════════════════════════════════════════════════════════\n\n";
+
+        for (int i = 0; i < message.Length; i++)
+        {
+            string expertLabel = i == 0 ? "⚛️ PHYSICIST" : "🧪 CHEMIST";
+            aggregatedResult += $"{expertLabel}:\n{message[i]}\n\n";
+        }
+
+        aggregatedResult += "═══════════════════════════════════════════════════════════════\n" +
+                          $"Summary: Received perspectives from {message.Length} AI experts.\n" +
+                          "═══════════════════════════════════════════════════════════════";
+
+        return ValueTask.FromResult(aggregatedResult);
+    }
+}
@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates the Fan-out/Fan-in pattern in a durable workflow.
+// The workflow uses 4 executors: 2 class-based executors and 2 AI agents.
+//
+// WORKFLOW PATTERN:
+//
+//                  ParseQuestion (class-based)
+//                         |
+//              +----------+----------+
+//              |                     |
+//          Physicist              Chemist
+//          (AI Agent)            (AI Agent)
+//              |                     |
+//              +----------+----------+
+//                         |
+//                    Aggregator (class-based)
+
+using Azure;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using OpenAI.Chat;
+using WorkflowConcurrency;
+
+// Configuration
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT is not set.");
+string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+
+// Create Azure OpenAI client
+AzureOpenAIClient openAiClient = !string.IsNullOrEmpty(azureOpenAiKey)
+    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+ChatClient chatClient = openAiClient.GetChatClient(deploymentName);
+
+// Define the 4 executors for the workflow
+ParseQuestionExecutor parseQuestion = new();
+AIAgent physicist = chatClient.AsAIAgent("You are a physics expert. Be concise (2-3 sentences).", "Physicist");
+AIAgent chemist = chatClient.AsAIAgent("You are a chemistry expert. Be concise (2-3 sentences).", "Chemist");
+AggregatorExecutor aggregator = new();
+
+// Build workflow: ParseQuestion -> [Physicist, Chemist] (parallel) -> Aggregator
+Workflow workflow = new WorkflowBuilder(parseQuestion)
+    .WithName("ExpertReview")
+    .AddFanOutEdge(parseQuestion, [physicist, chemist])
+    .AddFanInEdge([physicist, chemist], aggregator)
+    .Build();
+
+// Configure and start the host
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+    .ConfigureServices(services =>
+    {
+        services.ConfigureDurableOptions(
+            options => options.Workflows.AddWorkflow(workflow),
+            workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+            clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+    })
+    .Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Fan-out/Fan-in Workflow Sample");
+Console.WriteLine("ParseQuestion -> [Physicist, Chemist] -> Aggregator");
+Console.WriteLine();
+Console.WriteLine("Enter a science question (or 'exit' to quit):");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        IWorkflowRun run = await workflowClient.RunAsync(workflow, input);
+        Console.WriteLine($"Run ID: {run.RunId}");
+
+        if (run is IAwaitableWorkflowRun awaitableRun)
+        {
+            string? result = await awaitableRun.WaitForCompletionAsync<string>();
+
+            Console.WriteLine("Workflow completed!");
+            Console.WriteLine(result);
+        }
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
@@ -0,0 +1,100 @@
+# Concurrent Workflow Sample (Fan-Out/Fan-In)
+
+This sample demonstrates the **fan-out/fan-in** pattern in a durable workflow, combining class-based executors with AI agents running in parallel.
+
+## Key Concepts Demonstrated
+
+- **Fan-out/Fan-in pattern**: Parallel execution with result aggregation
+- **Mixed executor types**: Class-based executors and AI agents in the same workflow
+- **AI agents as executors**: Using `ChatClient.AsAIAgent()` to create workflow-compatible agents
+- **Workflow registration**: Auto-registration of agents used within workflows
+- **Standalone agents**: Registering agents outside of workflows
+
+## Overview
+
+The sample implements an expert review workflow with four executors:
+
+```
+                    ParseQuestion
+                         |
+              +----------+----------+
+              |                     |
+          Physicist              Chemist
+          (AI Agent)            (AI Agent)
+              |                     |
+              +----------+----------+
+                         |
+                    Aggregator
+```
+
+| Executor | Type | Description |
+|----------|------|-------------|
+| ParseQuestion | Class-based | Parses the user's question for expert review |
+| Physicist | AI Agent | Provides physics perspective (runs in parallel) |
+| Chemist | AI Agent | Provides chemistry perspective (runs in parallel) |
+| Aggregator | Class-based | Combines expert responses into a final answer |
+
+## Fan-Out/Fan-In Pattern
+
+The workflow demonstrates the fan-out/fan-in pattern:
+
+1. **Fan-out**: `ParseQuestion` sends the question to both `Physicist` and `Chemist` simultaneously
+2. **Parallel execution**: Both AI agents process the question concurrently
+3. **Fan-in**: `Aggregator` waits for both agents to complete, then combines their responses
+
+This pattern is useful for:
+- Gathering multiple perspectives on a problem
+- Parallel processing of independent tasks
+- Reducing overall execution time through concurrency
+
+## Environment Setup
+
+See the [README.md](../README.md) file in the parent directory for information on configuring the environment.
+
+### Required Environment Variables
+
+```bash
+# Durable Task Scheduler (optional, defaults to localhost)
+DURABLE_TASK_SCHEDULER_CONNECTION_STRING="Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+
+# Azure OpenAI (required)
+AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+AZURE_OPENAI_DEPLOYMENT="gpt-4o"
+AZURE_OPENAI_KEY="your-key"  # Optional if using Azure CLI credentials
+```
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow
+dotnet run --framework net10.0
+```
+
+### Sample Output
+
+```text
+-----------------------------------------------------------------------+
+|  Fan-out/Fan-in Workflow Sample (4 Executors)                         |
+|                                                                       |
+|  ParseQuestion -> [Physicist, Chemist] -> Aggregator                  |
+|  (class-based)    (AI agents, parallel)  (class-based)                |
+-----------------------------------------------------------------------+
+
+Enter a science question (or 'exit' to quit):
+
+Question: Why is the sky blue?
+Instance: abc123...
+
+[ParseQuestion] Parsing question for expert review...
+[Physicist] Analyzing from physics perspective...
+[Chemist] Analyzing from chemistry perspective...
+[Aggregator] Combining expert responses...
+
+Workflow completed!
+
+Physics perspective: The sky appears blue due to Rayleigh scattering...
+Chemistry perspective: The molecular composition of our atmosphere...
+Combined answer: ...
+
+Question: exit
+```
@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>ConditionalEdges</AssemblyName>
+    <RootNamespace>ConditionalEdges</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace ConditionalEdges;
+
+internal sealed class Order
+{
+    public Order(string id, decimal amount)
+    {
+        this.Id = id;
+        this.Amount = amount;
+    }
+    public string Id { get; }
+    public decimal Amount { get; }
+    public Customer? Customer { get; set; }
+    public string? PaymentReferenceNumber { get; set; }
+}
+
+public sealed record Customer(int Id, string Name, bool IsBlocked);
+
+internal sealed class OrderIdParser() : Executor<string, Order>("OrderIdParser")
+{
+    public override async ValueTask<Order> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        return GetOrder(message);
+    }
+
+    private static Order GetOrder(string id)
+    {
+        // Simulate fetching order details
+        return new Order(id, 100.0m);
+    }
+}
+
+internal sealed class OrderEnrich() : Executor<Order, Order>("EnrichOrder")
+{
+    public override async ValueTask<Order> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        message.Customer = GetCustomerForOrder(message.Id);
+        return message;
+    }
+
+    private static Customer GetCustomerForOrder(string orderId)
+    {
+        if (orderId.Contains('B'))
+        {
+            return new Customer(101, "George", true);
+        }
+
+        return new Customer(201, "Jerry", false);
+    }
+}
+
+internal sealed class PaymentProcesser() : Executor<Order, Order>("PaymentProcesser")
+{
+    public override async ValueTask<Order> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Call payment gateway.
+        message.PaymentReferenceNumber = Guid.NewGuid().ToString().Substring(0, 4);
+        return message;
+    }
+}
+
+internal sealed class NotifyFraud() : Executor<Order, string>("NotifyFraud")
+{
+    public override async ValueTask<string> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Notify fraud team.
+        return $"Order {message.Id} flagged as fraudulent for customer {message.Customer?.Name}.";
+    }
+}
+
+internal static class OrderRouteConditions
+{
+    /// <summary>
+    /// Returns a condition that evaluates to true when the customer is blocked.
+    /// </summary>
+    internal static Func<Order?, bool> WhenBlocked() => order => order?.Customer?.IsBlocked == true;
+
+    /// <summary>
+    /// Returns a condition that evaluates to true when the customer is not blocked.
+    /// </summary>
+    internal static Func<Order?, bool> WhenNotBlocked() => order => order?.Customer?.IsBlocked == false;
+}
@@ -0,0 +1,97 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates conditional edges in a workflow.
+// Orders are routed to different executors based on customer status:
+// - Blocked customers → NotifyFraud
+// - Valid customers → PaymentProcessor
+
+using ConditionalEdges;
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+
+// Create executor instances
+OrderIdParser orderParser = new();
+OrderEnrich orderEnrich = new();
+PaymentProcesser paymentProcessor = new();
+NotifyFraud notifyFraud = new();
+
+// Build workflow with conditional edges
+// The condition functions evaluate the Order output from OrderEnrich
+WorkflowBuilder builder = new(orderParser);
+builder
+    .AddEdge(orderParser, orderEnrich)
+    .AddEdge(orderEnrich, notifyFraud, condition: OrderRouteConditions.WhenBlocked())
+    .AddEdge(orderEnrich, paymentProcessor, condition: OrderRouteConditions.WhenNotBlocked());
+
+Workflow auditOrder = builder.WithName("AuditOrder").Build();
+
+IHost host = Host.CreateDefaultBuilder(args)
+.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+.ConfigureServices(services =>
+{
+    services.ConfigureDurableWorkflows(
+        workflowOptions => workflowOptions.AddWorkflow(auditOrder),
+        workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+        clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+})
+.Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Enter an order ID (or 'exit'):");
+Console.WriteLine("Tip: Order IDs containing 'B' are flagged as blocked customers.\n");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        await StartNewWorkflowAsync(input, auditOrder, workflowClient);
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
+
+// Start a new workflow and wait for completion
+static async Task StartNewWorkflowAsync(string orderId, Workflow workflow, IWorkflowClient client)
+{
+    Console.WriteLine($"Starting workflow for order '{orderId}'...");
+
+    // Cast to IAwaitableWorkflowRun to access WaitForCompletionAsync
+    IAwaitableWorkflowRun run = (IAwaitableWorkflowRun)await client.RunAsync(workflow, orderId);
+    Console.WriteLine($"Run ID: {run.RunId}");
+
+    try
+    {
+        Console.WriteLine("Waiting for workflow to complete...");
+        string? result = await run.WaitForCompletionAsync<string>();
+        Console.WriteLine($"Workflow completed. {result}");
+    }
+    catch (InvalidOperationException ex)
+    {
+        Console.WriteLine($"Failed: {ex.Message}");
+    }
+}
@@ -0,0 +1,92 @@
+# Conditional Edges Workflow Sample
+
+This sample demonstrates how to build a workflow with **conditional edges** that route execution to different paths based on runtime conditions. The workflow evaluates conditions on the output of an executor to determine which downstream executor to run.
+
+## Key Concepts Demonstrated
+
+- Building workflows with **conditional edges** using `AddEdge` with a `condition` parameter
+- Defining reusable condition functions for routing logic
+- Branching workflow execution based on data-driven decisions
+- Using `ConfigureDurableWorkflows` to register workflows with dependency injection
+
+## Overview
+
+The sample implements an order audit workflow that routes orders differently based on whether the customer is blocked (flagged for fraud):
+
+```
+OrderIdParser --> OrderEnrich --[IsBlocked]--> NotifyFraud
+                              |
+                              +--[NotBlocked]--> PaymentProcessor
+```
+
+| Executor | Description |
+|----------|-------------|
+| OrderIdParser | Parses the order ID and retrieves order details |
+| OrderEnrich | Enriches the order with customer information |
+| PaymentProcessor | Processes payment for valid orders |
+| NotifyFraud | Notifies the fraud team for blocked customers |
+
+## How Conditional Edges Work
+
+Conditional edges allow you to specify a condition function that determines whether the edge should be traversed:
+
+```csharp
+builder
+    .AddEdge(orderParser, orderEnrich)
+    .AddEdge(orderEnrich, notifyFraud, condition: OrderRouteConditions.WhenBlocked())
+    .AddEdge(orderEnrich, paymentProcessor, condition: OrderRouteConditions.WhenNotBlocked());
+```
+
+The condition functions receive the output of the source executor and return a boolean:
+
+```csharp
+internal static class OrderRouteConditions
+{
+    // Routes to NotifyFraud when customer is blocked
+    internal static Func<Order?, bool> WhenBlocked() => 
+        order => order?.Customer?.IsBlocked == true;
+
+    // Routes to PaymentProcessor when customer is not blocked
+    internal static Func<Order?, bool> WhenNotBlocked() => 
+        order => order?.Customer?.IsBlocked == false;
+}
+```
+
+### Routing Logic
+
+In this sample, the routing is based on the order ID:
+- Order IDs containing the letter **'B'** are associated with blocked customers ? routed to `NotifyFraud`
+- All other order IDs are associated with valid customers ? routed to `PaymentProcessor`
+
+## Environment Setup
+
+See the [README.md](../README.md) file in the parent directory for information on configuring the environment, including how to install and run the Durable Task Scheduler.
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges
+dotnet run --framework net10.0
+```
+
+### Sample Output
+
+**Valid order (routes to PaymentProcessor):**
+```text
+Enter an order ID (or 'exit'):
+> 12345
+Starting workflow for order '12345'...
+Run ID: abc123...
+Waiting for workflow to complete...
+Workflow completed. {"Id":"12345","Amount":100.0,"Customer":{"Id":201,"Name":"Jerry","IsBlocked":false},"PaymentReferenceNumber":"a1b2"}
+```
+
+**Blocked order (routes to NotifyFraud):**
+```text
+Enter an order ID (or 'exit'):
+> 12345B
+Starting workflow for order '12345B'...
+Run ID: def456...
+Waiting for workflow to complete...
+Workflow completed. Order 12345B flagged as fraudulent for customer George.
+```
@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>WorkflowConcurrency</AssemblyName>
+    <RootNamespace>WorkflowConcurrency</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowConcurrency;
+
+/// <summary>
+/// Parses and validates the incoming question before sending to AI agents.
+/// </summary>
+internal sealed class ParseQuestionExecutor() : Executor<string, string>("ParseQuestion")
+{
+    public override ValueTask<string> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Magenta;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine("│ [ParseQuestion] Preparing question for AI agents...");
+
+        string formattedQuestion = message.Trim();
+        if (!formattedQuestion.EndsWith('?'))
+        {
+            formattedQuestion += "?";
+        }
+
+        Console.WriteLine($"│ [ParseQuestion] Question: \"{formattedQuestion}\"");
+        Console.WriteLine("│ [ParseQuestion] → Sending to experts...");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult(formattedQuestion);
+    }
+}
+
+/// <summary>
+/// Aggregates responses from multiple AI agents into a unified response.
+/// This executor collects all expert opinions and synthesizes them.
+/// </summary>
+internal sealed class ResponseAggregatorExecutor() : Executor<string[], string>("ResponseAggregator")
+{
+    public override ValueTask<string> HandleAsync(
+        string[] message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [Aggregator] 📋 Received {message.Length} AI agent responses");
+        Console.WriteLine("│ [Aggregator] Combining into comprehensive answer...");
+        Console.WriteLine("│ [Aggregator] ✓ Aggregation complete!");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        string aggregatedResult = "═══════════════════════════════════════════════════════════════\n" +
+                                 "                    AI EXPERT PANEL RESPONSES\n" +
+                                 "═══════════════════════════════════════════════════════════════\n\n";
+
+        for (int i = 0; i < message.Length; i++)
+        {
+            string expertLabel = i == 0 ? "⚛️ PHYSICIST" : "🧪 CHEMIST";
+            aggregatedResult += $"{expertLabel}:\n{message[i]}\n\n";
+        }
+
+        aggregatedResult += "═══════════════════════════════════════════════════════════════\n" +
+                          $"Summary: Received perspectives from {message.Length} AI experts.\n" +
+                          "═══════════════════════════════════════════════════════════════";
+
+        return ValueTask.FromResult(aggregatedResult);
+    }
+}
@@ -0,0 +1,133 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates the THREE ways to configure durable agents and workflows:
+//
+// 1. ConfigureDurableAgents()   - For standalone agents only
+// 2. ConfigureDurableWorkflows() - For workflows only
+// 3. ConfigureDurableOptions()   - For both agents AND workflows
+//
+// KEY: All methods can be called MULTIPLE times - configurations are ADDITIVE.
+
+using Azure;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using OpenAI.Chat;
+using WorkflowConcurrency;
+
+// Configuration
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT is not set.");
+string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+
+// Create AI agents
+AzureOpenAIClient openAiClient = !string.IsNullOrEmpty(azureOpenAiKey)
+    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+ChatClient chatClient = openAiClient.GetChatClient(deploymentName);
+
+AIAgent biologist = chatClient.AsAIAgent("You are a biology expert. Explain concepts clearly in 2-3 sentences.", "Biologist");
+AIAgent physicist = chatClient.AsAIAgent("You are a physics expert. Explain concepts clearly in 2-3 sentences.", "Physicist");
+AIAgent chemist = chatClient.AsAIAgent("You are a chemistry expert. Explain concepts clearly in 2-3 sentences.", "Chemist");
+
+// Create workflows
+ParseQuestionExecutor questionParser = new();
+ResponseAggregatorExecutor responseAggregator = new();
+
+Workflow physicsWorkflow = new WorkflowBuilder(questionParser)
+    .WithName("PhysicsExpertReview")
+    .AddEdge(questionParser, physicist)
+    .Build();
+
+Workflow expertTeamWorkflow = new WorkflowBuilder(questionParser)
+.WithName("ExpertTeamReview")
+.AddFanOutEdge(questionParser, [biologist, physicist])
+.AddFanInEdge([biologist, physicist], responseAggregator)
+.Build();
+
+Workflow chemistryWorkflow = new WorkflowBuilder(questionParser)
+    .WithName("ChemistryExpertReview")
+    .AddEdge(questionParser, chemist)
+    .Build();
+
+// Configure services - demonstrating all 3 methods (each can be called multiple times)
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+    .ConfigureServices(services =>
+    {
+        // METHOD 1: ConfigureDurableAgents - for standalone agents only
+        services.ConfigureDurableAgents(
+            options => options.AddAIAgent(biologist),
+            workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+            clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+
+        // METHOD 2: ConfigureDurableWorkflows - for workflows only
+        services.ConfigureDurableWorkflows(options => options.AddWorkflow(physicsWorkflow));
+
+        // METHOD 3: ConfigureDurableOptions - for both agents AND workflows
+        services.ConfigureDurableOptions(options =>
+        {
+            options.Agents.AddAIAgent(chemist);
+            options.Workflows.AddWorkflow(expertTeamWorkflow);
+        });
+
+        // Second call to ConfigureDurableOptions (additive - adds to existing config)
+        services.ConfigureDurableOptions(options => options.Workflows.AddWorkflow(chemistryWorkflow));
+    })
+    .Build();
+
+await host.StartAsync();
+IServiceProvider services = host.Services;
+IWorkflowClient workflowClient = services.GetRequiredService<IWorkflowClient>();
+
+// DEMO 1: Direct agent conversation (standalone agents)
+Console.WriteLine("\n═══ DEMO 1: Direct Agent Conversation ═══\n");
+
+AIAgent biologistProxy = services.GetRequiredKeyedService<AIAgent>("Biologist");
+AgentSession session = await biologistProxy.GetNewSessionAsync();
+AgentResponse response = await biologistProxy.RunAsync("What is photosynthesis?", session);
+Console.WriteLine($"🧬 Biologist: {response.Text}\n");
+
+AIAgent chemistProxy = services.GetRequiredKeyedService<AIAgent>("Chemist");
+session = await chemistProxy.GetNewSessionAsync();
+response = await chemistProxy.RunAsync("What is a chemical bond?", session);
+Console.WriteLine($"🧪 Chemist: {response.Text}\n");
+
+// DEMO 2: Single-agent workflow
+Console.WriteLine("═══ DEMO 2: Single-Agent Workflow ═══\n");
+await RunWorkflowAsync(workflowClient, physicsWorkflow, "What is the relationship between energy and mass?");
+
+// DEMO 3: Multi-agent workflow
+Console.WriteLine("═══ DEMO 3: Multi-Agent Workflow ═══\n");
+await RunWorkflowAsync(workflowClient, expertTeamWorkflow, "How does radiation affect living cells?");
+
+// DEMO 4: Workflow from second ConfigureDurableOptions call
+Console.WriteLine("═══ DEMO 4: Workflow (added via 2nd ConfigureDurableOptions) ═══\n");
+await RunWorkflowAsync(workflowClient, chemistryWorkflow, "What happens during combustion?");
+
+Console.WriteLine("\n✅ All demos completed!");
+await host.StopAsync();
+
+// Helper method
+static async Task RunWorkflowAsync(IWorkflowClient client, Workflow workflow, string question)
+{
+    Console.WriteLine($"📋 {workflow.Name}: \"{question}\"");
+    IWorkflowRun run = await client.RunAsync(workflow, question);
+    if (run is IAwaitableWorkflowRun awaitable)
+    {
+        string? result = await awaitable.WaitForCompletionAsync<string>();
+        Console.WriteLine($"✅ {result}\n");
+    }
+}
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>WorkflowEvents</AssemblyName>
+    <RootNamespace>WorkflowEvents</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,129 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowEvents;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Custom event types - callers observe these via WatchStreamAsync
+// ═══════════════════════════════════════════════════════════════════════════════
+
+internal sealed class OrderLookupStartedEvent(string orderId) : WorkflowEvent(orderId)
+{
+    public string OrderId { get; } = orderId;
+}
+
+internal sealed class OrderFoundEvent(string customerName) : WorkflowEvent(customerName)
+{
+    public string CustomerName { get; } = customerName;
+}
+
+internal sealed class CancellationProgressEvent(int percentComplete, string status) : WorkflowEvent(status)
+{
+    public int PercentComplete { get; } = percentComplete;
+    public string Status { get; } = status;
+}
+
+internal sealed class OrderCancelledEvent() : WorkflowEvent("Order cancelled");
+
+internal sealed class EmailSentEvent(string email) : WorkflowEvent(email)
+{
+    public string Email { get; } = email;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Domain models
+// ═══════════════════════════════════════════════════════════════════════════════
+
+internal sealed record Order(string Id, DateTime OrderDate, bool IsCancelled, string? CancelReason, Customer Customer);
+
+internal sealed record Customer(string Name, string Email);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Executors - emit events via AddEventAsync and YieldOutputAsync
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// <summary>
+/// Looks up an order by ID, emitting progress events.
+/// </summary>
+internal sealed class OrderLookup() : Executor<string, Order>("OrderLookup")
+{
+    public override async ValueTask<Order> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        await context.AddEventAsync(new OrderLookupStartedEvent(message), cancellationToken);
+
+        // Simulate database lookup
+        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
+
+        Order order = new(
+            Id: message,
+            OrderDate: DateTime.UtcNow.AddDays(-1),
+            IsCancelled: false,
+            CancelReason: "Customer requested cancellation",
+            Customer: new Customer(Name: "Jerry", Email: "jerry@example.com"));
+
+        await context.AddEventAsync(new OrderFoundEvent(order.Customer.Name), cancellationToken);
+
+        // YieldOutputAsync emits a WorkflowOutputEvent observable via streaming
+        await context.YieldOutputAsync(order, cancellationToken);
+
+        return order;
+    }
+}
+
+/// <summary>
+/// Cancels an order, emitting progress events during the multi-step process.
+/// </summary>
+internal sealed class OrderCancel() : Executor<Order, Order>("OrderCancel")
+{
+    public override async ValueTask<Order> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        await context.AddEventAsync(new CancellationProgressEvent(0, "Starting cancellation"), cancellationToken);
+
+        // Simulate a multi-step cancellation process
+        await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken);
+        await context.AddEventAsync(new CancellationProgressEvent(33, "Contacting payment provider"), cancellationToken);
+
+        await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken);
+        await context.AddEventAsync(new CancellationProgressEvent(66, "Processing refund"), cancellationToken);
+
+        await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken);
+
+        Order cancelledOrder = message with { IsCancelled = true };
+        await context.AddEventAsync(new CancellationProgressEvent(100, "Complete"), cancellationToken);
+        await context.AddEventAsync(new OrderCancelledEvent(), cancellationToken);
+
+        await context.YieldOutputAsync(cancelledOrder, cancellationToken);
+
+        return cancelledOrder;
+    }
+}
+
+/// <summary>
+/// Sends a cancellation confirmation email, emitting an event on completion.
+/// </summary>
+internal sealed class SendEmail() : Executor<Order, string>("SendEmail")
+{
+    public override async ValueTask<string> HandleAsync(
+        Order message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // Simulate sending email
+        await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken);
+
+        string result = $"Cancellation email sent for order {message.Id} to {message.Customer.Email}.";
+
+        await context.AddEventAsync(new EmailSentEvent(message.Customer.Email), cancellationToken);
+
+        await context.YieldOutputAsync(result, cancellationToken);
+
+        return result;
+    }
+}
@@ -0,0 +1,138 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SAMPLE: Workflow Events and Streaming
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// This sample demonstrates how to use IWorkflowContext event methods in executors
+// and stream events from the caller side:
+//
+// 1. AddEventAsync     - Emit custom events that callers can observe in real-time
+// 2. StreamAsync       - Start a workflow and obtain a streaming handle
+// 3. WatchStreamAsync  - Observe events as they occur (custom, framework, and terminal)
+//
+// The sample uses IWorkflowClient.StreamAsync to start a workflow and
+// WatchStreamAsync to observe events as they occur in real-time.
+//
+// Workflow: OrderLookup -> OrderCancel -> SendEmail
+// ═══════════════════════════════════════════════════════════════════════════════
+
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using WorkflowEvents;
+
+// Get DTS connection string from environment variable
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+
+// Define executors and build workflow
+OrderLookup orderLookup = new();
+OrderCancel orderCancel = new();
+SendEmail sendEmail = new();
+
+Workflow cancelOrder = new WorkflowBuilder(orderLookup)
+    .WithName("CancelOrder")
+    .WithDescription("Cancel an order and notify the customer")
+    .AddEdge(orderLookup, orderCancel)
+    .AddEdge(orderCancel, sendEmail)
+    .Build();
+
+// Configure host with durable workflow support
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+    .ConfigureServices(services =>
+    {
+        services.ConfigureDurableWorkflows(
+            workflowOptions => workflowOptions.AddWorkflow(cancelOrder),
+            workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+            clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+    })
+    .Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Workflow Events Demo - Enter order ID (or 'exit'):");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        await RunWorkflowWithStreamingAsync(input, cancelOrder, workflowClient);
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
+
+// Runs a workflow and streams events as they occur
+static async Task RunWorkflowWithStreamingAsync(string orderId, Workflow workflow, IWorkflowClient client)
+{
+    // StreamAsync starts the workflow and returns a streaming handle for observing events
+    IStreamingWorkflowRun run = await client.StreamAsync(workflow, orderId);
+    Console.WriteLine($"Started run: {run.RunId}");
+
+    // WatchStreamAsync yields events as they're emitted by executors
+    await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+    {
+        Console.WriteLine($"  New event received at {DateTime.Now:HH:mm:ss.ffff} ({evt.GetType().Name})");
+
+        switch (evt)
+        {
+            // Custom domain events (emitted via AddEventAsync)
+            case OrderLookupStartedEvent e:
+                WriteColored($"    [Lookup] Looking up order {e.OrderId}", ConsoleColor.Cyan);
+                break;
+            case OrderFoundEvent e:
+                WriteColored($"    [Lookup] Found: {e.CustomerName}", ConsoleColor.Cyan);
+                break;
+            case CancellationProgressEvent e:
+                WriteColored($"    [Cancel] {e.PercentComplete}% - {e.Status}", ConsoleColor.Yellow);
+                break;
+            case OrderCancelledEvent:
+                WriteColored("    [Cancel] Done", ConsoleColor.Yellow);
+                break;
+            case EmailSentEvent e:
+                WriteColored($"    [Email] Sent to {e.Email}", ConsoleColor.Magenta);
+                break;
+
+            case WorkflowOutputEvent e:
+                WriteColored($"    [Output] {e.SourceId}", ConsoleColor.DarkGray);
+                break;
+
+            // Workflow completion
+            case DurableWorkflowCompletedEvent e:
+                WriteColored($"  Completed: {e.Result}", ConsoleColor.Green);
+                break;
+            case DurableWorkflowFailedEvent e:
+                WriteColored($"  Failed: {e.ErrorMessage}", ConsoleColor.Red);
+                break;
+        }
+    }
+}
+
+static void WriteColored(string message, ConsoleColor color)
+{
+    Console.ForegroundColor = color;
+    Console.WriteLine(message);
+    Console.ResetColor();
+}
@@ -0,0 +1,127 @@
+# Workflow Events Sample
+
+This sample demonstrates how to use workflow events and streaming in durable workflows.
+
+## What it demonstrates
+
+1. **Custom Events** (`AddEventAsync`) — Executors emit domain-specific events during execution
+2. **Event Streaming** (`StreamAsync` / `WatchStreamAsync`) — Callers observe events in real-time as the workflow progresses
+3. **Framework Events** — Automatic `ExecutorInvokedEvent`, `ExecutorCompletedEvent`, and `WorkflowOutputEvent` events emitted by the framework
+
+## Emitting Custom Events
+
+Executors can emit custom domain events during execution using the `IWorkflowContext` instance passed to `HandleAsync`. These events are streamed to callers in real-time via `WatchStreamAsync`.
+
+### Defining a custom event
+
+Create a class that inherits from `WorkflowEvent`. Pass any data payload to the base constructor:
+
+```csharp
+public class CancellationProgressEvent(int percentComplete, string status) : WorkflowEvent(status)
+{
+    public int PercentComplete { get; } = percentComplete;
+    public string Status { get; } = status;
+}
+```
+
+### Emitting the event from an executor
+
+Call `AddEventAsync` on the `IWorkflowContext` inside your executor's `HandleAsync` method:
+
+```csharp
+public override async ValueTask<Order> HandleAsync(
+    Order message,
+    IWorkflowContext context,
+    CancellationToken cancellationToken = default)
+{
+    await context.AddEventAsync(new CancellationProgressEvent(33, "Processing refund"), cancellationToken);
+    // ... rest of the executor logic
+}
+```
+
+### Observing events from the caller
+
+Use `StreamAsync` to start the workflow and `WatchStreamAsync` to observe events. Pattern match on your custom event types:
+
+```csharp
+IStreamingWorkflowRun run = await workflowClient.StreamAsync(workflow, input);
+
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    switch (evt)
+    {
+        case CancellationProgressEvent e:
+            Console.WriteLine($"{e.PercentComplete}% - {e.Status}");
+            break;
+    }
+}
+```
+
+## Workflow Structure
+
+```
+OrderLookup → OrderCancel → SendEmail
+```
+
+Each executor emits custom events during execution:
+- `OrderLookup` emits `OrderLookupStartedEvent` and `OrderFoundEvent`
+- `OrderCancel` emits `CancellationProgressEvent` (with percentage) and `OrderCancelledEvent`
+- `SendEmail` emits `EmailSentEvent`
+
+## Prerequisites
+
+- [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler) running locally or in Azure
+- Set the `DURABLE_TASK_SCHEDULER_CONNECTION_STRING` environment variable (defaults to local emulator)
+
+## 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.
+
+## Running the sample
+
+```bash
+dotnet run
+```
+
+Enter an order ID at the prompt to start a workflow and watch events stream in real-time:
+
+```text
+> order-42
+Started run: b6ba4d19...
+  New event received at 13:27:41.4956 (ExecutorInvokedEvent)
+  New event received at 13:27:41.5019 (OrderLookupStartedEvent)
+    [Lookup] Looking up order order-42
+  New event received at 13:27:41.5025 (OrderFoundEvent)
+    [Lookup] Found: Jerry
+  New event received at 13:27:41.5026 (ExecutorCompletedEvent)
+  New event received at 13:27:41.5026 (WorkflowOutputEvent)
+    [Output] OrderLookup
+  New event received at 13:27:43.0772 (ExecutorInvokedEvent)
+  New event received at 13:27:43.0773 (CancellationProgressEvent)
+    [Cancel] 0% - Starting cancellation
+  New event received at 13:27:43.0775 (CancellationProgressEvent)
+    [Cancel] 33% - Contacting payment provider
+  New event received at 13:27:43.0776 (CancellationProgressEvent)
+    [Cancel] 66% - Processing refund
+  New event received at 13:27:43.0777 (CancellationProgressEvent)
+    [Cancel] 100% - Complete
+  New event received at 13:27:43.0779 (OrderCancelledEvent)
+    [Cancel] Done
+  New event received at 13:27:43.0780 (ExecutorCompletedEvent)
+  New event received at 13:27:43.0780 (WorkflowOutputEvent)
+    [Output] OrderCancel
+  New event received at 13:27:43.6610 (ExecutorInvokedEvent)
+  New event received at 13:27:43.6611 (EmailSentEvent)
+    [Email] Sent to jerry@example.com
+  New event received at 13:27:43.6613 (ExecutorCompletedEvent)
+  New event received at 13:27:43.6613 (WorkflowOutputEvent)
+    [Output] SendEmail
+  New event received at 13:27:43.6619 (DurableWorkflowCompletedEvent)
+  Completed: Cancellation email sent for order order-42 to jerry@example.com.
+```
+
+### Viewing Workflows in the DTS Dashboard
+
+After running a workflow, you can navigate to the Durable Task Scheduler (DTS) dashboard to inspect the workflow execution and events.
+
+If you are using the DTS emulator, the dashboard is available at `http://localhost:8082`.
@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>WorkflowSharedState</AssemblyName>
+    <RootNamespace>WorkflowSharedState</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,182 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowSharedState;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Domain models
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// <summary>
+/// The primary order data passed through the pipeline via return values.
+/// </summary>
+internal sealed record OrderDetails(string OrderId, string CustomerName, decimal Amount, DateTime OrderDate);
+
+/// <summary>
+/// Cross-cutting audit trail accumulated in shared state across executors.
+/// Each executor appends its step name and timestamp. This data does not flow
+/// through return values — it lives only in shared state.
+/// </summary>
+internal sealed record AuditEntry(string Step, string Timestamp, string Detail);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Executors
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// <summary>
+/// Validates the order and writes the initial audit entry and tax rate to shared state.
+/// The order details are returned as the executor output (normal message flow),
+/// while the audit trail and tax rate are stored in shared state (side-channel).
+/// If the order ID starts with "INVALID", the executor halts the workflow early
+/// using <see cref="IWorkflowContext.RequestHaltAsync"/>.
+/// </summary>
+internal sealed class ValidateOrder() : Executor<string, OrderDetails>("ValidateOrder")
+{
+    public override async ValueTask<OrderDetails> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        await Task.Delay(TimeSpan.FromMilliseconds(200), cancellationToken);
+
+        // Halt the workflow early if the order ID is invalid.
+        // No downstream executors will run after this.
+        if (message.StartsWith("INVALID", StringComparison.OrdinalIgnoreCase))
+        {
+            await context.YieldOutputAsync($"Order '{message}' failed validation. Halting workflow.", cancellationToken);
+            await context.RequestHaltAsync();
+            return new OrderDetails(message, "Unknown", 0, DateTime.UtcNow);
+        }
+
+        OrderDetails details = new(message, "Jerry", 249.99m, DateTime.UtcNow);
+
+        // Store the tax rate in shared state — downstream ProcessPayment reads it
+        // without needing it in the message chain.
+        await context.QueueStateUpdateAsync("taxRate", 0.085m, cancellationToken: cancellationToken);
+        Console.WriteLine("    Wrote to shared state: taxRate = 8.5%");
+
+        // Start the audit trail in shared state
+        AuditEntry audit = new("ValidateOrder", DateTime.UtcNow.ToString("o"), $"Validated order {message}");
+        await context.QueueStateUpdateAsync("auditValidate", audit, cancellationToken: cancellationToken);
+        Console.WriteLine("    Wrote to shared state: auditValidate");
+
+        await context.YieldOutputAsync($"Order '{message}' validated. Customer: {details.CustomerName}, Amount: {details.Amount:C}", cancellationToken);
+
+        return details;
+    }
+}
+
+/// <summary>
+/// Enriches the order with shipping information.
+/// Reads the audit trail from shared state and appends its own entry.
+/// Uses ReadOrInitStateAsync to lazily initialize a shipping tier.
+/// Demonstrates custom scopes by writing shipping details under the "shipping" scope.
+/// </summary>
+internal sealed class EnrichOrder() : Executor<OrderDetails, OrderDetails>("EnrichOrder")
+{
+    public override async ValueTask<OrderDetails> HandleAsync(
+        OrderDetails message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        await Task.Delay(TimeSpan.FromMilliseconds(200), cancellationToken);
+
+        // Use ReadOrInitStateAsync — only initializes if no value exists yet
+        string shippingTier = await context.ReadOrInitStateAsync(
+            "shippingTier",
+            () => "Express",
+            cancellationToken: cancellationToken);
+        Console.WriteLine($"    Read from shared state: shippingTier = {shippingTier}");
+
+        // Write carrier under a custom "shipping" scope.
+        // This keeps the key separate from keys written without a scope,
+        // so "carrier" here won't collide with a "carrier" key written elsewhere.
+        await context.QueueStateUpdateAsync("carrier", "Contoso Express", scopeName: "shipping", cancellationToken: cancellationToken);
+        Console.WriteLine("    Wrote to shared state: carrier = Contoso Express (scope: shipping)");
+
+        // Verify we can read the audit entry from the previous step
+        AuditEntry? previousAudit = await context.ReadStateAsync<AuditEntry>("auditValidate", cancellationToken: cancellationToken);
+        string auditStatus = previousAudit is not null ? $"(previous step: {previousAudit.Step})" : "(no prior audit)";
+        Console.WriteLine($"    Read from shared state: auditValidate {auditStatus}");
+
+        // Append our own audit entry
+        AuditEntry audit = new("EnrichOrder", DateTime.UtcNow.ToString("o"), $"Enriched with {shippingTier} shipping {auditStatus}");
+        await context.QueueStateUpdateAsync("auditEnrich", audit, cancellationToken: cancellationToken);
+        Console.WriteLine("    Wrote to shared state: auditEnrich");
+
+        await context.YieldOutputAsync($"Order enriched. Shipping: {shippingTier} {auditStatus}", cancellationToken);
+
+        return message;
+    }
+}
+
+/// <summary>
+/// Processes payment using the tax rate from shared state (written by ValidateOrder).
+/// The tax rate is side-channel data — it doesn't flow through return values.
+/// </summary>
+internal sealed class ProcessPayment() : Executor<OrderDetails, string>("ProcessPayment")
+{
+    public override async ValueTask<string> HandleAsync(
+        OrderDetails message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        await Task.Delay(TimeSpan.FromMilliseconds(300), cancellationToken);
+
+        // Read tax rate written by ValidateOrder — not available in the message chain
+        decimal taxRate = await context.ReadOrInitStateAsync("taxRate", () => 0.0m, cancellationToken: cancellationToken);
+        Console.WriteLine($"    Read from shared state: taxRate = {taxRate:P1}");
+
+        decimal tax = message.Amount * taxRate;
+        decimal total = message.Amount + tax;
+        string paymentRef = $"PAY-{Guid.NewGuid():N}"[..16];
+
+        // Append audit entry
+        AuditEntry audit = new("ProcessPayment", DateTime.UtcNow.ToString("o"), $"Charged {total:C} (tax: {tax:C})");
+        await context.QueueStateUpdateAsync("auditPayment", audit, cancellationToken: cancellationToken);
+        Console.WriteLine("    Wrote to shared state: auditPayment");
+
+        await context.YieldOutputAsync($"Payment processed. Total: {total:C} (tax: {tax:C}). Ref: {paymentRef}", cancellationToken);
+
+        return paymentRef;
+    }
+}
+
+/// <summary>
+/// Generates the final invoice by reading the full audit trail from shared state.
+/// Demonstrates reading multiple state entries written by different executors
+/// and clearing a scope with <see cref="IWorkflowContext.QueueClearScopeAsync(string?, CancellationToken)"/>.
+/// </summary>
+internal sealed class GenerateInvoice() : Executor<string, string>("GenerateInvoice")
+{
+    public override async ValueTask<string> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        // Read the full audit trail from shared state — each step wrote its own entry
+        AuditEntry? validateAudit = await context.ReadStateAsync<AuditEntry>("auditValidate", cancellationToken: cancellationToken);
+        AuditEntry? enrichAudit = await context.ReadStateAsync<AuditEntry>("auditEnrich", cancellationToken: cancellationToken);
+        AuditEntry? paymentAudit = await context.ReadStateAsync<AuditEntry>("auditPayment", cancellationToken: cancellationToken);
+        int auditCount = new[] { validateAudit, enrichAudit, paymentAudit }.Count(a => a is not null);
+        Console.WriteLine($"    Read from shared state: {auditCount} audit entries");
+
+        // Read carrier from the "shipping" scope (written by EnrichOrder)
+        string? carrier = await context.ReadStateAsync<string>("carrier", scopeName: "shipping", cancellationToken: cancellationToken);
+        Console.WriteLine($"    Read from shared state: carrier = {carrier} (scope: shipping)");
+
+        // Clear the "shipping" scope — no longer needed after invoice generation.
+        await context.QueueClearScopeAsync("shipping", cancellationToken);
+        Console.WriteLine("    Cleared shared state scope: shipping");
+
+        string auditSummary = string.Join(" → ", new[]
+        {
+            validateAudit?.Step, enrichAudit?.Step, paymentAudit?.Step
+        }.Where(s => s is not null));
+
+        return $"Invoice complete. Payment: {message}. Audit trail: [{auditSummary}]";
+    }
+}
@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SAMPLE: Shared State During Workflow Execution
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// This sample demonstrates how executors in a durable workflow can share state
+// via IWorkflowContext. State is persisted across supersteps and survives
+// process restarts because the orchestration passes it to each activity.
+//
+// Key concepts:
+//   1. QueueStateUpdateAsync  - Write a value to shared state
+//   2. ReadStateAsync         - Read a value written by a previous executor
+//   3. ReadOrInitStateAsync   - Read or lazily initialize a state value
+//   4. QueueClearScopeAsync   - Clear all entries under a scope
+//   5. RequestHaltAsync       - Stop the workflow early (e.g., validation failure)
+//
+// Workflow: ValidateOrder -> EnrichOrder -> ProcessPayment -> GenerateInvoice
+//
+// Return values carry primary business data through the pipeline (OrderDetails,
+// payment ref). Shared state carries side-channel data that doesn't belong in
+// the message chain: a tax rate (set by ValidateOrder, read by ProcessPayment)
+// and an audit trail (each executor appends its own entry).
+// ═══════════════════════════════════════════════════════════════════════════════
+
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using WorkflowSharedState;
+
+// Get DTS connection string from environment variable
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+
+// Define executors
+ValidateOrder validateOrder = new();
+EnrichOrder enrichOrder = new();
+ProcessPayment processPayment = new();
+GenerateInvoice generateInvoice = new();
+
+// Build the workflow: ValidateOrder -> EnrichOrder -> ProcessPayment -> GenerateInvoice
+Workflow orderPipeline = new WorkflowBuilder(validateOrder)
+    .WithName("OrderPipeline")
+    .WithDescription("Order processing pipeline with shared state across executors")
+    .AddEdge(validateOrder, enrichOrder)
+    .AddEdge(enrichOrder, processPayment)
+    .AddEdge(processPayment, generateInvoice)
+    .Build();
+
+// Configure host with durable workflow support
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+    .ConfigureServices(services =>
+    {
+        services.ConfigureDurableWorkflows(
+            workflowOptions => workflowOptions.AddWorkflow(orderPipeline),
+            workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+            clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+    })
+    .Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Shared State Workflow Demo");
+Console.WriteLine("Workflow: ValidateOrder -> EnrichOrder -> ProcessPayment -> GenerateInvoice");
+Console.WriteLine();
+Console.WriteLine("Enter an order ID (or 'exit'):");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        // Start the workflow and stream events to see shared state in action
+        IStreamingWorkflowRun run = await workflowClient.StreamAsync(orderPipeline, input);
+        Console.WriteLine($"Started run: {run.RunId}");
+
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case WorkflowOutputEvent e:
+                    Console.WriteLine($"  [Output] {e.SourceId}: {e.Data}");
+                    break;
+
+                case DurableWorkflowCompletedEvent e:
+                    Console.WriteLine($"  Completed: {e.Result}");
+                    break;
+
+                case DurableWorkflowFailedEvent e:
+                    Console.WriteLine($"  Failed: {e.ErrorMessage}");
+                    break;
+            }
+        }
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
@@ -0,0 +1,71 @@
+# Shared State Workflow Sample
+
+This sample demonstrates how executors in a durable workflow can share state via `IWorkflowContext`. State written by one executor is accessible to all downstream executors, persisted across supersteps, and survives process restarts.
+
+## Key Concepts Demonstrated
+
+- Writing state with `QueueStateUpdateAsync` — executors store data for downstream executors
+- Reading state with `ReadStateAsync` — executors access data written by earlier executors
+- Lazy initialization with `ReadOrInitStateAsync` — initialize state only if not already present
+- Custom scopes with `scopeName` — partition state into isolated namespaces (e.g., `"shipping"`)
+- Clearing scopes with `QueueClearScopeAsync` — remove all entries under a scope when no longer needed
+- Early termination with `RequestHaltAsync` — halt the workflow when validation fails
+- State persistence across supersteps — the orchestration passes shared state to each executor
+- Event streaming with `IStreamingWorkflowRun` — observe executor progress in real time
+
+## Workflow
+
+**OrderPipeline**: `ValidateOrder` → `EnrichOrder` → `ProcessPayment` → `GenerateInvoice`
+
+Return values carry primary business data through the pipeline (`OrderDetails` → `OrderDetails` → payment ref → invoice string). Shared state carries side-channel data that doesn't belong in the message chain:
+
+| Executor | Returns (message flow) | Reads from State | Writes to State |
+|----------|----------------------|-----------------|-----------------|
+| **ValidateOrder** | `OrderDetails` | — | `taxRate`, `auditValidate` |
+| **EnrichOrder** | `OrderDetails` (pass-through) | `auditValidate` | `shippingTier`, `auditEnrich`, `carrier` (scope: shipping) |
+| **ProcessPayment** | payment ref string | `taxRate` | `auditPayment` |
+| **GenerateInvoice** | invoice string | `auditValidate`, `auditEnrich`, `auditPayment`, `carrier` (scope: shipping) | clears `shipping` scope |
+
+> [!NOTE]
+> `EnrichOrder` writes `carrier` under the `"shipping"` scope using `scopeName: "shipping"`. This keeps the key separate from keys written without a scope, so `"carrier"` in the `"shipping"` scope won't collide with a `"carrier"` key written elsewhere.
+
+## 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.
+
+## Running the Sample
+
+```bash
+dotnet run
+```
+
+Enter an order ID when prompted. The workflow will process the order through all four executors, streaming events as they occur:
+
+```text
+> ORD-001
+Started run: abc123
+    Wrote to shared state: taxRate = 8.5%
+    Wrote to shared state: auditValidate
+  [Output] ValidateOrder: Order 'ORD-001' validated. Customer: Jerry, Amount: $249.99
+    Read from shared state: shippingTier = Express
+    Wrote to shared state: carrier = Contoso Express (scope: shipping)
+    Read from shared state: auditValidate (previous step: ValidateOrder)
+    Wrote to shared state: auditEnrich
+  [Output] EnrichOrder: Order enriched. Shipping: Express (previous step: ValidateOrder)
+    Read from shared state: taxRate = 8.5%
+    Wrote to shared state: auditPayment
+  [Output] ProcessPayment: Payment processed. Total: $271.24 (tax: $21.25). Ref: PAY-abc123def456
+    Read from shared state: 3 audit entries
+    Read from shared state: carrier = Contoso Express (scope: shipping)
+    Cleared shared state scope: shipping
+  [Output] GenerateInvoice: Invoice complete. Payment: "PAY-abc123def456". Audit trail: [ValidateOrder → EnrichOrder → ProcessPayment]
+  Completed: Invoice complete. Payment: "PAY-abc123def456". Audit trail: [ValidateOrder → EnrichOrder → ProcessPayment]
+```
+
+### Viewing Workflows in the DTS Dashboard
+
+After running a workflow, you can navigate to the Durable Task Scheduler (DTS) dashboard to inspect the orchestration status, executor inputs/outputs, and events.
+
+If you are using the DTS emulator, the dashboard is available at `http://localhost:8082`.
+
+To inspect shared state in the dashboard, click on an executor to view its input and output. The input contains a snapshot of the shared state the executor ran with, and the output includes any state updates it made (as `stateUpdates` with scoped keys).
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>SubWorkflows</AssemblyName>
+    <RootNamespace>SubWorkflows</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,232 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace SubWorkflows;
+
+/// <summary>
+/// Event emitted when the fraud check risk score is calculated.
+/// </summary>
+internal sealed class FraudRiskAssessedEvent(int riskScore) : WorkflowEvent($"Risk score: {riskScore}/100")
+{
+    public int RiskScore => riskScore;
+}
+
+/// <summary>
+/// Represents an order being processed through the workflow.
+/// </summary>
+internal sealed class OrderInfo
+{
+    public required string OrderId { get; set; }
+
+    public decimal Amount { get; set; }
+
+    public string? PaymentTransactionId { get; set; }
+
+    public string? TrackingNumber { get; set; }
+
+    public string? Carrier { get; set; }
+}
+
+// Main workflow executors
+
+/// <summary>
+/// Entry point executor that receives the order ID and creates an OrderInfo object.
+/// </summary>
+internal sealed class OrderReceived() : Executor<string, OrderInfo>("OrderReceived")
+{
+    public override ValueTask<OrderInfo> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine($"[OrderReceived] Processing order '{message}'");
+        Console.ResetColor();
+
+        OrderInfo order = new()
+        {
+            OrderId = message,
+            Amount = 99.99m // Simulated order amount
+        };
+
+        return ValueTask.FromResult(order);
+    }
+}
+
+/// <summary>
+/// Final executor that outputs the completed order summary.
+/// </summary>
+internal sealed class OrderCompleted() : Executor<OrderInfo, string>("OrderCompleted")
+{
+    public override ValueTask<string> HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
+        Console.WriteLine($"│ [OrderCompleted] Order '{message.OrderId}' successfully processed!");
+        Console.WriteLine($"│   Payment: {message.PaymentTransactionId}");
+        Console.WriteLine($"│   Shipping: {message.Carrier} - {message.TrackingNumber}");
+        Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
+        Console.ResetColor();
+
+        return ValueTask.FromResult($"Order {message.OrderId} completed. Tracking: {message.TrackingNumber}");
+    }
+}
+
+// Payment sub-workflow executors
+
+/// <summary>
+/// Validates payment information for an order.
+/// </summary>
+internal sealed class ValidatePayment() : Executor<OrderInfo, OrderInfo>("ValidatePayment")
+{
+    public override async ValueTask<OrderInfo> HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"  [Payment/ValidatePayment] Validating payment for order '{message.OrderId}'...");
+        Console.ResetColor();
+
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"  [Payment/ValidatePayment] Payment validated for ${message.Amount}");
+        Console.ResetColor();
+
+        return message;
+    }
+}
+
+/// <summary>
+/// Charges the payment for an order.
+/// </summary>
+internal sealed class ChargePayment() : Executor<OrderInfo, OrderInfo>("ChargePayment")
+{
+    public override async ValueTask<OrderInfo> HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"  [Payment/ChargePayment] Charging ${message.Amount} for order '{message.OrderId}'...");
+        Console.ResetColor();
+
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        message.PaymentTransactionId = $"TXN-{Guid.NewGuid().ToString("N")[..8].ToUpperInvariant()}";
+
+        Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.WriteLine($"  [Payment/ChargePayment] ✓ Payment processed: {message.PaymentTransactionId}");
+        Console.ResetColor();
+
+        return message;
+    }
+}
+
+// FraudCheck sub-sub-workflow executors (nested inside Payment)
+
+/// <summary>
+/// Analyzes transaction patterns for potential fraud.
+/// </summary>
+internal sealed class AnalyzePatterns() : Executor<OrderInfo, OrderInfo>("AnalyzePatterns")
+{
+    public override async ValueTask<OrderInfo> HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.ForegroundColor = ConsoleColor.DarkYellow;
+        Console.WriteLine($"    [Payment/FraudCheck/AnalyzePatterns] Analyzing patterns for order '{message.OrderId}'...");
+        Console.ResetColor();
+
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        // Store analysis results in shared state for the next executor in this sub-workflow
+        int patternsFound = new Random().Next(0, 5);
+        await context.QueueStateUpdateAsync("patternsFound", patternsFound, cancellationToken: cancellationToken);
+
+        Console.ForegroundColor = ConsoleColor.DarkYellow;
+        Console.WriteLine($"    [Payment/FraudCheck/AnalyzePatterns] ✓ Pattern analysis complete ({patternsFound} suspicious patterns)");
+        Console.ResetColor();
+
+        return message;
+    }
+}
+
+/// <summary>
+/// Calculates a risk score for the transaction.
+/// </summary>
+internal sealed class CalculateRiskScore() : Executor<OrderInfo, OrderInfo>("CalculateRiskScore")
+{
+    public override async ValueTask<OrderInfo> HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.ForegroundColor = ConsoleColor.DarkYellow;
+        Console.WriteLine($"    [Payment/FraudCheck/CalculateRiskScore] Calculating risk score for order '{message.OrderId}'...");
+        Console.ResetColor();
+
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        // Read the pattern count from shared state (written by AnalyzePatterns)
+        int patternsFound = await context.ReadStateAsync<int>("patternsFound", cancellationToken: cancellationToken);
+        int riskScore = Math.Min(patternsFound * 20 + new Random().Next(1, 20), 100);
+
+        // Emit a workflow event from within a nested sub-workflow
+        await context.AddEventAsync(new FraudRiskAssessedEvent(riskScore), cancellationToken);
+
+        Console.ForegroundColor = ConsoleColor.DarkYellow;
+        Console.WriteLine($"    [Payment/FraudCheck/CalculateRiskScore] ✓ Risk score: {riskScore}/100 (based on {patternsFound} patterns)");
+        Console.ResetColor();
+
+        return message;
+    }
+}
+
+// Shipping sub-workflow executors
+
+/// <summary>
+/// Selects a shipping carrier for an order.
+/// </summary>
+/// <remarks>
+/// This executor uses <see cref="Executor{TInput}"/> (void return) combined with
+/// <see cref="IWorkflowContext.SendMessageAsync"/> to forward the order to the next
+/// connected executor (CreateShipment). This demonstrates explicit typed message passing
+/// as an alternative to returning a value from the handler.
+/// </remarks>
+internal sealed class SelectCarrier() : Executor<OrderInfo>("SelectCarrier")
+{
+    public override async ValueTask HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.Blue;
+        Console.WriteLine($"  [Shipping/SelectCarrier] Selecting carrier for order '{message.OrderId}'...");
+        Console.ResetColor();
+
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        message.Carrier = message.Amount > 50 ? "Express" : "Standard";
+
+        Console.ForegroundColor = ConsoleColor.Blue;
+        Console.WriteLine($"  [Shipping/SelectCarrier] ✓ Selected carrier: {message.Carrier}");
+        Console.ResetColor();
+
+        // Use SendMessageAsync to forward the updated order to connected executors.
+        // With a void-return executor, this is the mechanism for passing data downstream.
+        await context.SendMessageAsync(message, cancellationToken: cancellationToken);
+    }
+}
+
+/// <summary>
+/// Creates shipment and generates tracking number.
+/// </summary>
+internal sealed class CreateShipment() : Executor<OrderInfo, OrderInfo>("CreateShipment")
+{
+    public override async ValueTask<OrderInfo> HandleAsync(OrderInfo message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.ForegroundColor = ConsoleColor.Blue;
+        Console.WriteLine($"  [Shipping/CreateShipment] Creating shipment for order '{message.OrderId}'...");
+        Console.ResetColor();
+
+        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
+
+        message.TrackingNumber = $"TRACK-{Guid.NewGuid().ToString("N")[..10].ToUpperInvariant()}";
+
+        Console.ForegroundColor = ConsoleColor.Blue;
+        Console.WriteLine($"  [Shipping/CreateShipment] ✓ Shipment created: {message.TrackingNumber}");
+        Console.ResetColor();
+
+        return message;
+    }
+}
@@ -0,0 +1,146 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates nested sub-workflows. A sub-workflow can act as an executor
+// within another workflow, including multi-level nesting (sub-workflow within sub-workflow).
+
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using SubWorkflows;
+
+// Get DTS connection string from environment variable
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+
+// Build the FraudCheck sub-workflow (this will be nested inside the Payment sub-workflow)
+AnalyzePatterns analyzePatterns = new();
+CalculateRiskScore calculateRiskScore = new();
+
+Workflow fraudCheckWorkflow = new WorkflowBuilder(analyzePatterns)
+    .WithName("SubFraudCheck")
+    .WithDescription("Analyzes transaction patterns and calculates risk score")
+    .AddEdge(analyzePatterns, calculateRiskScore)
+    .Build();
+
+// Build the Payment sub-workflow: ValidatePayment -> FraudCheck (sub-workflow) -> ChargePayment
+ValidatePayment validatePayment = new();
+ExecutorBinding fraudCheckExecutor = fraudCheckWorkflow.BindAsExecutor("FraudCheck");
+ChargePayment chargePayment = new();
+
+Workflow paymentWorkflow = new WorkflowBuilder(validatePayment)
+    .WithName("SubPaymentProcessing")
+    .WithDescription("Validates and processes payment for an order")
+    .AddEdge(validatePayment, fraudCheckExecutor)
+    .AddEdge(fraudCheckExecutor, chargePayment)
+    .Build();
+
+// Build the Shipping sub-workflow: SelectCarrier -> CreateShipment
+SelectCarrier selectCarrier = new();
+CreateShipment createShipment = new();
+
+Workflow shippingWorkflow = new WorkflowBuilder(selectCarrier)
+    .WithName("SubShippingArrangement")
+    .WithDescription("Selects carrier and creates shipment")
+    .AddEdge(selectCarrier, createShipment)
+    .Build();
+
+// Build the main workflow using sub-workflows as executors
+// OrderReceived -> Payment (sub-workflow) -> Shipping (sub-workflow) -> OrderCompleted
+OrderReceived orderReceived = new();
+OrderCompleted orderCompleted = new();
+ExecutorBinding paymentExecutor = paymentWorkflow.BindAsExecutor("Payment");
+ExecutorBinding shippingExecutor = shippingWorkflow.BindAsExecutor("Shipping");
+
+Workflow orderProcessingWorkflow = new WorkflowBuilder(orderReceived)
+    .WithName("OrderProcessing")
+    .WithDescription("Processes an order through payment and shipping")
+    .AddEdge(orderReceived, paymentExecutor)
+    .AddEdge(paymentExecutor, shippingExecutor)
+    .AddEdge(shippingExecutor, orderCompleted)
+    .Build();
+
+// Configure and start the host
+// Register only the main workflow - sub-workflows are discovered automatically!
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+    .ConfigureServices(services =>
+    {
+        services.ConfigureDurableWorkflows(
+            workflowOptions => workflowOptions.AddWorkflow(orderProcessingWorkflow),
+            workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+            clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+    })
+    .Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Durable Sub-Workflows Sample");
+Console.WriteLine("Workflow: OrderReceived -> Payment(sub) -> Shipping(sub) -> OrderCompleted");
+Console.WriteLine("  Payment contains nested FraudCheck sub-workflow (Level 2 nesting)");
+Console.WriteLine();
+Console.WriteLine("Enter an order ID (or 'exit'):");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        await StartNewWorkflowAsync(input, orderProcessingWorkflow, workflowClient);
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
+
+// Start a new workflow using streaming to observe events (including from sub-workflows)
+static async Task StartNewWorkflowAsync(string orderId, Workflow workflow, IWorkflowClient client)
+{
+    Console.WriteLine($"\nStarting order processing for '{orderId}'...");
+
+    IStreamingWorkflowRun run = await client.StreamAsync(workflow, orderId);
+    Console.WriteLine($"Run ID: {run.RunId}");
+    Console.WriteLine();
+
+    await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+    {
+        switch (evt)
+        {
+            // Custom event emitted from the FraudCheck sub-sub-workflow
+            case FraudRiskAssessedEvent e:
+                Console.ForegroundColor = ConsoleColor.DarkYellow;
+                Console.WriteLine($"  [Event from sub-workflow] {e.GetType().Name}: Risk score {e.RiskScore}/100");
+                Console.ResetColor();
+                break;
+
+            case DurableWorkflowCompletedEvent e:
+                Console.ForegroundColor = ConsoleColor.Green;
+                Console.WriteLine($"✓ Order completed: {e.Result}");
+                Console.ResetColor();
+                break;
+
+            case DurableWorkflowFailedEvent e:
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.WriteLine($"✗ Failed: {e.ErrorMessage}");
+                Console.ResetColor();
+                break;
+        }
+    }
+}
@@ -0,0 +1,123 @@
+# Sub-Workflows Sample (Nested Workflows)
+
+This sample demonstrates how to compose complex workflows from simpler, reusable sub-workflows. Sub-workflows are built using `WorkflowBuilder` and embedded as executors via `BindAsExecutor()`. Unlike the in-process workflow runner, the durable workflow backend persists execution state across process restarts — each sub-workflow runs as a separate orchestration instance on the Durable Task Scheduler, providing independent checkpointing, fault tolerance, and hierarchical visualization in the DTS dashboard.
+
+## Key Concepts Demonstrated
+
+- **Sub-workflows**: Using `Workflow.BindAsExecutor()` to embed a workflow as an executor in another workflow
+- **Multi-level nesting**: Sub-workflows within sub-workflows (Level 2 nesting)
+- **Automatic discovery**: Registering only the main workflow; sub-workflows are discovered automatically
+- **Failure isolation**: Each sub-workflow runs as a separate orchestration instance on the DTS backend
+- **Hierarchical visualization**: Parent-child orchestration hierarchy visible in the DTS dashboard
+- **Event propagation**: Custom workflow events (`FraudRiskAssessedEvent`) bubble up from nested sub-workflows to the streaming client
+- **Message passing**: Using `Executor<TInput>` (void return) with `SendMessageAsync` to forward typed messages to connected executors (`SelectCarrier`)
+- **Shared state within sub-workflows**: Using `QueueStateUpdateAsync`/`ReadStateAsync` to share data between executors within a sub-workflow (`AnalyzePatterns` → `CalculateRiskScore`)
+
+## Overview
+
+The sample implements an order processing workflow composed of two sub-workflows, one of which contains its own nested sub-workflow:
+
+```
+OrderProcessing (main workflow)
+├── OrderReceived
+├── Payment (sub-workflow)
+│   ├── ValidatePayment
+│   ├── FraudCheck (sub-sub-workflow) ← Level 2 nesting!
+│   │   ├── AnalyzePatterns
+│   │   └── CalculateRiskScore
+│   └── ChargePayment
+├── Shipping (sub-workflow)
+│   ├── SelectCarrier ← Uses SendMessageAsync (void-return executor)
+│   └── CreateShipment
+└── OrderCompleted
+```
+
+| Executor | Sub-Workflow | Description |
+|----------|-------------|-------------|
+| OrderReceived | Main | Receives order ID and creates order info |
+| ValidatePayment | Payment | Validates payment information |
+| AnalyzePatterns | FraudCheck (nested in Payment) | Analyzes transaction patterns, stores results in shared state |
+| CalculateRiskScore | FraudCheck (nested in Payment) | Reads shared state, calculates risk score, emits `FraudRiskAssessedEvent` |
+| ChargePayment | Payment | Charges payment amount |
+| SelectCarrier | Shipping | Selects carrier using `SendMessageAsync` (void-return executor) |
+| CreateShipment | Shipping | Creates shipment with tracking |
+| OrderCompleted | Main | Outputs completed order summary |
+
+## How Sub-Workflows Work
+
+1. **Build** each sub-workflow as a standalone `Workflow` using `WorkflowBuilder`
+2. **Bind** a workflow as an executor using `workflow.BindAsExecutor("name")`
+3. **Add** the bound executor as a node in the parent workflow's graph
+4. **Register** only the top-level workflow — sub-workflows are discovered and registered automatically
+
+```csharp
+// Build a sub-workflow
+Workflow fraudCheckWorkflow = new WorkflowBuilder(analyzePatterns)
+    .WithName("SubFraudCheck")
+    .AddEdge(analyzePatterns, calculateRiskScore)
+    .Build();
+
+// Nest it inside another sub-workflow using BindAsExecutor
+ExecutorBinding fraudCheckExecutor = fraudCheckWorkflow.BindAsExecutor("FraudCheck");
+
+Workflow paymentWorkflow = new WorkflowBuilder(validatePayment)
+    .WithName("SubPaymentProcessing")
+    .AddEdge(validatePayment, fraudCheckExecutor)
+    .AddEdge(fraudCheckExecutor, chargePayment)
+    .Build();
+
+// Use the Payment sub-workflow in the main workflow
+ExecutorBinding paymentExecutor = paymentWorkflow.BindAsExecutor("Payment");
+
+Workflow mainWorkflow = new WorkflowBuilder(orderReceived)
+    .AddEdge(orderReceived, paymentExecutor)
+    .AddEdge(paymentExecutor, orderCompleted)
+    .Build();
+```
+
+## Environment Setup
+
+See the [README.md](../README.md) file in the parent directory for information on configuring the environment, including how to install and run the Durable Task Scheduler.
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/Durable/Workflow/ConsoleApps/07_SubWorkflows
+dotnet run --framework net10.0
+```
+
+### Sample Output
+
+```text
+Durable Sub-Workflows Sample
+Workflow: OrderReceived -> Payment(sub) -> Shipping(sub) -> OrderCompleted
+  Payment contains nested FraudCheck sub-workflow (Level 2 nesting)
+
+Enter an order ID (or 'exit'):
+> ORD-001
+Starting order processing for 'ORD-001'...
+Run ID: abc123...
+
+[OrderReceived] Processing order 'ORD-001'
+  [Payment/ValidatePayment] Validating payment for order 'ORD-001'...
+  [Payment/ValidatePayment] Payment validated for $99.99
+    [Payment/FraudCheck/AnalyzePatterns] Analyzing patterns for order 'ORD-001'...
+    [Payment/FraudCheck/AnalyzePatterns] ✓ Pattern analysis complete (2 suspicious patterns)
+    [Payment/FraudCheck/CalculateRiskScore] Calculating risk score for order 'ORD-001'...
+    [Payment/FraudCheck/CalculateRiskScore] ✓ Risk score: 53/100 (based on 2 patterns)
+  [Event from sub-workflow] FraudRiskAssessedEvent: Risk score 53/100
+  [Payment/ChargePayment] Charging $99.99 for order 'ORD-001'...
+  [Payment/ChargePayment] ✓ Payment processed: TXN-A1B2C3D4
+  [Shipping/SelectCarrier] Selecting carrier for order 'ORD-001'...
+  [Shipping/SelectCarrier] ✓ Selected carrier: Express
+  [Shipping/CreateShipment] Creating shipment for order 'ORD-001'...
+  [Shipping/CreateShipment] ✓ Shipment created: TRACK-I9J0K1L2M3
+┌─────────────────────────────────────────────────────────────────┐
+│ [OrderCompleted] Order 'ORD-001' successfully processed!
+│   Payment: TXN-A1B2C3D4
+│   Shipping: Express - TRACK-I9J0K1L2M3
+└─────────────────────────────────────────────────────────────────┘
+✓ Order completed: Order ORD-001 completed. Tracking: TRACK-I9J0K1L2M3
+
+> exit
+```
@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>WorkflowLoop</AssemblyName>
+    <RootNamespace>WorkflowLoop</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
+    <PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.DurableTask" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowLoop;
+
+/// <summary>
+/// Evaluates slogans and either accepts them or sends feedback back for refinement.
+/// Uses SendMessageAsync to loop back to SloganWriter and YieldOutputAsync to end the workflow.
+/// </summary>
+internal sealed class FeedbackExecutor : Executor<SloganResult>
+{
+    private readonly AIAgent _agent;
+    private AgentSession? _session;
+
+    /// <summary>
+    /// Gets or sets the minimum rating required to accept a slogan.
+    /// </summary>
+    public int MinimumRating { get; init; } = 9;
+
+    /// <summary>
+    /// Gets or sets the maximum number of refinement attempts before accepting the slogan.
+    /// </summary>
+    public int MaxAttempts { get; init; } = 3;
+
+    private int _attempts;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FeedbackExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="chatClient">The chat client to use for the AI agent.</param>
+    public FeedbackExecutor(string id, IChatClient chatClient) : base(id)
+    {
+        ChatClientAgentOptions agentOptions = new()
+        {
+            ChatOptions = new()
+            {
+                Instructions = "You are a professional editor. You will be given a slogan and the task it is meant to accomplish.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<FeedbackResult>()
+            }
+        };
+
+        this._agent = new ChatClientAgent(chatClient, agentOptions);
+    }
+
+    /// <inheritdoc/>
+    public override async ValueTask HandleAsync(SloganResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"  [FeedbackProvider] Evaluating slogan: \"{message.Slogan}\"");
+        this._session ??= await this._agent.GetNewSessionAsync(cancellationToken);
+
+        string sloganMessage = $"""
+            Here is a slogan for the task '{message.Task}':
+            Slogan: {message.Slogan}
+            Please provide feedback on this slogan, including comments, a rating from 1 to 10, and suggested actions for improvement.
+            """;
+
+        AgentResponse response = await this._agent.RunAsync(sloganMessage, this._session, cancellationToken: cancellationToken);
+        FeedbackResult feedback = JsonSerializer.Deserialize<FeedbackResult>(response.Text) ?? throw new InvalidOperationException("Failed to deserialize feedback.");
+
+        Console.WriteLine($"  [FeedbackProvider] Rating: {feedback.Rating}/{this.MinimumRating} - {feedback.Comments}");
+
+        // If the rating meets the threshold, accept the slogan and end the workflow
+        if (feedback.Rating >= this.MinimumRating)
+        {
+            Console.WriteLine("  [FeedbackProvider] Accepted!");
+            await context.YieldOutputAsync($"The following slogan was accepted:\n\n{message.Slogan}", cancellationToken);
+            return;
+        }
+
+        // If we've exceeded max attempts, accept the slogan anyway
+        if (this._attempts >= this.MaxAttempts)
+        {
+            Console.WriteLine("  [FeedbackProvider] Max attempts reached, accepting final slogan.");
+            await context.YieldOutputAsync($"The slogan was accepted after {this.MaxAttempts} attempts. Final slogan:\n\n{message.Slogan}", cancellationToken);
+            return;
+        }
+
+        // Otherwise, send feedback back to the slogan writer for refinement (circular edge)
+        Console.WriteLine($"  [FeedbackProvider] Sending back for refinement (attempt {this._attempts + 1}/{this.MaxAttempts})...");
+        await context.SendMessageAsync(feedback, cancellationToken: cancellationToken);
+        this._attempts++;
+    }
+}
@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates a CYCLIC WORKFLOW (back-edges in the graph).
+// SloganWriter and FeedbackProvider loop until the slogan meets quality criteria.
+
+using Azure;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask.Client.AzureManaged;
+using Microsoft.DurableTask.Worker.AzureManaged;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using WorkflowLoop;
+
+// Get DTS connection string from environment variable
+string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
+    ?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT is not set.");
+string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+
+// Create the chat client using key-based or Azure CLI credential authentication
+AzureOpenAIClient openAiClient = !string.IsNullOrEmpty(azureOpenAiKey)
+    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
+    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+IChatClient chatClient = openAiClient.GetChatClient(deploymentName).AsIChatClient();
+
+// Define executors for the workflow
+SloganWriterExecutor sloganWriter = new("SloganWriter", chatClient);
+FeedbackExecutor feedbackProvider = new("FeedbackProvider", chatClient);
+
+// Build the workflow with a circular edge: SloganWriter → FeedbackProvider → SloganWriter
+Workflow workflow = new WorkflowBuilder(sloganWriter)
+    .WithName("SloganCreationWorkflow")
+    .AddEdge(sloganWriter, feedbackProvider)
+    .AddEdge(feedbackProvider, sloganWriter)
+    .WithOutputFrom(feedbackProvider)
+    .Build();
+
+IHost host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
+    .ConfigureServices(services =>
+    {
+        services.ConfigureDurableWorkflows(
+            workflowOptions => workflowOptions.AddWorkflow(workflow),
+            workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
+            clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
+    })
+    .Build();
+
+await host.StartAsync();
+
+IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
+
+Console.WriteLine("Workflow Loop Demo - Enter a topic for slogan generation (or 'exit'):");
+
+while (true)
+{
+    Console.Write("> ");
+    string? input = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+    {
+        break;
+    }
+
+    try
+    {
+        // RunAsync starts the workflow; cast to IAwaitableWorkflowRun to wait for the result
+        IAwaitableWorkflowRun run = (IAwaitableWorkflowRun)await workflowClient.RunAsync(workflow, input);
+        Console.WriteLine($"Started run: {run.RunId}");
+
+        string? result = await run.WaitForCompletionAsync<string>();
+        Console.WriteLine($"Result: {result}");
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error: {ex.Message}");
+    }
+
+    Console.WriteLine();
+}
+
+await host.StopAsync();
@@ -0,0 +1,69 @@
+# Workflow Loop Sample
+
+This sample demonstrates how to run a **cyclic workflow** (containing loops / back-edges) as a durable orchestration. The workflow iteratively improves a slogan based on AI feedback until it meets quality criteria.
+
+## Key Concepts Demonstrated
+
+- **Cyclic workflow support** — back-edges in the graph (A → B → A)
+- **Multi-type executor handlers** — SloganWriter handles both `string` and `FeedbackResult` inputs
+- **Message routing via `SendMessageAsync`** — FeedbackProvider sends messages back to SloganWriter
+- **Workflow termination via `YieldOutputAsync`** — FeedbackProvider yields output when the slogan is accepted
+
+## Overview
+
+```
+                  ┌──────────────────────┐
+                  │                      │
+     input ──→ SloganWriter ──→ FeedbackProvider
+                  ▲                      │
+                  │    (FeedbackResult)   │
+                  └──────────────────────┘
+                       back-edge
+```
+
+| Executor | Description |
+|----------|-------------|
+| SloganWriter | Generates slogans from user input; refines them based on feedback |
+| FeedbackProvider | Evaluates slogans — accepts (YieldOutput) or loops (SendMessage) |
+
+### Loop Behavior
+
+1. **SloganWriter** generates a slogan based on user input
+2. **FeedbackProvider** evaluates the slogan and provides a rating
+3. If the rating is below the threshold (default: 9), feedback is sent back to SloganWriter
+4. SloganWriter improves the slogan based on feedback
+5. The loop continues until the slogan is accepted or max attempts (default: 3) are reached
+
+## Environment Setup
+
+See the [README.md](../README.md) file in the parent directory for information on configuring the environment, including how to install and run the Durable Task Scheduler.
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure OpenAI deployment name |
+| `AZURE_OPENAI_KEY` | (Optional) Azure OpenAI API key. If not set, uses Azure CLI credential |
+| `DURABLE_TASK_SCHEDULER_CONNECTION_STRING` | (Optional) DTS connection string. Defaults to local emulator |
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/Durable/Workflow/ConsoleApps/08_WorkflowLoop
+dotnet run --framework net10.0
+```
+
+### Sample Output
+
+```text
+Workflow Loop Demo - Enter a topic for slogan generation (or 'exit'):
+> sustainable energy
+Started run: abc123...
+  [FeedbackProvider] Rating 6/9 - sending back for refinement (attempt 1/3)
+  [FeedbackProvider] Rating 8/9 - sending back for refinement (attempt 2/3)
+  Event: WorkflowOutputEvent
+  Completed: The following slogan was accepted:
+
+Power the future, preserve the planet.
+```
@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace WorkflowLoop;
+
+/// <summary>
+/// Represents the result produced by the slogan writer executor.
+/// </summary>
+public sealed class SloganResult
+{
+    [JsonPropertyName("task")]
+    public required string Task { get; set; }
+
+    [JsonPropertyName("slogan")]
+    public required string Slogan { get; set; }
+}
+
+/// <summary>
+/// Represents feedback from the feedback executor, including comments, rating, and improvement actions.
+/// </summary>
+public sealed class FeedbackResult
+{
+    [JsonPropertyName("comments")]
+    public string Comments { get; set; } = string.Empty;
+
+    [JsonPropertyName("rating")]
+    public int Rating { get; set; }
+
+    [JsonPropertyName("actions")]
+    public string Actions { get; set; } = string.Empty;
+}
@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowLoop;
+
+/// <summary>
+/// Generates slogans based on user input or refines them based on feedback.
+/// This executor handles two input types: string (initial request) and FeedbackResult (refinement loop).
+/// </summary>
+internal sealed class SloganWriterExecutor : Executor
+{
+    private readonly AIAgent _agent;
+    private AgentSession? _session;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SloganWriterExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="chatClient">The chat client to use for the AI agent.</param>
+    public SloganWriterExecutor(string id, IChatClient chatClient) : base(id)
+    {
+        ChatClientAgentOptions agentOptions = new()
+        {
+            ChatOptions = new()
+            {
+                Instructions = "You are a professional slogan writer. You will be given a task to create a slogan.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<SloganResult>()
+            }
+        };
+
+        this._agent = new ChatClientAgent(chatClient, agentOptions);
+    }
+
+    /// <summary>
+    /// Configures two routes: one for initial string input and one for feedback-based refinement.
+    /// </summary>
+    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
+        routeBuilder.AddHandler<string, SloganResult>(this.HandleAsync)
+                    .AddHandler<FeedbackResult, SloganResult>(this.HandleFeedbackAsync);
+
+    /// <summary>
+    /// Handles the initial slogan generation request.
+    /// </summary>
+    public async ValueTask<SloganResult> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"  [SloganWriter] Generating slogan for: {message}");
+        this._session ??= await this._agent.GetNewSessionAsync(cancellationToken);
+
+        AgentResponse result = await this._agent.RunAsync(message, this._session, cancellationToken: cancellationToken);
+        SloganResult slogan = JsonSerializer.Deserialize<SloganResult>(result.Text) ?? throw new InvalidOperationException("Failed to deserialize slogan result.");
+        Console.WriteLine($"  [SloganWriter] Generated: \"{slogan.Slogan}\"");
+        return slogan;
+    }
+
+    /// <summary>
+    /// Handles feedback from the feedback executor to refine the slogan.
+    /// </summary>
+    public async ValueTask<SloganResult> HandleFeedbackAsync(FeedbackResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine($"  [SloganWriter] Refining slogan based on feedback (rating was {message.Rating})...");
+
+        string feedbackMessage = $"""
+            Here is the feedback on your previous slogan:
+            Comments: {message.Comments}
+            Rating: {message.Rating}
+            Suggested Actions: {message.Actions}
+
+            Please use this feedback to improve your slogan.
+            """;
+
+        AgentResponse result = await this._agent.RunAsync(feedbackMessage, this._session, cancellationToken: cancellationToken);
+        SloganResult slogan = JsonSerializer.Deserialize<SloganResult>(result.Text) ?? throw new InvalidOperationException("Failed to deserialize slogan result.");
+        Console.WriteLine($"  [SloganWriter] Refined: \"{slogan.Slogan}\"");
+        return slogan;
+    }
+}
@@ -26,12 +26,9 @@ AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
 AIAgent a2aAgent = agentCard.AsAIAgent();

 // Create the main agent, and provide the a2a agent skills as a function tools.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
-    new DefaultAzureCredential())
+    new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful assistant that helps people with travel planning.",
@@ -16,7 +16,7 @@ AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
 // Create an instance of the AIAgent for an existing A2A agent specified by the agent card.
 AIAgent agent = agentCard.AsAIAgent();

-AgentSession session = await agent.CreateSessionAsync();
+AgentSession session = await agent.GetNewSessionAsync();

 // Start the initial run with a long-running task.
 AgentResponse response = await agent.RunAsync("Conduct a comprehensive analysis of quantum computing applications in cryptography, including recent breakthroughs, implementation challenges, and future roadmap. Please include diagrams and visual representations to illustrate complex concepts.", session);
@@ -20,7 +20,7 @@ AIAgent agent = chatClient.AsAIAgent(
    name: "agui-client",
    description: "AG-UI Client Agent");

-AgentSession session = await agent.CreateSessionAsync();
+AgentSession session = await agent.GetNewSessionAsync();
 List<ChatMessage> messages =
 [
    new(ChatRole.System, "You are a helpful assistant.")
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Shyju Krishnankutty	70b44d9aa5	Add circular edges sample.	2026-02-23 14:13:30 -08:00
Shyju Krishnankutty	3d7409f2c9	Removed unused using statement.	2026-02-23 13:04:24 -08:00
Shyju Krishnankutty	1a396883ca	Removed unused reference.	2026-02-23 12:02:37 -08:00
Shyju Krishnankutty	16343368f6	README cleanup	2026-02-23 11:49:29 -08:00
Shyju Krishnankutty	adb566161f	Nested workflow support.	2026-02-23 11:19:28 -08:00
Shyju Krishnankutty GitHub Copilot	3256baa8b6	.NET: [Feature Branch] Adding support for events & shared state in durable workflows (#4020 ) * Adding support for events & shared state in durable workflows. * PR feedback fixes * PR feedback fixes. * Add YieldOutputAsync calls to 05_WorkflowEvents sample executors The integration test asserts that WorkflowOutputEvent is found in the stream, but the sample executors only used AddEventAsync for custom events and never called YieldOutputAsync. Since WorkflowOutputEvent is only emitted via explicit YieldOutputAsync calls, the assertion would fail. Added YieldOutputAsync to each executor to match the test expectation and demonstrate the API in the sample. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix deserialization to use shared serializer options. * PR feedback updates. * Sample cleanup * PR feedback fixes * Addressing PR review feedback for DurableStreamingWorkflowRun - Use -1 instead of 0 for taskId in TaskFailedException when task ID is not relevant. - Add [NotNullWhen(true)] to TryParseWorkflowResult out parameter following .NET TryXXX conventions. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>	2026-02-20 16:49:47 -08:00
Shyju KrishnankuttyandGitHub	b62b1f2191	.NET: [Feature Branch] Add Azure Functions hosting support for durable workflows (#3935 ) * Adding azure functions workflow support. * - PR feedback fixes. - Add example to demonstrate complex Object as payload. * rename instanceId to runId. * Use custom ITaskOrchestrator to run orchestrator function.	2026-02-14 16:19:28 -08:00
Shyju KrishnankuttyandGitHub	e8d0bd9051	.NET: [Feature Branch] Add basic durable workflow support (#3648 ) * Add basic durable workflow support. * PR feedback fixes * Add conditional edge sample. * PR feedback fixes. * Minor cleanup. * Minor cleanup * Minor formatting improvements. * Improve comments/documentation on the execution flow.	2026-02-06 16:02:42 -08:00