Merge branch 'main' into dev/dotnet_workflow/remove_timeout

Python: [BREAKING] update context provider APIs, middleware, and per-service-call history persistence (#4992 )
* Rename provider base APIs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Allow provider-added chat and function middleware Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Simulate service-stored history per model call Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix typing regressions in CI Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix response ID suppression review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Rename per-service-call history persistence APIs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address context persistence review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Stabilize markdown sample docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Persist service continuation state per call Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-04-01 13:33:48 -04:00 · 2026-04-01 16:13:11 +00:00 · 2026-04-01 15:38:48 +00:00 · 2026-04-01 15:18:33 +00:00 · 2026-04-01 13:47:20 +00:00
434 changed files with 18165 additions and 21509 deletions
@@ -34,7 +34,7 @@ runs:

    - name: Test Copilot CLI
      shell: bash
-      run: copilot -p "What can you do in one sentence?"
+      run: copilot --version && copilot -p "What can you do in one sentence?"

    - name: Azure CLI Login
      uses: azure/login@v2
@@ -126,8 +126,6 @@ jobs:
          packages/openai/tests/openai/test_openai_chat_completion_client_azure.py
          packages/openai/tests/openai/test_openai_chat_client_azure.py
          packages/openai/tests/openai/test_openai_embedding_client_azure.py
-          packages/azure-ai/tests/azure_openai
-          --ignore=packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
@@ -288,7 +286,6 @@ jobs:
        timeout-minutes: 15
        run: >
          uv run pytest --import-mode=importlib
-          packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          packages/foundry/tests
          -m integration
          -n logical --dist worksteal
@@ -62,9 +62,7 @@ jobs:
            azure:
              - 'python/packages/openai/**'
              - 'python/packages/core/agent_framework/azure/**'
-              - 'python/packages/azure-ai/agent_framework_azure_ai/_deprecated_azure_openai.py'
-              - 'python/packages/azure-ai/tests/azure_openai/**'
-              - 'python/samples/**/providers/azure/openai_chat_completion_client_azure*.py'
+              - 'python/samples/**/providers/azure/**'
            misc:
              - 'python/packages/anthropic/**'
              - 'python/packages/ollama/**'
@@ -223,8 +221,6 @@ jobs:
          packages/openai/tests/openai/test_openai_chat_completion_client_azure.py
          packages/openai/tests/openai/test_openai_chat_client_azure.py
          packages/openai/tests/openai/test_openai_embedding_client_azure.py
-          packages/azure-ai/tests/azure_openai
-          --ignore=packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
@@ -430,7 +426,6 @@ jobs:
        timeout-minutes: 15
        run: >
          uv run pytest --import-mode=importlib
-          packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          packages/foundry/tests
          -m integration
          -n logical --dist worksteal
@@ -23,10 +23,8 @@ jobs:
    environment: integration
    env:
      # Required configuration for get-started samples
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
    defaults:
      run:
        working-directory: python
@@ -43,10 +41,8 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env

      - name: Run sample validation
        run: |
@@ -64,14 +60,13 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Foundry configuration
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # Azure OpenAI configuration
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
+      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME || vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
      # OpenAI configuration
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
@@ -97,11 +92,10 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_DEPLOYMENT_NAME=$AZURE_OPENAI_DEPLOYMENT_NAME" >> .env
          echo "AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=$AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME" >> .env
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
@@ -125,6 +119,7 @@ jobs:
    environment: integration
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_MODEL: ${{ vars.OPENAI__CHATMODELID }}
      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
    defaults:
@@ -144,6 +139,7 @@ jobs:
      - name: Create .env for samples
        run: |
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
+          echo "OPENAI_MODEL=$OPENAI_MODEL" >> .env
          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env

@@ -158,15 +154,14 @@ jobs:
          name: validation-report-02-agents-openai
          path: python/samples/sample_validation/reports/

-  validate-02-agents-azure-openai:
-    name: Validate 02-agents/providers/azure_openai
+  validate-02-agents-azure:
+    name: Validate 02-agents/providers/azure
    runs-on: ubuntu-latest
    environment: integration
    env:
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_API_VERSION: ${{ vars.AZURE_OPENAI_API_VERSION || '' }}
    defaults:
      run:
        working-directory: python
@@ -183,100 +178,19 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_DEPLOYMENT_NAME=$AZURE_OPENAI_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_API_VERSION=$AZURE_OPENAI_API_VERSION" >> .env

      - name: Run sample validation
        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure_openai --save-report --report-name 02-agents-azure-openai
+          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure --save-report --report-name 02-agents-azure

      - name: Upload validation report
        uses: actions/upload-artifact@v7
        if: always()
        with:
-          name: validation-report-02-agents-azure-openai
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-azure-ai:
-    name: Validate 02-agents/providers/azure_ai
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_AI_CHAT_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
-      BING_CONNECTION_ID: ${{ secrets.BING_CONNECTION_ID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_AI_CHAT_MODEL_DEPLOYMENT_NAME=$AZURE_AI_CHAT_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME=$AZURE_AI_EMBEDDING_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "BING_CONNECTION_ID=$BING_CONNECTION_ID" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure_ai --save-report --report-name 02-agents-azure-ai
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-azure-ai
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-azure-ai-agent:
-    name: Validate 02-agents/providers/azure_ai_agent
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure_ai_agent --save-report --report-name 02-agents-azure-ai-agent
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-azure-ai-agent
+          name: validation-report-02-agents-azure
          path: python/samples/sample_validation/reports/

  validate-02-agents-anthropic:
@@ -409,11 +323,16 @@ jobs:
          name: validation-report-02-agents-ollama
          path: python/samples/sample_validation/reports/

-  validate-02-agents-foundry-local:
-    name: Validate 02-agents/providers/foundry_local
-    if: false # Temporarily disabled - requires local Foundry setup
+  validate-02-agents-foundry:
+    name: Validate 02-agents/providers/foundry
+    if: false # Temporarily disabled - provider folder also contains the local Foundry sample
    runs-on: ubuntu-latest
    environment: integration
+    env:
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_AGENT_NAME: ${{ vars.FOUNDRY_AGENT_NAME || '' }}
+      FOUNDRY_AGENT_VERSION: ${{ vars.FOUNDRY_AGENT_VERSION || '' }}
    defaults:
      run:
        working-directory: python
@@ -428,15 +347,22 @@ jobs:
          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
          os: ${{ runner.os }}

+      - name: Create .env for samples
+        run: |
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
+          echo "FOUNDRY_AGENT_NAME=$FOUNDRY_AGENT_NAME" >> .env
+          echo "FOUNDRY_AGENT_VERSION=$FOUNDRY_AGENT_VERSION" >> .env
+
      - name: Run sample validation
        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/foundry_local --save-report --report-name 02-agents-foundry-local
+          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/foundry --save-report --report-name 02-agents-foundry

      - name: Upload validation report
        uses: actions/upload-artifact@v7
        if: always()
        with:
-          name: validation-report-02-agents-foundry-local
+          name: validation-report-02-agents-foundry
          path: python/samples/sample_validation/reports/

  validate-02-agents-copilotstudio:
@@ -515,13 +441,8 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
    defaults:
      run:
        working-directory: python
@@ -538,11 +459,8 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env

      - name: Run sample validation
        run: |
@@ -561,12 +479,8 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # A2A configuration
      A2A_AGENT_HOST: http://localhost:5001/
    defaults:
@@ -600,19 +514,18 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # Azure OpenAI configuration
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # Azure AI Search (for evaluation samples)
      AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
      AZURE_SEARCH_API_KEY: ${{ secrets.AZURE_SEARCH_API_KEY }}
      AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
      # Evaluation sample
-      AZURE_AI_MODEL_DEPLOYMENT_NAME_WORKFLOW: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_MODEL_WORKFLOW: ${{ vars.FOUNDRY_MODEL_WORKFLOW || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_MODEL_EVAL: ${{ vars.FOUNDRY_MODEL_EVAL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
    defaults:
      run:
        working-directory: python
@@ -643,12 +556,11 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # Azure OpenAI configuration
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # OpenAI configuration
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
@@ -670,10 +582,10 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_DEPLOYMENT_NAME=$AZURE_OPENAI_DEPLOYMENT_NAME" >> .env
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
@@ -694,13 +606,11 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # Azure OpenAI configuration
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # OpenAI configuration
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
@@ -727,11 +637,10 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_DEPLOYMENT_NAME=$AZURE_OPENAI_DEPLOYMENT_NAME" >> .env
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
@@ -759,14 +668,12 @@ jobs:
      - validate-01-get-started
      - validate-02-agents
      - validate-02-agents-openai
-      - validate-02-agents-azure-openai
-      - validate-02-agents-azure-ai
-      - validate-02-agents-azure-ai-agent
+      - validate-02-agents-azure
      - validate-02-agents-anthropic
      - validate-02-agents-github-copilot
      - validate-02-agents-amazon
      - validate-02-agents-ollama
-      - validate-02-agents-foundry-local
+      - validate-02-agents-foundry
      - validate-02-agents-copilotstudio
      - validate-02-agents-custom
      - validate-03-workflows
@@ -123,22 +123,30 @@ We use and recommend the following workflow:
     "issue-123" or "githubhandle-issue".
 4. Make and commit your changes to your branch.
 5. Add new tests corresponding to your change, if applicable.
-6. Run the relevant scripts in [the section below](#development-scripts) to ensure that your build is clean and all tests are passing.
+6. Run the relevant scripts in [the section below](#development-setup) to ensure that your build is clean and all tests are passing.
 7. Create a PR against the repository's **main** branch.
   - State in the description what issue or improvement your change is addressing.
   - Verify that all the Continuous Integration checks are passing.
 8. Wait for feedback or approval of your changes from the code maintainers.
 9. When area owners have signed off, and all checks are green, your PR will be merged.

-### Development scripts
+### Development Setup

-The scripts below are used to build, test, and lint within the project.
+Each language has its own dev setup guide, coding standards, and build scripts:

- Python: see [python/DEV_SETUP.md](./python/DEV_SETUP.md).
- .NET:
-  - Build: `dotnet build`
-  - Test: `dotnet test`
-  - Linting (auto-fix): `dotnet format`
+- **Python**: [Dev Setup](./python/DEV_SETUP.md) · [Coding Standard](./python/CODING_STANDARD.md) · [README](./python/README.md)
+  - From the `./python` directory:
+    - Build: `uv run poe build`
+    - Unit tests: `uv run poe test -A -m "not integration"`
+    - Integration tests: `uv run poe test -A -m integration` (requires API keys/endpoints)
+    - Format + lint: `uv run poe syntax`
+    - All checks: `uv run poe check`
+- **.NET**: [README](./dotnet/README.md) · [Agent Instructions](./dotnet/AGENTS.md)
+  - From the `./dotnet` directory:
+    - Build: `dotnet build`
+    - Unit tests: `dotnet test --filter-query "/*UnitTests*/*/*/*"`
+    - Integration tests: `dotnet test --filter-query "/*IntegrationTests*/*/*/*"` (requires API keys/endpoints)
+    - Linting (auto-fix): `dotnet format`

 ### PR - CI Process

@@ -2,7 +2,7 @@

 # Welcome to Microsoft Agent Framework!

-[![Microsoft Azure AI Foundry Discord](https://dcbadge.limes.pink/api/server/b5zjErwbQM?style=flat)](https://discord.gg/b5zjErwbQM)
+[![Microsoft Foundry Discord](https://dcbadge.limes.pink/api/server/b5zjErwbQM?style=flat)](https://discord.gg/b5zjErwbQM)
 [![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
 [![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
 [![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
@@ -94,23 +94,23 @@ Create a simple Azure Responses Agent that writes a haiku about the Microsoft Ag
 # Use `az login` to authenticate with Azure CLI
 import os
 import asyncio
-from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
 from azure.identity import AzureCliCredential


 async def main():
-    # Initialize a chat agent with Azure OpenAI Responses
+    # Initialize a chat agent with Microsoft Foundry
    # the endpoint, deployment name, and api version can be set via environment variables
-    # or they can be passed in directly to the AzureOpenAIResponsesClient constructor
-    agent = AzureOpenAIResponsesClient(
-        # endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
-        # deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
-        # api_version=os.environ["AZURE_OPENAI_API_VERSION"],
-        # api_key=os.environ["AZURE_OPENAI_API_KEY"],  # Optional if using AzureCliCredential
-        credential=AzureCliCredential(), # Optional, if using api_key
-    ).as_agent(
-        name="HaikuBot",
-        instructions="You are an upbeat assistant that writes beautifully.",
+    # or they can be passed in directly to the FoundryChatClient constructor
+    agent = Agent(
+      client=FoundryChatClient(
+          credential=AzureCliCredential(),
+          # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+          # model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
+      ),
+      name="HaikuBot",
+      instructions="You are an upbeat assistant that writes beautifully.",
    )

    print(await agent.run("Write a haiku about Microsoft Agent Framework."))
@@ -137,24 +137,21 @@ var agent = new OpenAIClient("<apikey>")
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```

-Create a simple Agent, using Azure OpenAI Responses with token based auth, that writes a haiku about the Microsoft Agent Framework
+Create a simple Agent, using Microsoft Foundry with token-based auth, that writes a haiku about the Microsoft Agent Framework

 ```c#
-// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
+// dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
 // dotnet add package Azure.Identity
 // Use `az login` to authenticate with Azure CLI
-using System.ClientModel.Primitives;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
-using OpenAI.Responses;

-// Replace <resource> and gpt-4o-mini with your Azure OpenAI resource name and deployment name.
-var agent = new OpenAIClient(
-    new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
-    new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
-    .GetResponsesClient("gpt-4o-mini")
-    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");

 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
@@ -163,15 +160,43 @@ 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
+- [Getting Started](./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
+- [Workflows](./python/samples/03-workflows): workflow creation and integration with agents
+- [Hosting](./python/samples/04-hosting): A2A, Azure Functions, Durable Task hosting
+- [End-to-End](./python/samples/05-end-to-end): full applications, evaluation, and demos

 ### .NET

- [Getting Started with Agents](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
- [Agent Provider Samples](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
- [Workflow Samples](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started](./dotnet/samples/01-get-started): progressive tutorial from hello agent to hosting
+- [Agent Concepts](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
+- [Agent Providers](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
+- [Workflows](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
+- [Hosting](./dotnet/samples/04-hosting): A2A, Durable Agents, Durable Workflows
+- [End-to-End](./dotnet/samples/05-end-to-end): full applications and demos
+
+## Troubleshooting
+
+### Authentication
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Authentication errors when using Azure credentials | Not signed in to Azure CLI | Run `az login` before starting your app |
+| API key errors | Wrong or missing API key | Verify the key and ensure it's for the correct resource/provider |
+
+> **Tip:** `DefaultAzureCredential` is convenient for development but in production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
+### Environment Variables
+
+The samples typically read configuration from environment variables. Common required variables:
+
+| Variable | Used by | Purpose |
+|----------|---------|---------|
+| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI samples | Your Azure OpenAI resource URL |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI samples | Model deployment name (e.g. `gpt-4o-mini`) |
+| `AZURE_AI_PROJECT_ENDPOINT` | Microsoft Foundry samples | Your Microsoft Foundry project endpoint |
+| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Microsoft Foundry samples | Model deployment name |
+| `OPENAI_API_KEY` | OpenAI (non-Azure) samples | Your OpenAI platform API key |

 ## Contributor Resources

@@ -42,7 +42,7 @@ The persistence timing and `FunctionResultContent` trimming behaviors are interr
 ## Considered Options

 - Option 1: Per-run persistence with opt-in FRC (FunctionResultContent) trimming
- Option 2: Opt-in per-service-call persistence (via `SimulateServiceStoredChatHistory`)
+- Option 2: Opt-in per-service-call persistence (via `RequirePerServiceCallChatHistoryPersistence`)

 ## Pros and Cons of the Options

@@ -57,12 +57,12 @@ Keep the current default behavior of persisting chat history only at the end of
 - Bad, because if the process crashes mid-loop, all intermediate progress from the current run is lost, not satisfying driver C.
 - Bad, because this option alone does not provide a way for users to opt into per-service-call persistence, not satisfying driver E.

-### Option 2: Opt-in per-service-call persistence (via `SimulateServiceStoredChatHistory`)
+### Option 2: Opt-in per-service-call persistence (via `RequirePerServiceCallChatHistoryPersistence`)

-Introduce an optional SimulateServiceStoredChatHistory setting to persist chat history after each individual service call within the FIC loop, matching the AI service's behavior. Trailing `FunctionResultContent` trimming is unnecessary with this approach (it is naturally handled).
+Introduce an optional RequirePerServiceCallChatHistoryPersistence setting to persist chat history after each individual service call within the FIC loop, matching the AI service's behavior. Trailing `FunctionResultContent` trimming is unnecessary with this approach (it is naturally handled).

 Settings:
- `SimulateServiceStoredChatHistory` = `true`
+- `RequirePerServiceCallChatHistoryPersistence` = `true`

 - Good, because the stored history matches the service's behavior when opting in for both timing and content, fully satisfying driver A.
 - Good, because intermediate progress is preserved if the process is interrupted, satisfying driver C.
@@ -73,36 +73,49 @@ Settings:

 ## Decision Outcome

-Chosen option: **Option 2: Opt-in per-service-call persistence (via `SimulateServiceStoredChatHistory`)**. The existing per-run persistence behavior is retained as-is, requiring no changes from users. Per-service-call persistence is available as an opt-in feature via the `SimulateServiceStoredChatHistory` setting. This satisfies drivers B (atomicity) and D (simplicity) for the common case, while fully satisfying driver A (consistency) for users who opt into simulated service-stored behavior. Users who need per-service-call persistence for recoverability (driver C) can enable it explicitly.
+Chosen option: **Option 2: Opt-in per-service-call persistence (via `RequirePerServiceCallChatHistoryPersistence`)**. The existing per-run persistence behavior is retained as-is, requiring no changes from users. Per-service-call persistence is available as an opt-in feature via the `RequirePerServiceCallChatHistoryPersistence` setting. This satisfies drivers B (atomicity) and D (simplicity) for the common case, while fully satisfying driver A (consistency) for users who opt into simulated service-stored behavior. Users who need per-service-call persistence for recoverability (driver C) can enable it explicitly.

 ### Configuration Matrix

-The behavior depends on the combination of `UseProvidedChatClientAsIs` and `SimulateServiceStoredChatHistory`:
+The behavior depends on the combination of `UseProvidedChatClientAsIs` and `RequirePerServiceCallChatHistoryPersistence`:

-| `UseProvidedChatClientAsIs` | `SimulateServiceStoredChatHistory` | Behavior |
+| `UseProvidedChatClientAsIs` | `RequirePerServiceCallChatHistoryPersistence` | Behavior |
 |---|---|---|
 | `false` (default) | `false` (default) | **Per-run persistence.** Messages are persisted at the end of the full agent run via the `ChatHistoryProvider`. |
-| `false` | `true` | **Per-service-call persistence (simulated).** A `ServiceStoredSimulatingChatClient` middleware is automatically injected into the chat client pipeline between `FunctionInvokingChatClient` and the leaf `IChatClient`. Messages are persisted after each service call. A sentinel `ConversationId` causes FIC to treat the conversation as service-managed. |
+| `false` | `true` | **Per-service-call persistence (simulated).** A `PerServiceCallChatHistoryPersistingChatClient` middleware is automatically injected into the chat client pipeline between `FunctionInvokingChatClient` and the leaf `IChatClient`. Messages are persisted after each service call. A sentinel `ConversationId` causes FIC to treat the conversation as service-managed. |
 | `true` | `false` | **Per-run persistence.** No middleware is injected because the user has provided a custom chat client stack. Messages are persisted at the end of the run. |
-| `true` | `true` | **User responsibility.** The system checks whether the custom chat client stack includes a `ServiceStoredSimulatingChatClient`. If not, a warning is emitted — the user is expected to have added their own per-service-call persistence mechanism. End-of-run persistence is skipped. |
+| `true` | `true` | **User responsibility.** The system checks whether the custom chat client stack includes a `PerServiceCallChatHistoryPersistingChatClient`. If not, a warning is emitted — the user is expected to have added their own per-service-call persistence mechanism. End-of-run persistence is skipped. |

 ### Consequences

 - Good, because per-run persistence is atomic by default — chat history is only updated when the full run succeeds, satisfying driver B.
 - Good, because the default mental model is simple: one run = one history update, satisfying driver D.
- Good, because users who opt into `SimulateServiceStoredChatHistory` get stored history that matches the service's behavior for both timing and content, fully satisfying driver A.
+- Good, because users who opt into `RequirePerServiceCallChatHistoryPersistence` get stored history that matches the service's behavior for both timing and content, fully satisfying driver A.
 - Good, because per-service-call persistence preserves intermediate progress if the process is interrupted, satisfying driver C when opted in.
 - Good, because no separate `FunctionResultContent` trimming logic is needed when per-service-call persistence is active — it is naturally handled.
 - Good, because conflict detection (configurable via `ThrowOnChatHistoryProviderConflict`, `WarnOnChatHistoryProviderConflict`, `ClearOnChatHistoryProviderConflict`) prevents misconfiguration when a service returns a `ConversationId` alongside a configured `ChatHistoryProvider`.
 - Bad, because per-service-call persistence (when opted in) may leave chat history in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), requiring manual recovery in rare cases.
- Neutral, because users who want per-service-call consistency can opt in via `SimulateServiceStoredChatHistory = true`, satisfying driver E.
+- Neutral, because users who want per-service-call consistency can opt in via `RequirePerServiceCallChatHistoryPersistence = true`, satisfying driver E.
 - Neutral, because increased write frequency from per-service-call persistence may impact performance for some storage backends; this can be mitigated with a caching decorator.

 ### Implementation Notes

 #### Conversation ID Consistency

-We should introduce a separate `ConversationIdPersistingChatClient`, middleware which allows us to
-persist response `ConversationIds` during the FICC loop. This could be used with or without
-`ServiceStoredSimulatingChatClient`.
+When `RequirePerServiceCallChatHistoryPersistence` is enabled, the `PerServiceCallChatHistoryPersistingChatClient`
+decorator also updates `session.ConversationId` after each service call. This handles two scenarios:
+
+1. **Framework-managed chat history** — the decorator sets a sentinel `ConversationId` on the response
+   so that `FunctionInvokingChatClient` treats the conversation as service-managed (clearing accumulated
+   history between iterations and not injecting duplicate `FunctionCallContent` during approval processing).
+
+2. **Service-stored chat history** — when the service returns a real `ConversationId`, the decorator
+   updates `session.ConversationId` immediately after each service call, rather than deferring the update
+   to the end of the run. This ensures intermediate ConversationId changes are captured even if the
+   process is interrupted mid-loop.
+
+For some service-stored scenarios (e.g., the Conversations API with the Responses API), there is only
+one thread with one ID, so every service call returns the same ConversationId and this per-call update
+makes no practical difference. Enabling `RequirePerServiceCallChatHistoryPersistence` ensures consistent
+per-service-call behavior across all service types regardless of how they manage ConversationIds.

@@ -462,7 +462,7 @@ class FoundryEvals:
 ### Azure AI: FoundryEvals Constants

 ```python
-from agent_framework_azure_ai import FoundryEvals
+from agent_framework.foundry import FoundryEvals

 evaluators = [FoundryEvals.RELEVANCE, FoundryEvals.TOOL_CALL_ACCURACY]
 ```
@@ -0,0 +1,213 @@
+---
+name: verify-samples-tool
+description: How to use the verify-samples tool to run, verify, and manage sample definitions in the Agent Framework repository. Use this when adding, updating, or running sample verification.
+---
+
+# verify-samples Tool
+
+The `verify-samples` project (`dotnet/eng/verify-samples/`) is an automated tool that runs sample projects and verifies their output using deterministic checks and AI-powered verification.
+
+## Running verify-samples
+
+```bash
+cd dotnet
+
+# Run all samples across all categories
+dotnet run --project eng/verify-samples -- --log results.log --csv results.csv
+
+# Run a specific category
+dotnet run --project eng/verify-samples -- --category 02-agents --log results.log
+
+# Run specific samples by name
+dotnet run --project eng/verify-samples -- Agent_Step02_StructuredOutput Agent_Step09_AsFunctionTool
+
+# Control parallelism (default 8)
+dotnet run --project eng/verify-samples -- --parallel 8 --log results.log
+
+# Combine options
+dotnet run --project eng/verify-samples -- --category 03-workflows --parallel 4 --log results.log --csv results.csv
+```
+
+### Required Environment Variables
+
+The tool itself needs:
+- `AZURE_OPENAI_ENDPOINT` — for the AI verification agent
+- `AZURE_OPENAI_DEPLOYMENT_NAME` (optional, defaults to `gpt-5-mini`)
+
+Individual samples require their own env vars (e.g., `AZURE_AI_PROJECT_ENDPOINT`). The tool automatically checks and skips samples with missing env vars.
+
+### Output Files
+
+- `--log results.log` — detailed per-sample log with stdout/stderr, AI reasoning, and a summary
+- `--csv results.csv` — tabular summary with Sample, ProjectPath, Status, FailedChecks, and Failures columns
+
+## Sample Categories
+
+Definitions are in the `dotnet/eng/verify-samples/` directory:
+
+| Category | Config File | Registered Key |
+|----------|-------------|----------------|
+| 01-get-started | `GetStartedSamples.cs` | `01-get-started` |
+| 02-agents | `AgentsSamples.cs` | `02-agents` |
+| 03-workflows | `WorkflowSamples.cs` | `03-workflows` |
+
+Categories are registered in `VerifyOptions.cs` in the `s_sampleSets` dictionary.
+
+## SampleDefinition Properties
+
+Each sample is defined as a `SampleDefinition` in the appropriate config file. Key properties:
+
+```csharp
+new SampleDefinition
+{
+    // Required: Display name for the sample
+    Name = "Agent_Step02_StructuredOutput",
+
+    // Required: Relative path from dotnet/ to the sample project directory
+    ProjectPath = "samples/02-agents/Agents/Agent_Step02_StructuredOutput",
+
+    // Environment variables the sample requires (throws if missing)
+    RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+
+    // Environment variables with defaults that would prompt on console if unset
+    OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+
+    // Skip this sample with a reason (for structural issues only)
+    SkipReason = null, // or "Requires external service X."
+
+    // Deterministic checks: substrings that must appear in stdout
+    MustContain = ["=== Section Header ==="],
+
+    // Substrings that must NOT appear in stdout
+    MustNotContain = [],
+
+    // If true, only MustContain checks are used (no AI verification)
+    IsDeterministic = false,
+
+    // AI verification: natural-language descriptions of expected output
+    // Each entry describes one aspect to verify independently
+    ExpectedOutputDescription =
+    [
+        "The output should show structured person information with Name, Age, and Occupation fields.",
+        "The output should not contain error messages or stack traces.",
+    ],
+
+    // Stdin inputs to feed to the sample (for interactive samples)
+    Inputs = ["Y", "Y", "Y"],
+
+    // Delay between stdin inputs in ms (default 2000, increase for LLM calls between inputs)
+    InputDelayMs = 3000,
+}
+```
+
+## How to Add a New Sample Definition
+
+1. **Check the sample's Program.cs** to understand:
+   - What environment variables it reads (look for `GetEnvironmentVariable`)
+   - Whether it needs stdin input (look for `Console.ReadLine`, `Application.GetInput`)
+   - Whether it has an external loop (look for `EXIT` patterns in YAML workflows)
+   - What output it produces (section headers, markers, expected behavior)
+   - Whether it exits on its own or runs as a server
+
+2. **Choose the right verification strategy:**
+   - **Deterministic** (`IsDeterministic = true`): Use `MustContain` for samples with fixed output strings. No AI verification.
+   - **AI-verified** (default): Use `ExpectedOutputDescription` with semantic descriptions. Write expectations that are flexible enough for non-deterministic LLM output.
+   - **Both**: Use `MustContain` for fixed markers AND `ExpectedOutputDescription` for LLM-generated content.
+
+3. **Set `SkipReason` only for structural issues:**
+   - Web servers that don't exit
+   - Multi-process client/server architectures
+   - Samples requiring external infrastructure (MCP servers you can't reach, Docker, etc.)
+   - Do NOT skip for missing env vars — the tool checks those dynamically.
+
+4. **For interactive samples, provide `Inputs`:**
+   - Samples using `Application.GetInput(args)` need one initial input
+   - Samples with `Console.ReadLine()` approval loops need `"Y"` inputs
+   - YAML workflows with `externalLoop` need `"EXIT"` as the last input
+   - Set `InputDelayMs` to 3000-8000ms for samples with LLM calls between inputs
+
+5. **Add the definition** to the appropriate config file (e.g., `AgentsSamples.cs`) in the `All` list.
+
+6. **Register new categories** (if needed) in `VerifyOptions.cs` `s_sampleSets` dictionary.
+
+### Writing Good ExpectedOutputDescription
+
+- Write descriptions that are **semantically flexible** — LLM output varies between runs
+- Each array entry should describe **one independent aspect** to verify
+- Always include `"The output should not contain error messages or stack traces."` as the last entry
+- Avoid exact wording expectations — use "should mention", "should contain information about", "should show"
+- Bad: `"The output should say 'The weather in Amsterdam is cloudy with a high of 15°C'"`
+- Good: `"The output should contain weather information about Amsterdam mentioning cloudy weather with a high of 15°C."`
+
+### Example: Simple LLM Sample
+
+```csharp
+new SampleDefinition
+{
+    Name = "Agent_With_AzureOpenAIChatCompletion",
+    ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion",
+    RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+    ExpectedOutputDescription =
+    [
+        "The output should contain a joke about a pirate.",
+        "The output should not contain error messages or stack traces.",
+    ],
+},
+```
+
+### Example: Deterministic Sample
+
+```csharp
+new SampleDefinition
+{
+    Name = "Workflow_Declarative_GenerateCode",
+    ProjectPath = "samples/03-workflows/Declarative/GenerateCode",
+    IsDeterministic = true,
+    MustContain = ["WORKFLOW: Parsing", "WORKFLOW: Defined"],
+    ExpectedOutputDescription = ["The output should show a YAML workflow being parsed and C# code being generated from it."],
+},
+```
+
+### Example: Interactive Sample with Approval Loop
+
+```csharp
+new SampleDefinition
+{
+    Name = "FoundryAgent_Hosted_MCP",
+    ProjectPath = "samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP",
+    RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+    Inputs = ["Y", "Y", "Y", "Y", "Y"],
+    InputDelayMs = 5000,
+    ExpectedOutputDescription = ["The output should show an agent using the Microsoft Learn MCP tool with approval prompts."],
+},
+```
+
+### Example: Declarative Workflow with External Loop
+
+```csharp
+new SampleDefinition
+{
+    Name = "Workflow_Declarative_FunctionTools",
+    ProjectPath = "samples/03-workflows/Declarative/FunctionTools",
+    RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+    Inputs = ["What are today's specials?", "EXIT"],
+    InputDelayMs = 8000,
+    ExpectedOutputDescription = ["The output should show a workflow calling function tools to answer a question about restaurant specials."],
+},
+```
+
+### Example: Skipped Sample
+
+```csharp
+new SampleDefinition
+{
+    Name = "Agent_MCP_Server",
+    ProjectPath = "samples/02-agents/ModelContextProtocol/Agent_MCP_Server",
+    RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+    SkipReason = "Runs as an MCP stdio server that does not exit on its own.",
+},
+```
@@ -7,6 +7,7 @@
  <Folder Name="/Samples/">
    <File Path="samples/AGENTS.md" />
    <File Path="samples/README.md" />
+    <Project Path="eng/verify-samples/verify-samples.csproj" />
  </Folder>
  <Folder Name="/Samples/01-get-started/">
    <Project Path="samples/01-get-started/01_hello_agent/01_hello_agent.csproj" />
@@ -171,6 +172,7 @@
    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step05_Neo4jGraphRAG/AgentWithRAG_Step05_Neo4jGraphRAG.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Thread-safe console output with sample-name prefixes and colored status.
+/// </summary>
+internal sealed class ConsoleReporter
+{
+    private readonly object _lock = new();
+
+    /// <summary>
+    /// Writes a complete prefixed line atomically to the console.
+    /// </summary>
+    public void WriteLineWithPrefix(string sampleName, string message, ConsoleColor? color = null)
+    {
+        lock (this._lock)
+        {
+            Console.ForegroundColor = ConsoleColor.Cyan;
+            Console.Write($"[{sampleName}] ");
+            if (color.HasValue)
+            {
+                Console.ForegroundColor = color.Value;
+            }
+            else
+            {
+                Console.ResetColor();
+            }
+
+            Console.WriteLine(message);
+            Console.ResetColor();
+        }
+    }
+
+    /// <summary>
+    /// Prints the final summary table and elapsed time to the console.
+    /// </summary>
+    public void PrintSummary(
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        TimeSpan elapsed)
+    {
+        var passCount = orderedResults.Count(r => r.Passed);
+        var failCount = orderedResults.Count(r => !r.Passed);
+
+        Console.WriteLine();
+        Console.WriteLine(new string('─', 60));
+        Console.ForegroundColor = ConsoleColor.White;
+        Console.WriteLine("SUMMARY");
+        Console.ResetColor();
+
+        foreach (var result in orderedResults)
+        {
+            Console.ForegroundColor = result.Passed ? ConsoleColor.Green : ConsoleColor.Red;
+            Console.Write(result.Passed ? "  ✓ " : "  ✗ ");
+            Console.ResetColor();
+            Console.WriteLine($"{result.SampleName}: {result.Summary}");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            Console.ForegroundColor = ConsoleColor.Yellow;
+            Console.Write("  ○ ");
+            Console.ResetColor();
+            Console.WriteLine($"{name}: Skipped — {reason}");
+        }
+
+        Console.WriteLine();
+        Console.Write("Results: ");
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.Write($"{passCount} passed");
+        Console.ResetColor();
+
+        if (failCount > 0)
+        {
+            Console.Write(", ");
+            Console.ForegroundColor = ConsoleColor.Red;
+            Console.Write($"{failCount} failed");
+            Console.ResetColor();
+        }
+
+        if (skipped.Count > 0)
+        {
+            Console.Write(", ");
+            Console.ForegroundColor = ConsoleColor.Yellow;
+            Console.Write($"{skipped.Count} skipped");
+            Console.ResetColor();
+        }
+
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine($"Elapsed: {elapsed.Hours:D2}:{elapsed.Minutes:D2}:{elapsed.Seconds:D2}");
+        Console.ResetColor();
+    }
+}
@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Writes a CSV summary of sample verification results.
+/// </summary>
+internal static class CsvResultWriter
+{
+    /// <summary>
+    /// Writes the results to a CSV file at the specified path.
+    /// </summary>
+    public static async Task WriteAsync(
+        string path,
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        IReadOnlyList<SampleDefinition> samples)
+    {
+        var pathLookup = samples.ToDictionary(s => s.Name, s => s.ProjectPath);
+
+        var sb = new StringBuilder();
+        sb.AppendLine("Sample,ProjectPath,Status,FailedChecks,Failures");
+
+        foreach (var result in orderedResults)
+        {
+            var status = result.Passed ? "PASSED" : "FAILED";
+            var failedChecks = result.Failures.Count;
+            var failures = string.Join("; ", result.Failures);
+            pathLookup.TryGetValue(result.SampleName, out var projectPath);
+            sb.AppendLine($"{CsvEscape(result.SampleName)},{CsvEscape(projectPath ?? "")},{status},{failedChecks},{CsvEscape(failures)}");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            pathLookup.TryGetValue(name, out var projectPath);
+            sb.AppendLine($"{CsvEscape(name)},{CsvEscape(projectPath ?? "")},SKIPPED,0,{CsvEscape(reason)}");
+        }
+
+        await File.WriteAllTextAsync(path, sb.ToString());
+    }
+
+    /// <summary>
+    /// Escapes a value for CSV: wraps in quotes if it contains commas, quotes, or newlines.
+    /// </summary>
+    private static string CsvEscape(string value)
+    {
+        if (value.Contains('"') || value.Contains(',') || value.Contains('\n') || value.Contains('\r'))
+        {
+            return $"\"{value.Replace("\"", "\"\"")}\"";
+        }
+
+        return value;
+    }
+}
@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Defines the expected behavior for each sample in 01-get-started.
+/// </summary>
+internal static class GetStartedSamples
+{
+    public static IReadOnlyList<SampleDefinition> All { get; } =
+    [
+        new SampleDefinition
+        {
+            Name = "05_first_workflow",
+            ProjectPath = "samples/01-get-started/05_first_workflow",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "UppercaseExecutor: HELLO, WORLD!",
+                "ReverseTextExecutor: !DLROW ,OLLEH",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "01_hello_agent",
+            ProjectPath = "samples/01-get-started/01_hello_agent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should contain a joke about a pirate.",
+                "There should be two separate joke responses — one from a non-streaming call and one from a streaming call.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "02_add_tools",
+            ProjectPath = "samples/01-get-started/02_add_tools",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain = [],
+            ExpectedOutputDescription =
+            [
+                "The output should contain information about the weather in Amsterdam.",
+                "The response should mention that it is cloudy with a high of 15°C (or equivalent), since this comes from a tool that returns a canned response.",
+                "There should be two responses — one from a non-streaming call and one from a streaming call.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "03_multi_turn",
+            ProjectPath = "samples/01-get-started/03_multi_turn",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should contain a joke about a pirate.",
+                "After the initial joke, there should be a modified version that includes emojis and is told in the voice of a pirate's parrot.",
+                "The pattern repeats: first a non-streaming pirate joke + parrot version, then a streaming pirate joke + parrot version.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "04_memory",
+            ProjectPath = "samples/01-get-started/04_memory",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain =
+            [
+                ">> Use session with blank memory",
+                ">> Use deserialized session with previously created memories",
+                ">> Read memories using memory component",
+                "MEMORY - User Name:",
+                "MEMORY - User Age:",
+                ">> Use new session with previously created memories",
+            ],
+            ExpectedOutputDescription =
+            [
+                "In the 'Use session with blank memory' section, the agent should respond to the user's messages. It may ask for the user's name or age if not yet known.",
+                "In the 'Use deserialized session with previously created memories' section, the agent should correctly recall that the user's name is Ruaidhrí and age is 20.",
+                "The 'MEMORY - User Name:' line should show 'Ruaidhrí' (or a close transliteration).",
+                "The 'MEMORY - User Age:' line should show '20'.",
+                "In the 'Use new session with previously created memories' section, the agent should know the user's name and age from the transferred memory.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "06_host_your_agent",
+            ProjectPath = "samples/01-get-started/06_host_your_agent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            SkipReason = "Requires Azure Functions Core Tools runtime and starts a web server.",
+        },
+    ];
+}
@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Incrementally writes a sequential (non-interleaved) log file, appending after each sample completes.
+/// Thread-safe: multiple parallel tasks may call write methods concurrently.
+/// </summary>
+internal sealed class LogFileWriter : IDisposable
+{
+    private readonly string _path;
+    private readonly SemaphoreSlim _writeLock = new(1, 1);
+
+    public LogFileWriter(string path)
+    {
+        this._path = path;
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        this._writeLock.Dispose();
+    }
+
+    /// <summary>
+    /// Writes the log file header. Call once at the start of the run.
+    /// </summary>
+    public async Task WriteHeaderAsync()
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine($"Sample Verification Log — {DateTime.UtcNow:yyyy-MM-dd HH:mm:ss} UTC");
+        sb.AppendLine(new string('═', 72));
+        sb.AppendLine();
+
+        await File.WriteAllTextAsync(this._path, sb.ToString());
+    }
+
+    /// <summary>
+    /// Appends a skipped-sample entry to the log file.
+    /// </summary>
+    public async Task WriteSkippedAsync(string name, string reason)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine($"── {name} ──");
+        sb.AppendLine($"Status: SKIPPED — {reason}");
+        sb.AppendLine();
+
+        await this.AppendAsync(sb.ToString());
+    }
+
+    /// <summary>
+    /// Appends a completed sample's full output section to the log file.
+    /// </summary>
+    public async Task WriteSampleResultAsync(VerificationResult result)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine(new string('─', 72));
+        sb.AppendLine($"── {result.SampleName} ──");
+        sb.AppendLine($"Status: {(result.Passed ? "PASSED" : "FAILED")}");
+        sb.AppendLine();
+
+        foreach (var line in result.LogLines)
+        {
+            sb.AppendLine(line);
+        }
+
+        sb.AppendLine();
+
+        if (!string.IsNullOrWhiteSpace(result.Stdout))
+        {
+            sb.AppendLine("--- stdout ---");
+            sb.AppendLine(result.Stdout.TrimEnd());
+            sb.AppendLine("--- end stdout ---");
+            sb.AppendLine();
+        }
+
+        if (!string.IsNullOrWhiteSpace(result.Stderr))
+        {
+            sb.AppendLine("--- stderr ---");
+            sb.AppendLine(result.Stderr.TrimEnd());
+            sb.AppendLine("--- end stderr ---");
+            sb.AppendLine();
+        }
+
+        if (result.Failures.Count > 0)
+        {
+            sb.AppendLine("Failures:");
+            foreach (var failure in result.Failures)
+            {
+                sb.AppendLine($"  ✗ {failure}");
+            }
+
+            sb.AppendLine();
+        }
+
+        if (result.AIReasoning is not null)
+        {
+            sb.AppendLine("AI Reasoning:");
+            sb.AppendLine(result.AIReasoning);
+            sb.AppendLine();
+        }
+
+        await this.AppendAsync(sb.ToString());
+    }
+
+    /// <summary>
+    /// Appends the final summary section and elapsed time to the log file.
+    /// </summary>
+    public async Task WriteSummaryAsync(
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        TimeSpan elapsed)
+    {
+        var passCount = orderedResults.Count(r => r.Passed);
+        var failCount = orderedResults.Count(r => !r.Passed);
+
+        var sb = new StringBuilder();
+        sb.AppendLine(new string('═', 72));
+        sb.AppendLine("SUMMARY");
+        sb.AppendLine();
+
+        foreach (var result in orderedResults)
+        {
+            sb.AppendLine($"  {(result.Passed ? "✓" : "✗")} {result.SampleName}: {result.Summary}");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            sb.AppendLine($"  ○ {name}: Skipped — {reason}");
+        }
+
+        sb.AppendLine();
+        sb.AppendLine($"Results: {passCount} passed{(failCount > 0 ? $", {failCount} failed" : "")}{(skipped.Count > 0 ? $", {skipped.Count} skipped" : "")}");
+        sb.AppendLine($"Elapsed: {elapsed.Hours:D2}:{elapsed.Minutes:D2}:{elapsed.Seconds:D2}");
+
+        await this.AppendAsync(sb.ToString());
+    }
+
+    private async Task AppendAsync(string text)
+    {
+        await this._writeLock.WaitAsync();
+        try
+        {
+            await File.AppendAllTextAsync(this._path, text);
+        }
+        finally
+        {
+            this._writeLock.Release();
+        }
+    }
+}
@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This tool runs the 01-get-started, 02-agents, and 03-workflows samples and verifies their output.
+// Deterministic samples are verified with exact string matching.
+// Non-deterministic (LLM) samples are verified using an agent-framework agent.
+//
+// Usage:
+//   dotnet run                                          # Run all samples
+//   dotnet run -- 01_hello_agent 05_first_workflow      # Run specific samples by name
+//   dotnet run -- --category 01-get-started             # Run the 01-get-started category
+//   dotnet run -- --category 02-agents                  # Run the 02-agents category
+//   dotnet run -- --category 03-workflows               # Run the 03-workflows category
+//   dotnet run -- --parallel 16                         # Run up to 16 samples concurrently
+//   dotnet run -- --log results.log                     # Write sequential log to file
+//   dotnet run -- --csv results.csv                     # Write CSV summary to file
+//
+// Required environment variables (for AI-powered samples):
+//   AZURE_OPENAI_ENDPOINT
+//   AZURE_OPENAI_DEPLOYMENT_NAME (optional, defaults to gpt-5-mini)
+
+using System.Diagnostics;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using VerifySamples;
+
+var options = VerifyOptions.Parse(args);
+if (options is null)
+{
+    return 1;
+}
+
+var stopwatch = Stopwatch.StartNew();
+
+// Resolve the dotnet/ root directory (verify-samples is at dotnet/eng/verify-samples/)
+var dotnetRoot = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "..", ".."));
+if (!File.Exists(Path.Combine(dotnetRoot, "agent-framework-dotnet.slnx")))
+{
+    dotnetRoot = Path.GetFullPath(Path.Combine(Directory.GetCurrentDirectory(), "..", ".."));
+}
+
+// Set up the AI verifier
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5-mini";
+
+OpenAI.Chat.ChatClient? chatClient = null;
+if (!string.IsNullOrEmpty(endpoint))
+{
+    chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+        .GetChatClient(deploymentName);
+}
+
+// Set up optional log file writer
+LogFileWriter? logWriter = null;
+if (options.LogFilePath is not null)
+{
+    logWriter = new LogFileWriter(options.LogFilePath);
+    await logWriter.WriteHeaderAsync();
+}
+
+try
+{
+    // Run all samples
+    var reporter = new ConsoleReporter();
+    var verifier = new SampleVerifier(chatClient);
+    var orchestrator = new VerificationOrchestrator(verifier, reporter, dotnetRoot, TimeSpan.FromMinutes(3), logWriter);
+
+    var run = await orchestrator.RunAllAsync(options.Samples, options.MaxParallelism);
+
+    stopwatch.Stop();
+
+    // Print summary
+    var orderedResults = run.SampleOrder
+        .Where(run.Results.ContainsKey)
+        .Select(name => run.Results[name])
+        .ToList();
+
+    reporter.PrintSummary(orderedResults, run.Skipped, stopwatch.Elapsed);
+
+    // Write log file summary
+    if (logWriter is not null)
+    {
+        await logWriter.WriteSummaryAsync(orderedResults, run.Skipped, stopwatch.Elapsed);
+        Console.WriteLine($"Log written to: {options.LogFilePath}");
+    }
+
+    // Write CSV summary
+    if (options.CsvFilePath is not null)
+    {
+        await CsvResultWriter.WriteAsync(options.CsvFilePath, orderedResults, run.Skipped, options.Samples);
+        Console.WriteLine($"CSV written to: {options.CsvFilePath}");
+    }
+
+    return orderedResults.Any(r => !r.Passed) ? 1 : 0;
+}
+finally
+{
+    logWriter?.Dispose();
+}
@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Describes a sample to verify, including its expected output.
+/// </summary>
+internal sealed class SampleDefinition
+{
+    /// <summary>
+    /// Display name for the sample (e.g., "01_hello_agent").
+    /// </summary>
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Relative path from the dotnet/ directory to the sample project directory.
+    /// </summary>
+    public required string ProjectPath { get; init; }
+
+    /// <summary>
+    /// Environment variables that the sample requires for a meaningful run.
+    /// The runner checks these before running and will skip the sample if any are unset,
+    /// recording a skip reason that indicates which required variables are missing.
+    /// </summary>
+    public string[] RequiredEnvironmentVariables { get; init; } = [];
+
+    /// <summary>
+    /// Environment variables that the sample can use but typically has fallbacks or defaults for.
+    /// If these are not set, the sample might prompt or behave interactively, which could cause
+    /// automated verification to hang. The runner checks these and skips the sample if they are unset
+    /// to avoid non-deterministic or blocking behavior in automated runs.
+    /// </summary>
+    public string[] OptionalEnvironmentVariables { get; init; } = [];
+
+    /// <summary>
+    /// If set, the sample is skipped with this reason.
+    /// Use only for structural reasons (e.g., web server, multi-process, needs external service).
+    /// Do NOT use for missing environment variables — those are checked dynamically.
+    /// </summary>
+    public string? SkipReason { get; init; }
+
+    /// <summary>
+    /// Substrings that must appear in stdout for the sample to pass.
+    /// Used for deterministic verification.
+    /// </summary>
+    public string[] MustContain { get; init; } = [];
+
+    /// <summary>
+    /// Substrings that must not appear in stdout for the sample to pass.
+    /// </summary>
+    public string[] MustNotContain { get; init; } = [];
+
+    /// <summary>
+    /// If true, <see cref="MustContain"/> entries cover the entire expected output —
+    /// no AI verification is needed.
+    /// </summary>
+    public bool IsDeterministic { get; init; }
+
+    /// <summary>
+    /// Natural-language description of what the sample output should look like.
+    /// Used by the AI verifier for non-deterministic samples.
+    /// Each entry describes one aspect of the expected output that should be verified.
+    /// </summary>
+    public string[] ExpectedOutputDescription { get; init; } = [];
+
+    /// <summary>
+    /// Sequence of stdin inputs to feed to the sample process.
+    /// Each entry is written as a line (followed by newline) to the process stdin.
+    /// A <c>null</c> entry inserts a delay without writing anything.
+    /// Inputs are sent with a short delay between each to allow the process to prompt.
+    /// </summary>
+    public string?[] Inputs { get; init; } = [];
+
+    /// <summary>
+    /// Delay in milliseconds between each input line. Default is 2000ms.
+    /// Increase for samples that need more time between prompts (e.g., LLM calls between inputs).
+    /// </summary>
+    public int InputDelayMs { get; init; } = 2000;
+}
@@ -0,0 +1,132 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Result of running a sample process.
+/// </summary>
+internal sealed record SampleRunResult(
+    string Stdout,
+    string Stderr,
+    int ExitCode,
+    TimeSpan Elapsed);
+
+/// <summary>
+/// Runs a sample project via <c>dotnet run</c> and captures its output.
+/// </summary>
+internal static class SampleRunner
+{
+    /// <summary>
+    /// Runs <c>dotnet run --framework net10.0</c> in the given project directory.
+    /// </summary>
+    public static Task<SampleRunResult> RunAsync(
+        string projectPath,
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default)
+        => RunAsync(projectPath, "run --framework net10.0", timeout, inputs: null, inputDelayMs: 0, cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Runs <c>dotnet run --framework net10.0</c> with stdin inputs.
+    /// </summary>
+    public static Task<SampleRunResult> RunAsync(
+        string projectPath,
+        TimeSpan timeout,
+        string?[]? inputs,
+        int inputDelayMs = 2000,
+        CancellationToken cancellationToken = default)
+        => RunAsync(projectPath, "run --framework net10.0", timeout, inputs, inputDelayMs, cancellationToken);
+
+    /// <summary>
+    /// Runs an arbitrary <c>dotnet</c> command in the given working directory.
+    /// </summary>
+    public static async Task<SampleRunResult> RunAsync(
+        string workingDirectory,
+        string dotnetArgs,
+        TimeSpan timeout,
+        string?[]? inputs = null,
+        int inputDelayMs = 0,
+        CancellationToken cancellationToken = default)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = "dotnet",
+            Arguments = dotnetArgs,
+            WorkingDirectory = workingDirectory,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            RedirectStandardInput = inputs is { Length: > 0 },
+            UseShellExecute = false,
+            CreateNoWindow = true,
+        };
+
+        var sw = Stopwatch.StartNew();
+
+        using var process = new Process { StartInfo = psi };
+        process.Start();
+
+        var stdoutTask = process.StandardOutput.ReadToEndAsync(cancellationToken);
+        var stderrTask = process.StandardError.ReadToEndAsync(cancellationToken);
+
+        // Feed stdin inputs with delays if configured
+        if (inputs is { Length: > 0 })
+        {
+            _ = Task.Run(async () =>
+            {
+                try
+                {
+                    foreach (var input in inputs)
+                    {
+                        await Task.Delay(inputDelayMs, cancellationToken);
+                        if (input is not null)
+                        {
+                            await process.StandardInput.WriteLineAsync(input.AsMemory(), cancellationToken);
+                            await process.StandardInput.FlushAsync(cancellationToken);
+                        }
+                    }
+
+                    process.StandardInput.Close();
+                }
+                catch (Exception ex) when (ex is IOException or ObjectDisposedException or OperationCanceledException)
+                {
+                    // Process may have exited before all inputs were sent
+                }
+            }, cancellationToken);
+        }
+
+        using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        cts.CancelAfter(timeout);
+
+        try
+        {
+            await process.WaitForExitAsync(cts.Token);
+        }
+        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+        {
+            // Timeout — kill the process
+            try
+            {
+                process.Kill(entireProcessTree: true);
+            }
+            catch
+            {
+                // Best effort
+            }
+
+            sw.Stop();
+            return new SampleRunResult(
+                Stdout: await stdoutTask,
+                Stderr: $"TIMEOUT: Sample did not complete within {timeout.TotalSeconds}s.\n{await stderrTask}",
+                ExitCode: -1,
+                Elapsed: sw.Elapsed);
+        }
+
+        sw.Stop();
+        return new SampleRunResult(
+            Stdout: await stdoutTask,
+            Stderr: await stderrTask,
+            ExitCode: process.ExitCode,
+            Elapsed: sw.Elapsed);
+    }
+}
@@ -0,0 +1,202 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Verifies sample output using deterministic checks and an AI agent
+/// for non-deterministic output validation.
+/// </summary>
+internal sealed class SampleVerifier
+{
+    private readonly AIAgent? _verifierAgent;
+
+    /// <summary>
+    /// Creates a verifier. If <paramref name="chatClient"/> is provided,
+    /// AI-based verification is available for non-deterministic samples.
+    /// </summary>
+    public SampleVerifier(ChatClient? chatClient = null)
+    {
+        if (chatClient is not null)
+        {
+            this._verifierAgent = chatClient.AsAIAgent(
+                instructions: """
+                    You are a test output verifier. You will be given:
+                    1. The actual stdout output of a program
+                    2. A list of expectations about what the output should contain or demonstrate
+
+                    Your job is to determine whether the actual output satisfies each expectation.
+                    Be reasonable — the output comes from an LLM so exact wording won't match, but the
+                    semantic intent should be clearly satisfied.
+                    """,
+                name: "OutputVerifier");
+        }
+    }
+
+    /// <summary>
+    /// Verifies the output of a sample run against its definition.
+    /// </summary>
+    public async Task<VerificationResult> VerifyAsync(SampleDefinition sample, SampleRunResult run)
+    {
+        var failures = new List<string>();
+
+        // 1. Exit code check
+        if (run.ExitCode != 0)
+        {
+            failures.Add($"Exit code was {run.ExitCode}, expected 0. Stderr: {Truncate(run.Stderr, 500)}");
+        }
+
+        // 2. Must-contain checks
+        foreach (var expected in sample.MustContain)
+        {
+            if (!run.Stdout.Contains(expected, StringComparison.Ordinal))
+            {
+                failures.Add($"Output missing expected substring: \"{expected}\"");
+            }
+        }
+
+        // 3. Must-not-contain checks
+        foreach (var unexpected in sample.MustNotContain)
+        {
+            if (run.Stdout.Contains(unexpected, StringComparison.Ordinal))
+            {
+                failures.Add($"Output contains unexpected substring: \"{unexpected}\"");
+            }
+        }
+
+        // 4. AI verification for non-deterministic samples
+        string? aiReasoning = null;
+        if (!sample.IsDeterministic && sample.ExpectedOutputDescription.Length > 0)
+        {
+            if (this._verifierAgent is null)
+            {
+                failures.Add("AI verification required but no AI agent configured (missing AZURE_OPENAI_ENDPOINT).");
+            }
+            else
+            {
+                var aiResult = await this.VerifyWithAIAsync(run.Stdout, sample.ExpectedOutputDescription);
+                aiReasoning = aiResult.Reasoning;
+
+                foreach (var unmet in aiResult.UnmetExpectations)
+                {
+                    failures.Add($"AI expectation not met: {unmet}");
+                }
+            }
+        }
+
+        bool passed = failures.Count == 0;
+        return new VerificationResult
+        {
+            SampleName = sample.Name,
+            Passed = passed,
+            Summary = passed ? "All checks passed" : $"{failures.Count} check(s) failed",
+            Failures = failures,
+            AIReasoning = aiReasoning,
+        };
+    }
+
+    private async Task<(string Reasoning, List<string> UnmetExpectations)> VerifyWithAIAsync(
+        string actualOutput,
+        string[] expectations)
+    {
+        var expectationList = string.Join("\n", expectations.Select((e, i) => $"  {i + 1}. {e}"));
+        var prompt = $"""
+            Actual program output:
+            ---
+            {Truncate(actualOutput, 4000)}
+            ---
+
+            Expectations to verify:
+            {expectationList}
+
+            Does the output satisfy all expectations?
+            """;
+
+        try
+        {
+            var response = await this._verifierAgent!.RunAsync<AIVerificationResponse>(prompt);
+            var result = response.Result;
+
+            if (result is null)
+            {
+                return ($"AI verification returned null result. Raw: {response.Text}", ["AI verification returned null result."]);
+            }
+
+            var reasoning = result.Reasoning ?? "(no reasoning provided)";
+
+            // Collect unmet expectations as individual failures
+            var unmet = new List<string>();
+            if (result.ExpectationResults is { Count: > 0 })
+            {
+                foreach (var er in result.ExpectationResults.Where(er => !er.Met))
+                {
+                    var detail = string.IsNullOrWhiteSpace(er.Detail) ? er.Expectation : $"{er.Expectation} — {er.Detail}";
+                    unmet.Add(detail ?? "Unknown expectation");
+                }
+
+                // If the model flagged overall failure but all individual expectations were met,
+                // still treat as failure using the overall reasoning.
+                if (unmet.Count == 0 && !result.Pass)
+                {
+                    unmet.Add(reasoning);
+                }
+            }
+            else if (!result.Pass)
+            {
+                // Fallback: no per-expectation detail but overall pass is false
+                unmet.Add(reasoning);
+            }
+
+            return (reasoning, unmet);
+        }
+        catch (Exception ex)
+        {
+            return ($"AI verification error: {ex.Message}", [$"AI verification error: {ex.Message}"]);
+        }
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : text[..maxLength] + "... (truncated)";
+}
+
+/// <summary>
+/// Structured response from the AI verification agent.
+/// </summary>
+[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by JSON deserialization via RunAsync<T>.")]
+internal sealed class AIVerificationResponse
+{
+    /// <summary>Whether all expectations were met.</summary>
+    [JsonPropertyName("pass")]
+    public bool Pass { get; set; }
+
+    /// <summary>Brief explanation of the overall assessment.</summary>
+    [JsonPropertyName("reasoning")]
+    public string? Reasoning { get; set; }
+
+    /// <summary>Per-expectation results.</summary>
+    [JsonPropertyName("expectation_results")]
+    public List<ExpectationResult>? ExpectationResults { get; set; }
+}
+
+/// <summary>
+/// Result for an individual expectation check.
+/// </summary>
+[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by JSON deserialization via RunAsync<T>.")]
+internal sealed class ExpectationResult
+{
+    /// <summary>The expectation text that was evaluated.</summary>
+    [JsonPropertyName("expectation")]
+    public string? Expectation { get; set; }
+
+    /// <summary>Whether this expectation was met.</summary>
+    [JsonPropertyName("met")]
+    public bool Met { get; set; }
+
+    /// <summary>Detail about how the expectation was or was not met.</summary>
+    [JsonPropertyName("detail")]
+    public string? Detail { get; set; }
+}
@@ -0,0 +1,197 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Concurrent;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Orchestrates sample verification: filters, runs in parallel, and collects results.
+/// </summary>
+internal sealed class VerificationOrchestrator
+{
+    private readonly SampleVerifier _verifier;
+    private readonly ConsoleReporter _reporter;
+    private readonly LogFileWriter? _logWriter;
+    private readonly string _dotnetRoot;
+    private readonly TimeSpan _timeout;
+
+    public VerificationOrchestrator(
+        SampleVerifier verifier,
+        ConsoleReporter reporter,
+        string dotnetRoot,
+        TimeSpan timeout,
+        LogFileWriter? logWriter = null)
+    {
+        this._verifier = verifier;
+        this._reporter = reporter;
+        this._logWriter = logWriter;
+        this._dotnetRoot = dotnetRoot;
+        this._timeout = timeout;
+    }
+
+    /// <summary>
+    /// The result of running all samples through the orchestrator.
+    /// </summary>
+    internal sealed record RunAllResult(
+        ConcurrentDictionary<string, VerificationResult> Results,
+        List<(string Name, string Reason)> Skipped,
+        List<string> SampleOrder);
+
+    /// <summary>
+    /// Filters samples, runs the runnable ones in parallel, and returns all results.
+    /// </summary>
+    public async Task<RunAllResult> RunAllAsync(
+        IReadOnlyList<SampleDefinition> samples,
+        int maxParallelism)
+    {
+        var skipped = new List<(string Name, string Reason)>();
+        var runnableSamples = new List<SampleDefinition>();
+        var sampleOrder = new List<string>();
+
+        // Separate samples into skipped and runnable
+        foreach (var sample in samples)
+        {
+            sampleOrder.Add(sample.Name);
+
+            if (sample.SkipReason is not null)
+            {
+                skipped.Add((sample.Name, sample.SkipReason));
+                this._reporter.WriteLineWithPrefix(sample.Name, $"SKIPPED — {sample.SkipReason}", ConsoleColor.Yellow);
+
+                if (this._logWriter is not null)
+                {
+                    await this._logWriter.WriteSkippedAsync(sample.Name, sample.SkipReason);
+                }
+
+                continue;
+            }
+
+            var missingRequired = sample.RequiredEnvironmentVariables
+                .Where(v => string.IsNullOrEmpty(Environment.GetEnvironmentVariable(v)))
+                .ToList();
+
+            var missingOptional = sample.OptionalEnvironmentVariables
+                .Where(v => string.IsNullOrEmpty(Environment.GetEnvironmentVariable(v)))
+                .ToList();
+
+            if (missingRequired.Count > 0 || missingOptional.Count > 0)
+            {
+                var reasons = new List<string>();
+                if (missingRequired.Count > 0)
+                {
+                    reasons.Add($"Missing required: {string.Join(", ", missingRequired)}");
+                }
+
+                if (missingOptional.Count > 0)
+                {
+                    reasons.Add($"Missing optional (would cause console prompt hang): {string.Join(", ", missingOptional)}");
+                }
+
+                var skipReason = string.Join("; ", reasons);
+                skipped.Add((sample.Name, skipReason));
+                this._reporter.WriteLineWithPrefix(sample.Name, $"SKIPPED — {skipReason}", ConsoleColor.Yellow);
+
+                if (this._logWriter is not null)
+                {
+                    await this._logWriter.WriteSkippedAsync(sample.Name, skipReason);
+                }
+
+                continue;
+            }
+
+            runnableSamples.Add(sample);
+        }
+
+        // Run samples in parallel
+        var results = new ConcurrentDictionary<string, VerificationResult>();
+        var semaphore = new SemaphoreSlim(maxParallelism);
+
+        this._reporter.WriteLineWithPrefix(
+            "runner", $"Running {runnableSamples.Count} samples (max {maxParallelism} parallel)...");
+
+        try
+        {
+            var tasks = runnableSamples.Select(sample => this.RunSingleAsync(sample, results, semaphore)).ToArray();
+            await Task.WhenAll(tasks);
+        }
+        finally
+        {
+            semaphore.Dispose();
+        }
+
+        return new RunAllResult(results, skipped, sampleOrder);
+    }
+
+    private async Task RunSingleAsync(
+        SampleDefinition sample,
+        ConcurrentDictionary<string, VerificationResult> results,
+        SemaphoreSlim semaphore)
+    {
+        await semaphore.WaitAsync();
+        try
+        {
+            var log = new List<string>();
+            log.Add($"[{sample.Name}] Running...");
+            this._reporter.WriteLineWithPrefix(sample.Name, "Running...");
+
+            var projectPath = Path.Combine(this._dotnetRoot, sample.ProjectPath);
+            var run = sample.Inputs.Length > 0
+                ? await SampleRunner.RunAsync(projectPath, this._timeout, sample.Inputs, sample.InputDelayMs)
+                : await SampleRunner.RunAsync(projectPath, this._timeout);
+
+            log.Add($"[{sample.Name}] Completed ({run.Elapsed.TotalSeconds:F1}s, exit={run.ExitCode})");
+            this._reporter.WriteLineWithPrefix(
+                sample.Name, $"Completed ({run.Elapsed.TotalSeconds:F1}s, exit={run.ExitCode}). Verifying...");
+
+            var result = await this._verifier.VerifyAsync(sample, run);
+
+            if (result.Passed)
+            {
+                log.Add($"[{sample.Name}] PASSED");
+                this._reporter.WriteLineWithPrefix(sample.Name, "PASSED", ConsoleColor.Green);
+            }
+            else
+            {
+                log.Add($"[{sample.Name}] FAILED");
+                this._reporter.WriteLineWithPrefix(sample.Name, "FAILED", ConsoleColor.Red);
+                foreach (var failure in result.Failures)
+                {
+                    log.Add($"[{sample.Name}]   ✗ {failure}");
+                    this._reporter.WriteLineWithPrefix(sample.Name, $"  ✗ {failure}", ConsoleColor.Red);
+                }
+            }
+
+            if (result.AIReasoning is not null)
+            {
+                log.Add($"[{sample.Name}]   AI: {result.AIReasoning}");
+                this._reporter.WriteLineWithPrefix(
+                    sample.Name, $"  AI: {Truncate(result.AIReasoning, 300)}", ConsoleColor.DarkGray);
+            }
+
+            var verificationResult = new VerificationResult
+            {
+                SampleName = result.SampleName,
+                Passed = result.Passed,
+                Summary = result.Summary,
+                Failures = result.Failures,
+                AIReasoning = result.AIReasoning,
+                Stdout = run.Stdout,
+                Stderr = run.Stderr,
+                LogLines = log,
+            };
+            results[sample.Name] = verificationResult;
+
+            if (this._logWriter is not null)
+            {
+                await this._logWriter.WriteSampleResultAsync(verificationResult);
+            }
+        }
+        finally
+        {
+            semaphore.Release();
+        }
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : text[..maxLength] + "...";
+}
@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// The result of verifying a single sample.
+/// </summary>
+internal sealed class VerificationResult
+{
+    public required string SampleName { get; init; }
+    public required bool Passed { get; init; }
+    public required string Summary { get; init; }
+    public List<string> Failures { get; init; } = [];
+    public string? AIReasoning { get; init; }
+
+    /// <summary>
+    /// The sample's stdout output, captured for log file output.
+    /// </summary>
+    public string? Stdout { get; init; }
+
+    /// <summary>
+    /// The sample's stderr output, captured for log file output.
+    /// </summary>
+    public string? Stderr { get; init; }
+
+    /// <summary>
+    /// Per-sample log lines, buffered during parallel execution
+    /// and written sequentially to the log file.
+    /// </summary>
+    public List<string> LogLines { get; init; } = [];
+}
@@ -0,0 +1,124 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Parsed command-line options for the sample verification tool.
+/// </summary>
+internal sealed class VerifyOptions
+{
+    /// <summary>
+    /// Maximum number of samples to run concurrently.
+    /// </summary>
+    public int MaxParallelism { get; init; } = 8;
+
+    /// <summary>
+    /// Path to write a CSV summary file, or <c>null</c> to skip.
+    /// </summary>
+    public string? CsvFilePath { get; init; }
+
+    /// <summary>
+    /// Path to write a sequential log file, or <c>null</c> to skip.
+    /// </summary>
+    public string? LogFilePath { get; init; }
+
+    /// <summary>
+    /// The filtered list of samples to process.
+    /// </summary>
+    public required IReadOnlyList<SampleDefinition> Samples { get; init; }
+
+    /// <summary>
+    /// All known sample set registries, keyed by category name.
+    /// </summary>
+    private static readonly Dictionary<string, IReadOnlyList<SampleDefinition>> s_sampleSets =
+        new(StringComparer.OrdinalIgnoreCase)
+        {
+            ["01-get-started"] = GetStartedSamples.All,
+            ["02-agents"] = AgentsSamples.All,
+            ["03-workflows"] = WorkflowSamples.All,
+        };
+
+    /// <summary>
+    /// Parses command-line arguments and resolves the sample list.
+    /// Returns <c>null</c> and writes to stderr if the arguments are invalid.
+    /// </summary>
+    public static VerifyOptions? Parse(string[] args)
+    {
+        var argList = args.ToList();
+
+        var categoryFilter = ExtractArg(argList, "--category");
+        var logFilePath = ExtractArg(argList, "--log");
+        var csvFilePath = ExtractArg(argList, "--csv");
+
+        int maxParallelism = 8;
+        var parallelArg = ExtractArg(argList, "--parallel");
+        if (parallelArg is not null && int.TryParse(parallelArg, out var p) && p > 0)
+        {
+            maxParallelism = p;
+        }
+
+        HashSet<string>? nameFilter = null;
+        if (argList.Count > 0)
+        {
+            nameFilter = argList.ToHashSet(StringComparer.OrdinalIgnoreCase);
+        }
+
+        // Build the sample list
+        IReadOnlyList<SampleDefinition> samples;
+        if (categoryFilter is not null)
+        {
+            if (!s_sampleSets.TryGetValue(categoryFilter, out var categoryList))
+            {
+                Console.Error.WriteLine(
+                    $"Unknown category '{categoryFilter}'. Available: {string.Join(", ", s_sampleSets.Keys)}");
+                return null;
+            }
+
+            samples = categoryList;
+        }
+        else
+        {
+            samples = s_sampleSets.Values.SelectMany(s => s).ToList();
+        }
+
+        if (nameFilter is not null)
+        {
+            samples = samples.Where(s => nameFilter.Contains(s.Name)).ToList();
+        }
+
+        if (samples.Count == 0)
+        {
+            var allNames = s_sampleSets.Values.SelectMany(s => s).Select(s => s.Name);
+            Console.Error.WriteLine($"No matching samples found. Available: {string.Join(", ", allNames)}");
+            return null;
+        }
+
+        return new VerifyOptions
+        {
+            MaxParallelism = maxParallelism,
+            LogFilePath = logFilePath,
+            CsvFilePath = csvFilePath,
+            Samples = samples,
+        };
+    }
+
+    private static string? ExtractArg(List<string> list, string flag)
+    {
+        var idx = list.IndexOf(flag);
+        if (idx < 0)
+        {
+            return null;
+        }
+
+        if (idx + 1 >= list.Count)
+        {
+            Console.Error.WriteLine($"Missing value for {flag}.");
+            list.RemoveAt(idx);
+            return null;
+        }
+
+        var value = list[idx + 1];
+        list.RemoveRange(idx, 2);
+        return value;
+    }
+}
@@ -0,0 +1,525 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Defines the expected behavior for each sample in 03-workflows.
+/// </summary>
+internal static class WorkflowSamples
+{
+    public static IReadOnlyList<SampleDefinition> All { get; } =
+    [
+        // ───────────────────────────────────────────────────────────────────
+        // _StartHere
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_01_Streaming",
+            ProjectPath = "samples/03-workflows/_StartHere/01_Streaming",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "UppercaseExecutor: HELLO, WORLD!",
+                "ReverseTextExecutor: !DLROW ,OLLEH",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_02_AgentsInWorkflows",
+            ProjectPath = "samples/03-workflows/_StartHere/02_AgentsInWorkflows",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show agent responses from a translation workflow.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_03_AgentWorkflowPatterns",
+            ProjectPath = "samples/03-workflows/_StartHere/03_AgentWorkflowPatterns",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            Inputs = ["sequential"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription =
+            [
+                "The output should show a sequential workflow pattern with multiple agents executing tasks in order.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_04_MultiModelService",
+            ProjectPath = "samples/03-workflows/_StartHere/04_MultiModelService",
+            RequiredEnvironmentVariables = ["BEDROCK_ACCESS_KEY", "BEDROCK_SECRET_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+            SkipReason = "Requires multiple external provider API keys (Bedrock, Anthropic, OpenAI).",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_05_SubWorkflows",
+            ProjectPath = "samples/03-workflows/_StartHere/05_SubWorkflows",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "=== Sub-Workflow Demonstration ===",
+                "Final Output:",
+                "=== Main Workflow Completed ===",
+                "Sample Complete: Workflows can be composed hierarchically using sub-workflows",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_06_MixedWorkflowAgentsAndExecutors",
+            ProjectPath = "samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            Inputs = ["What is 2 plus 2?"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription =
+            [
+                "The output should show agents and executors working together to process a user question.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_07_WriterCriticWorkflow",
+            ProjectPath = "samples/03-workflows/_StartHere/07_WriterCriticWorkflow",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain = ["=== Writer-Critic Iteration Workflow ==="],
+            ExpectedOutputDescription =
+            [
+                "The output should show a writer-critic iteration workflow with writer and critic sections.",
+                "The critic should either approve or request revisions.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Agents
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_CustomAgentExecutors",
+            ProjectPath = "samples/03-workflows/Agents/CustomAgentExecutors",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show custom workflow events including slogan generation and feedback.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_FoundryAgent",
+            ProjectPath = "samples/03-workflows/Agents/FoundryAgent",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            SkipReason = "Requires Azure AI Foundry project endpoint.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_GroupChatToolApproval",
+            ProjectPath = "samples/03-workflows/Agents/GroupChatToolApproval",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain = ["Starting group chat workflow for software deployment..."],
+            ExpectedOutputDescription =
+            [
+                "The output should show a group chat workflow with QA and DevOps agents for software deployment.",
+                "There should be approval requests for tool calls.",
+                "The workflow should show interaction between QA and DevOps agents toward deployment.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_WorkflowAsAnAgent",
+            ProjectPath = "samples/03-workflows/Agents/WorkflowAsAnAgent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            Inputs = ["hello", "exit"],
+            InputDelayMs = 5000,
+            ExpectedOutputDescription =
+            [
+                "The output should show a conversational workflow responding to the user's hello message.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Checkpoint
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Checkpoint_CheckpointAndRehydrate",
+            ProjectPath = "samples/03-workflows/Checkpoint/CheckpointAndRehydrate",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Workflow completed with result:",
+                "Number of checkpoints created:",
+                "Hydrating a new workflow instance from the 6th checkpoint.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Checkpoint_CheckpointAndResume",
+            ProjectPath = "samples/03-workflows/Checkpoint/CheckpointAndResume",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Workflow completed with result:",
+                "Number of checkpoints created:",
+                "Restoring from the 6th checkpoint.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Checkpoint_CheckpointWithHumanInTheLoop",
+            ProjectPath = "samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop",
+            RequiredEnvironmentVariables = [],
+            Inputs = ["50", "25", "40", "45", "42", "50", "25", "40", "45", "42"],
+            InputDelayMs = 1000,
+            MustContain = ["found in"],
+            ExpectedOutputDescription =
+            [
+                "The output should show a number guessing game with higher/lower hints that eventually reaches the correct number.",
+                "The output should demonstrate checkpoint save and restore behavior.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Concurrent
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Concurrent_Concurrent",
+            ProjectPath = "samples/03-workflows/Concurrent/Concurrent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show results from concurrent agent processing.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Concurrent_MapReduce",
+            ProjectPath = "samples/03-workflows/Concurrent/MapReduce",
+            RequiredEnvironmentVariables = [],
+            MustContain =
+            [
+                "=== RUNNING WORKFLOW ===",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // ConditionalEdges
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_ConditionalEdges_01_EdgeCondition",
+            ProjectPath = "samples/03-workflows/ConditionalEdges/01_EdgeCondition",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show an email being classified as spam or not spam and processed accordingly.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_ConditionalEdges_02_SwitchCase",
+            ProjectPath = "samples/03-workflows/ConditionalEdges/02_SwitchCase",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show an ambiguous email being classified as spam, not spam, or uncertain.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_ConditionalEdges_03_MultiSelection",
+            ProjectPath = "samples/03-workflows/ConditionalEdges/03_MultiSelection",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show an email being classified and potentially routed to multiple handlers.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // HumanInTheLoop
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_HumanInTheLoop_Basic",
+            ProjectPath = "samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic",
+            RequiredEnvironmentVariables = [],
+            Inputs = ["50", "25", "40", "45", "42"],
+            InputDelayMs = 1000,
+            MustContain = ["found in"],
+            ExpectedOutputDescription =
+            [
+                "The output should show a number guessing game with higher/lower hints that eventually reaches the correct number 42.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Loop
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Loop",
+            ProjectPath = "samples/03-workflows/Loop",
+            RequiredEnvironmentVariables = [],
+            MustContain = ["Result:"],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // SharedStates
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_SharedStates",
+            ProjectPath = "samples/03-workflows/SharedStates",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Total Paragraphs:",
+                "Total Words:",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Visualization
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Visualization",
+            ProjectPath = "samples/03-workflows/Visualization",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Generating workflow visualization...",
+                "Mermaid string:",
+                "DiGraph string:",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Observability
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Observability_ApplicationInsights",
+            ProjectPath = "samples/03-workflows/Observability/ApplicationInsights",
+            RequiredEnvironmentVariables = ["APPLICATIONINSIGHTS_CONNECTION_STRING"],
+            SkipReason = "Requires Application Insights connection string.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Observability_AspireDashboard",
+            ProjectPath = "samples/03-workflows/Observability/AspireDashboard",
+            RequiredEnvironmentVariables = [],
+            SkipReason = "Requires Aspire Dashboard / OTLP endpoint.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Observability_WorkflowAsAnAgent",
+            ProjectPath = "samples/03-workflows/Observability/WorkflowAsAnAgent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            SkipReason = "Interactive console with ReadLine loop; requires OTLP endpoint.",
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Declarative
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ConfirmInput",
+            ProjectPath = "samples/03-workflows/Declarative/ConfirmInput",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            Inputs = ["hello", "hello"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a confirmation prompt and a user response."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_CustomerSupport",
+            ProjectPath = "samples/03-workflows/Declarative/CustomerSupport",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["My laptop won't start"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a customer support workflow processing a laptop issue, with agent responses providing troubleshooting or support."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_DeepResearch",
+            ProjectPath = "samples/03-workflows/Declarative/DeepResearch",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            SkipReason = "Requires external weather API (wttr.in).",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ExecuteCode",
+            ProjectPath = "samples/03-workflows/Declarative/ExecuteCode",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            Inputs = ["What is 12 * 34?"],
+            InputDelayMs = 5000,
+            ExpectedOutputDescription = ["The output should show a declarative workflow executing generated code, processing a math question and producing a result."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ExecuteWorkflow",
+            ProjectPath = "samples/03-workflows/Declarative/ExecuteWorkflow",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            SkipReason = "Requires a workflow file path as a CLI argument.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_FunctionTools",
+            ProjectPath = "samples/03-workflows/Declarative/FunctionTools",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["What are today's specials?", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow calling function tools (e.g. a menu plugin) to answer a question about restaurant specials."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_GenerateCode",
+            ProjectPath = "samples/03-workflows/Declarative/GenerateCode",
+            IsDeterministic = true,
+            MustContain = ["WORKFLOW: Parsing", "WORKFLOW: Defined"],
+            ExpectedOutputDescription = ["The output should show a YAML workflow being parsed and C# code being generated from it."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_HostedWorkflow",
+            ProjectPath = "samples/03-workflows/Declarative/HostedWorkflow",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            SkipReason = "Hosts a persistent workflow server that does not exit.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InputArguments",
+            ProjectPath = "samples/03-workflows/Declarative/InputArguments",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["I'd like to visit Seattle", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow capturing location input and providing travel-related information about Seattle."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InvokeFunctionTool",
+            ProjectPath = "samples/03-workflows/Declarative/InvokeFunctionTool",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["What's the soup of the day?", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow invoking a function tool (e.g. a menu plugin) to answer a question about the soup of the day."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InvokeMcpTool",
+            ProjectPath = "samples/03-workflows/Declarative/InvokeMcpTool",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["Search for .NET tutorials on Microsoft Learn"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a workflow using MCP tools to search Microsoft Learn documentation and provide a summary of results."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_Marketing",
+            ProjectPath = "samples/03-workflows/Declarative/Marketing",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["A smart water bottle that tracks hydration"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a marketing workflow generating content about a smart water bottle product."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_StudentTeacher",
+            ProjectPath = "samples/03-workflows/Declarative/StudentTeacher",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["What is 18 + 27?"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a student-teacher workflow where a student asks a math question and a teacher provides the answer."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ToolApproval",
+            ProjectPath = "samples/03-workflows/Declarative/ToolApproval",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["Search for .NET tutorials", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow using an MCP tool with approval to search Microsoft Learn, followed by an exit from the input loop."],
+        },
+    ];
+}
@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <IsAotCompatible>false</IsAotCompatible>
+    <!-- This is a top-level console app; ConfigureAwait is unnecessary -->
+    <NoWarn>$(NoWarn);CA2007</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -2,11 +2,11 @@
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
    <VersionPrefix>1.0.0</VersionPrefix>
-    <RCNumber>4</RCNumber>
+    <RCNumber>5</RCNumber>
    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260311.1</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260311.1</PackageVersion>
-    <GitTag>1.0.0-rc4</GitTag>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260330.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260330.1</PackageVersion>
+    <GitTag>1.0.0-rc5</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -5,8 +5,8 @@ This sample demonstrates how to create an AIAgent using Anthropic Claude models
 The sample supports three deployment scenarios:

 1. **Anthropic Public API** - Direct connection to Anthropic's public API
-2. **Azure Foundry with API Key** - Anthropic models deployed through Azure Foundry using API key authentication
-3. **Azure Foundry with Azure CLI** - Anthropic models deployed through Azure Foundry using Azure CLI credentials
+2. **Microsoft Foundry with API Key** - Anthropic models deployed through Microsoft Foundry using API key authentication
+3. **Microsoft Foundry with Azure CLI** - Anthropic models deployed through Microsoft Foundry using Azure CLI credentials

 ## Prerequisites

@@ -25,29 +25,29 @@ $env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic A
 $env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```

-### For Azure Foundry with API Key
+### For Microsoft Foundry with API Key

- Azure Foundry service endpoint and deployment configured
+- Microsoft Foundry service endpoint and deployment configured
 - Anthropic API key

 Set the following environment variables:

 ```powershell
-$env:ANTHROPIC_RESOURCE="your-foundry-resource-name"  # Replace with your Azure Foundry resource name (subdomain before .services.ai.azure.com)
+$env:ANTHROPIC_RESOURCE="your-foundry-resource-name"  # Replace with your Microsoft Foundry resource name (subdomain before .services.ai.azure.com)
 $env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
 $env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```

-### For Azure Foundry with Azure CLI
+### For Microsoft Foundry with Azure CLI

- Azure Foundry service endpoint and deployment configured
+- Microsoft Foundry service endpoint and deployment configured
 - Azure CLI installed and authenticated (for Azure credential authentication)

 Set the following environment variables:

 ```powershell
-$env:ANTHROPIC_RESOURCE="your-foundry-resource-name"  # Replace with your Azure Foundry resource name (subdomain before .services.ai.azure.com)
+$env:ANTHROPIC_RESOURCE="your-foundry-resource-name"  # Replace with your Microsoft Foundry resource name (subdomain before .services.ai.azure.com)
 $env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```

-**Note**: When using Azure Foundry with Azure CLI, make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+**Note**: When using Microsoft Foundry with Azure CLI, make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
@@ -2,7 +2,7 @@

 #pragma warning disable CS0618 // Type or member is obsolete - sample uses deprecated PersistentAgentsClientExtensions

-// This sample shows how to create and use a simple AI agent with Azure Foundry Agents as the backend.
+// This sample shows how to create and use a simple AI agent with Microsoft Foundry Agents as the backend.

 using Azure.AI.Agents.Persistent;
 using Azure.Identity;
@@ -13,14 +13,14 @@ Below is a comparison between the classic and new Foundry Agents approaches:
 Before you begin, ensure you have the following prerequisites:

 - .NET 10 SDK or later
- Azure Foundry service endpoint and deployment configured
+- Microsoft Foundry service endpoint and deployment configured
 - Azure CLI installed and authenticated (for Azure credential authentication)

-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

 Set the following environment variables:

 ```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Microsoft Foundry resource endpoint
 $env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```
@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

-// This sample shows how to create and use a AI agents with Azure Foundry Agents as the backend.
+// This sample shows how to create and use AI agents with Microsoft Foundry Agents as the backend.

 using Azure.AI.Projects;
 using Azure.AI.Projects.Agents;
@@ -13,7 +13,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYME

 const string JokerName = "JokerAgent";

-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
+// Get a client to create/retrieve/delete server side agents with Microsoft Foundry Agents.
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
@@ -13,14 +13,14 @@ Below is a comparison between the classic and new Foundry Agents approaches:
 Before you begin, ensure you have the following prerequisites:

 - .NET 10 SDK or later
- Azure Foundry service endpoint and deployment configured
+- Microsoft Foundry service endpoint and deployment configured
 - Azure CLI installed and authenticated (for Azure credential authentication)

-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

 Set the following environment variables:

 ```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Microsoft Foundry resource endpoint
 $env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

-// This sample shows how to use the OpenAI SDK to create and use a simple AI agent with any model hosted in Azure AI Foundry.
-// You could use models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, xAI or any other model you have deployed in your Azure AI Foundry resource.
+// This sample shows how to use the OpenAI SDK to create and use a simple AI agent with any model hosted in Microsoft Foundry.
+// You could use models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, xAI or any other model you have deployed in your Microsoft Foundry resource.
 // Note: Ensure that you pick a model that suits your needs. For example, if you want to use function calling, ensure that the model you pick supports function calling.

 using System.ClientModel;
@@ -15,7 +15,7 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
 var model = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "Phi-4-mini-instruct";

-// Since we are using the OpenAI Client SDK, we need to override the default endpoint to point to Azure Foundry.
+// Since we are using the OpenAI Client SDK, we need to override the default endpoint to point to Microsoft Foundry.
 var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(endpoint) };

 // Create the OpenAI client with either an API key or Azure CLI credential.
@@ -1,8 +1,8 @@
 ## Overview

-This sample shows how to use the OpenAI SDK to create and use a simple AI agent with any model hosted in Azure AI Foundry.
+This sample shows how to use the OpenAI SDK to create and use a simple AI agent with any model hosted in Microsoft Foundry.

-You could use models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, xAI or any other model you have deployed in Azure AI Foundry.
+You could use models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, xAI or any other model you have deployed in Microsoft Foundry.

 **Note**: Ensure that you pick a model that suits your needs. For example, if you want to use function calling, ensure that the model you pick supports function calling.

@@ -11,19 +11,19 @@ You could use models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, xAI o
 Before you begin, ensure you have the following prerequisites:

 - .NET 10 SDK or later
- Azure AI Foundry resource
- A model deployment in your Azure AI Foundry resource. This example defaults to using the `Phi-4-mini-instruct` model,
+- Microsoft Foundry resource
+- A model deployment in your Microsoft Foundry resource. This example defaults to using the `Phi-4-mini-instruct` model,
 so if you want to use a different model, ensure that you set your `AZURE_AI_MODEL_DEPLOYMENT_NAME` environment
 variable to the name of your deployed model.
- An API key or role based authentication to access the Azure AI Foundry resource
+- An API key or role based authentication to access the Microsoft Foundry resource

 See [here](https://learn.microsoft.com/en-us/azure/ai-foundry/quickstarts/get-started-code?tabs=csharp) for more info on setting up these prerequisites

 Set the following environment variables:

 ```powershell
-# Replace with your Azure AI Foundry resource endpoint
-# Ensure that you have the "/openai/v1/" path in the URL, since this is required when using the OpenAI SDK to access Azure Foundry models.
+# Replace with your Microsoft Foundry resource endpoint
+# Ensure that you have the "/openai/v1/" path in the URL, since this is required when using the OpenAI SDK to access Microsoft Foundry models.
 $env:AZURE_OPENAI_ENDPOINT="https://ai-foundry-<myresourcename>.services.ai.azure.com/openai/v1/"

 # Optional, defaults to using Azure CLI for authentication if not provided
@@ -18,7 +18,7 @@ See the README.md for each sample for the prerequisites for that sample.
 |[Creating an AIAgent with Anthropic](./Agent_With_Anthropic/)|This sample demonstrates how to create an AIAgent using Anthropic Claude models as the underlying inference service|
 |[Creating an AIAgent with Foundry Agents using Azure.AI.Agents.Persistent](./Agent_With_AzureAIAgentsPersistent/)|This sample demonstrates how to create a Foundry Persistent agent and expose it as an AIAgent using the Azure.AI.Agents.Persistent SDK|
 |[Creating an AIAgent with Foundry Agents using Azure.AI.Project](./Agent_With_AzureAIProject/)|This sample demonstrates how to create an Foundry Project agent and expose it as an AIAgent using the Azure.AI.Project SDK|
-|[Creating an AIAgent with AzureFoundry Model](./Agent_With_AzureFoundryModel/)|This sample demonstrates how to use any model deployed to Azure Foundry to create an AIAgent|
+|[Creating an AIAgent with Foundry Model](./Agent_With_AzureFoundryModel/)|This sample demonstrates how to use any model deployed to Microsoft Foundry to create an AIAgent|
 |[Creating an AIAgent with Azure OpenAI ChatCompletion](./Agent_With_AzureOpenAIChatCompletion/)|This sample demonstrates how to create an AIAgent using Azure OpenAI ChatCompletion as the underlying inference service|
 |[Creating an AIAgent with Azure OpenAI Responses](./Agent_With_AzureOpenAIResponses/)|This sample demonstrates how to create an AIAgent using Azure OpenAI Responses as the underlying inference service|
 |[Creating an AIAgent with a custom implementation](./Agent_With_CustomImplementation/)|This sample demonstrates how to create an AIAgent with a custom implementation|
@@ -18,9 +18,9 @@ Before you begin, ensure you have the following prerequisites:

 **Note**: These samples use Anthropic Claude models. For more information, see [Anthropic documentation](https://docs.anthropic.com/).

-## Using Anthropic with Azure Foundry
+## Using Anthropic with Microsoft Foundry

-To use Anthropic with Azure Foundry, you can check the sample [AgentProviders/Agent_With_Anthropic](../AgentProviders/Agent_With_Anthropic/README.md) for more details.
+To use Anthropic with Microsoft Foundry, you can check the sample [AgentProviders/Agent_With_Anthropic](../AgentProviders/Agent_With_Anthropic/README.md) for more details.

 ## Samples

@@ -1,10 +1,10 @@
 // Copyright (c) Microsoft. All rights reserved.

 // This sample shows how to use the FoundryMemoryProvider to persist and recall memories for an agent.
-// The sample stores conversation messages in an Azure AI Foundry memory store and retrieves relevant
+// The sample stores conversation messages in a Microsoft Foundry memory store and retrieves relevant
 // memories for subsequent invocations, even across new sessions.
 //
-// Note: Memory extraction in Azure AI Foundry is asynchronous and takes time. This sample demonstrates
+// Note: Memory extraction in Microsoft Foundry is asynchronous and takes time. This sample demonstrates
 // a simple polling approach to wait for memory updates to complete before querying.

 using System.Text.Json;
@@ -62,7 +62,7 @@ await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
 Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
 Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));

-// Memory extraction in Azure AI Foundry is asynchronous and takes time to process.
+// Memory extraction in Microsoft Foundry is asynchronous and takes time to process.
 // WhenUpdatesCompletedAsync polls all pending updates and waits for them to complete.
 Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
 await memoryProvider.WhenUpdatesCompletedAsync();
@@ -1,6 +1,6 @@
-# Agent with Memory Using Azure AI Foundry
+# Agent with Memory Using Microsoft Foundry

-This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories across sessions.
+This sample demonstrates how to create and run an agent that uses Microsoft Foundry's managed memory service to extract and retrieve individual memories across sessions.

 ## Features Demonstrated

@@ -13,7 +13,7 @@ This sample demonstrates how to create and run an agent that uses Azure AI Found

 ## Prerequisites

-1. Azure subscription with Azure AI Foundry project
+1. Azure subscription with Microsoft Foundry project
 2. Azure OpenAI resource with a chat model deployment (e.g., gpt-4o-mini) and an embedding model deployment (e.g., text-embedding-ada-002)
 3. .NET 10.0 SDK
 4. Azure CLI logged in (`az login`)
@@ -21,7 +21,7 @@ This sample demonstrates how to create and run an agent that uses Azure AI Found
 ## Environment Variables

 ```bash
-# Azure AI Foundry project endpoint and memory store name
+# Microsoft Foundry project endpoint and memory store name
 export AZURE_AI_PROJECT_ENDPOINT="https://your-account.services.ai.azure.com/api/projects/your-project"
 export AZURE_AI_MEMORY_STORE_ID="my_memory_store"

@@ -48,10 +48,10 @@ The agent will:

 ## Key Differences from Mem0

-| Aspect | Mem0 | Azure AI Foundry Memory |
+| Aspect | Mem0 | Microsoft Foundry Memory |
 |--------|------|------------------------|
 | Authentication | API Key | Azure Identity (DefaultAzureCredential) |
 | Scope | ApplicationId, UserId, AgentId, ThreadId | Single `Scope` string |
 | Memory Types | Single memory store | User Profile + Chat Summary |
-| Hosting | Mem0 cloud or self-hosted | Azure AI Foundry managed service |
+| Hosting | Mem0 cloud or self-hosted | Microsoft Foundry managed service |
 | Store Creation | N/A (automatic) | Explicit via `EnsureMemoryStoreCreatedAsync` |
@@ -7,7 +7,7 @@ These samples show how to create an agent with the Agent Framework that uses Mem
 |[Chat History memory](./AgentWithMemory_Step01_ChatHistoryMemory/)|This sample demonstrates how to enable an agent to remember messages from previous conversations.|
 |[Memory with MemoryStore](./AgentWithMemory_Step02_MemoryUsingMem0/)|This sample demonstrates how to create and run an agent that uses the Mem0 service to extract and retrieve individual memories.|
 |[Custom Memory Implementation](../../01-get-started/04_memory/)|This sample demonstrates how to create a custom memory component and attach it to an agent.|
-|[Memory with Azure AI Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories.|
+|[Memory with Microsoft Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Microsoft Foundry's managed memory service to extract and retrieve individual memories.|
 |[Bounded Chat History with Overflow](./AgentWithMemory_Step05_BoundedChatHistory/)|This sample demonstrates how to create a bounded chat history provider that overflows older messages to a vector store and recalls them as memories.|

-> **See also**: [Memory Search with Foundry Agents](../AgentsWithFoundry/Agent_Step22_MemorySearch/) - demonstrates using the built-in Memory Search tool with Azure Foundry agents.
+> **See also**: [Memory Search with Foundry Agents](../AgentsWithFoundry/Agent_Step22_MemorySearch/) - demonstrates using the built-in Memory Search tool with Microsoft Foundry agents.
@@ -13,7 +13,7 @@ This sample uses Qdrant for the vector store, but this can easily be swapped out
 - User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource.
 - An existing Qdrant instance. You can use a managed service or run a local instance using Docker, but the sample assumes the instance is running locally.

-**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).

 **Note**: These samples use Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

@@ -0,0 +1,54 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Remove="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Remove="Microsoft.VisualStudio.Threading.Analyzers" />
+    <PackageReference Remove="xunit.analyzers" />
+    <PackageReference Remove="Moq.Analyzers" />
+    <PackageReference Remove="Roslynator.Analyzers" />
+    <PackageReference Remove="Roslynator.CodeAnalysis.Analyzers" />
+    <PackageReference Remove="Roslynator.Formatting.Analyzers" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
+    <PackageReference Include="Azure.Identity" Version="1.19.0" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-rc4" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.4.0" />
+    <PackageReference Include="Neo4j.AgentFramework.GraphRAG" Version="0.1.0-preview.2" />
+    <PackageReference Include="Neo4j.Driver" Version="5.28.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.CodeAnalysis.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Formatting.Analyzers" Version="4.14.1">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Neo4j.AgentFramework.GraphRAG;
+using Neo4j.Driver;
+
+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";
+var neo4jUri = Environment.GetEnvironmentVariable("NEO4J_URI") ?? throw new InvalidOperationException("NEO4J_URI is not set.");
+var neo4jUsername = Environment.GetEnvironmentVariable("NEO4J_USERNAME") ?? "neo4j";
+var neo4jPassword = Environment.GetEnvironmentVariable("NEO4J_PASSWORD") ?? throw new InvalidOperationException("NEO4J_PASSWORD is not set.");
+var fulltextIndex = Environment.GetEnvironmentVariable("NEO4J_FULLTEXT_INDEX_NAME") ?? "search_chunks";
+
+const string RetrievalQuery = """
+    MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)<-[:FILED]-(company:Company)
+    OPTIONAL MATCH (company)-[:FACES_RISK]->(risk:RiskFactor)
+    WITH node, score, company, doc, collect(DISTINCT risk.name)[0..5] AS risks
+    OPTIONAL MATCH (company)-[:MENTIONS]->(product:Product)
+    WITH node, score, company, doc, risks, collect(DISTINCT product.name)[0..5] AS products
+    RETURN
+        node.text AS text,
+        score,
+        company.name AS company,
+        company.ticker AS ticker,
+        doc.title AS title,
+        risks,
+        products
+    ORDER BY score DESC
+    """;
+
+await using var driver = GraphDatabase.Driver(new Uri(neo4jUri), AuthTokens.Basic(neo4jUsername, neo4jPassword));
+await driver.VerifyConnectivityAsync();
+
+await using var provider = new Neo4jContextProvider(
+    driver,
+    new Neo4jContextProviderOptions
+    {
+        IndexName = fulltextIndex,
+        IndexType = IndexType.Fulltext,
+        RetrievalQuery = RetrievalQuery,
+        TopK = 5,
+        ContextPrompt = "Use the retrieved Neo4j graph context to answer accurately and call out when context is missing."
+    });
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsIChatClient()
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant that answers questions using Neo4j graph context."
+        },
+        AIContextProviders = [provider]
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+foreach (var question in new[]
+{
+    "What products does Microsoft offer?",
+    "What risks does Apple face?",
+    "Tell me about NVIDIA's AI business and risk factors."
+})
+{
+    Console.WriteLine($">> {question}\n");
+    Console.WriteLine(await agent.RunAsync(question, session));
+    Console.WriteLine();
+}
@@ -0,0 +1,32 @@
+# Agent Framework Retrieval Augmented Generation (RAG) with Neo4j GraphRAG
+
+This sample demonstrates how to create and run an agent that uses the [Neo4j GraphRAG context provider](https://github.com/neo4j-labs/neo4j-maf-provider) with Microsoft Agent Framework for .NET.
+
+The sample uses a Neo4j fulltext index for retrieval and a Cypher `RetrievalQuery` to enrich results with related companies, products, and risk factors.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI endpoint and chat deployment
+- Azure CLI installed and authenticated
+- A Neo4j database with chunked documents and a fulltext index such as `search_chunks`
+
+## Environment variables
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+$env:NEO4J_URI="neo4j+s://your-instance.databases.neo4j.io"
+$env:NEO4J_USERNAME="neo4j"
+$env:NEO4J_PASSWORD="your-password"
+$env:NEO4J_FULLTEXT_INDEX_NAME="search_chunks"
+```
+
+## Build and run
+
+```powershell
+dotnet build
+dotnet run --framework net10.0 --no-build
+```
+
+The sample issues a few questions against the graph-backed retrieval provider and prints the responses to the console.
@@ -8,3 +8,4 @@ These samples show how to create an agent with the Agent Framework that uses Ret
 |[RAG with Vector Store and custom schema](./AgentWithRAG_Step02_CustomVectorStoreRAG/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with a vector store. It also uses a custom schema for the documents stored in the vector store.|
 |[RAG with custom RAG data source](./AgentWithRAG_Step03_CustomRAGDataSource/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with a custom RAG data source.|
 |[RAG with Foundry VectorStore service](./AgentWithRAG_Step04_FoundryServiceRAG/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with the Foundry VectorStore service.|
+|[RAG with Neo4j GraphRAG](./AgentWithRAG_Step05_Neo4jGraphRAG/)|This sample demonstrates how to create and run an agent that uses a Neo4j-backed GraphRAG context provider with graph-enriched retrieval.|
@@ -18,7 +18,7 @@ Before you begin, ensure you have the following prerequisites:
 - Azure CLI installed and authenticated (for Azure credential authentication)
 - User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource

-**Note**: This sample uses Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+**Note**: This sample uses Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).

 **Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

@@ -20,8 +20,8 @@ To use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
   MCP Inspector is up and running at http://127.0.0.1:6274
   ```
 1. Open a web browser and navigate to the URL displayed in the terminal. If not opened automatically, this will open the MCP Inspector interface.
-1. In the MCP Inspector interface, add the following environment variables to allow your MCP server to access Azure AI Foundry Project to create and run the agent:
-    - AZURE_AI_PROJECT_ENDPOINT = https://your-resource.openai.azure.com/ # Replace with your Azure AI Foundry Project endpoint
+1. In the MCP Inspector interface, add the following environment variables to allow your MCP server to access Microsoft Foundry Project to create and run the agent:
+    - AZURE_AI_PROJECT_ENDPOINT = https://your-resource.openai.azure.com/ # Replace with your Microsoft Foundry Project endpoint
    - AZURE_AI_MODEL_DEPLOYMENT_NAME = gpt-4o-mini # Replace with your model deployment name
 1. Find and click the `Connect` button in the MCP Inspector interface to connect to the MCP server.
 1. As soon as the connection is established, open the `Tools` tab in the MCP Inspector interface and select the `Joker` tool from the list.
@@ -13,7 +13,7 @@ using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;

-// Get Azure AI Foundry configuration from environment variables
+// Get Microsoft Foundry configuration from environment variables
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";

@@ -3,7 +3,7 @@
 // This sample shows how to use a chat history reducer to keep the context within model size limits.
 // Any implementation of Microsoft.Extensions.AI.IChatReducer can be used to customize how the chat history is reduced.
 // NOTE: this feature is only supported where the chat history is stored locally, such as with OpenAI Chat Completion.
-// Where the chat history is stored server side, such as with Azure Foundry Agents, the service must manage the chat history size.
+// Where the chat history is stored server side, such as with Microsoft Foundry Agents, the service must manage the chat history size.

 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -2,7 +2,7 @@

 #pragma warning disable CS0618 // Type or member is obsolete - sample uses deprecated PersistentAgentsClientExtensions

-// This sample shows how to create an Azure AI Foundry Agent with the Deep Research Tool.
+// This sample shows how to create a Microsoft Foundry Agent with the Deep Research Tool.

 using Azure.AI.Agents.Persistent;
 using Azure.Identity;
@@ -11,10 +11,10 @@ Key features:

 Before running this sample, ensure you have:

-1. An Azure AI Foundry project set up
+1. A Microsoft Foundry project set up
 2. A deep research model deployment (e.g., o3-deep-research)
 3. A model deployment (e.g., gpt-4o)
-4. A Bing Connection configured in your Azure AI Foundry project
+4. A Bing Connection configured in your Microsoft Foundry project
 5. Azure CLI installed and authenticated

 **Important**: Please visit the following documentation for detailed setup instructions:
@@ -29,14 +29,14 @@ Pay special attention to the purple `Note` boxes in the Azure documentation.
 /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>/connections/<connection-name>
 ```

-You can find this in the Azure AI Foundry portal under **Management > Connected resources**, or retrieve it programmatically via the connections API (`.id` property).
+You can find this in the Microsoft Foundry portal under **Management > Connected resources**, or retrieve it programmatically via the connections API (`.id` property).

 ## Environment Variables

 Set the following environment variables:

 ```powershell
-# Replace with your Azure AI Foundry project endpoint
+# Replace with your Microsoft Foundry project endpoint
 $env:AZURE_AI_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/"

 # Replace with your Bing Grounding connection ID (full ARM resource URI)
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 // This sample demonstrates how the ChatClientAgent persists chat history after each individual
-// call to the AI service, using the SimulateServiceStoredChatHistory option.
+// call to the AI service, using the RequirePerServiceCallChatHistoryPersistence option.
 // When an agent uses tools, FunctionInvokingChatClient may loop multiple times
 // (service call → tool execution → service call), and intermediate messages (tool calls and
 // results) are persisted after each service call. This allows you to inspect or recover them
@@ -9,7 +9,7 @@
 // yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
 //
 // To use end-of-run persistence instead (atomic run semantics), remove the
-// SimulateServiceStoredChatHistory = true setting (or set it to false). End-of-run
+// RequirePerServiceCallChatHistoryPersistence = true setting (or set it to false). End-of-run
 // persistence is the default behavior.
 //
 // The sample runs two multi-turn conversations: one using non-streaming (RunAsync) and one
@@ -54,7 +54,7 @@ static string GetTime([Description("The city name.")] string city) =>
        _ => $"{city}: time data not available."
    };

-// Create the agent — per-service-call persistence is enabled via SimulateServiceStoredChatHistory.
+// Create the agent — per-service-call persistence is enabled via RequirePerServiceCallChatHistoryPersistence.
 // The in-memory ChatHistoryProvider is used by default when the service does not require service stored chat
 // history, so for those cases, we can inspect the chat history via session.TryGetInMemoryChatHistory().
 IChatClient chatClient = string.Equals(store, "TRUE", StringComparison.OrdinalIgnoreCase) ?
@@ -64,7 +64,7 @@ AIAgent agent = chatClient.AsAIAgent(
    new ChatClientAgentOptions
    {
        Name = "WeatherAssistant",
-        SimulateServiceStoredChatHistory = true,
+        RequirePerServiceCallChatHistoryPersistence = true,
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
@@ -1,19 +1,19 @@
 # In-Function-Loop Checkpointing

-This sample demonstrates how `ChatClientAgent` can persist chat history after each individual call to the AI service using the `SimulateServiceStoredChatHistory` option. This per-service-call persistence ensures intermediate progress is saved during the function invocation loop.
+This sample demonstrates how `ChatClientAgent` can persist chat history after each individual call to the AI service using the `RequirePerServiceCallChatHistoryPersistence` option. This per-service-call persistence ensures intermediate progress is saved during the function invocation loop.

 ## What This Sample Shows

-When an agent uses tools, the `FunctionInvokingChatClient` loops multiple times (service call → tool execution → service call → …). By enabling `SimulateServiceStoredChatHistory = true`, chat history is persisted after each service call via the `ServiceStoredSimulatingChatClient` decorator:
+When an agent uses tools, the `FunctionInvokingChatClient` loops multiple times (service call → tool execution → service call → …). By enabling `RequirePerServiceCallChatHistoryPersistence = true`, chat history is persisted after each service call via the `PerServiceCallChatHistoryPersistingChatClient` decorator:

- A `ServiceStoredSimulatingChatClient` decorator is inserted into the chat client pipeline
+- A `PerServiceCallChatHistoryPersistingChatClient` decorator is inserted into the chat client pipeline
 - Before each service call, the decorator loads history from the `ChatHistoryProvider` and prepends it to the request
 - After each service call, the decorator notifies the `ChatHistoryProvider` (and any `AIContextProvider` instances) with the new messages
 - Only **new** messages are sent to providers on each notification — messages that were already persisted in an earlier call within the same run are deduplicated automatically

-By default (without `SimulateServiceStoredChatHistory`), chat history is persisted at the end of the full agent run instead. To use per-service-call persistence, set `SimulateServiceStoredChatHistory = true` on `ChatClientAgentOptions`.
+By default (without `RequirePerServiceCallChatHistoryPersistence`), chat history is persisted at the end of the full agent run instead. To use per-service-call persistence, set `RequirePerServiceCallChatHistoryPersistence = true` on `ChatClientAgentOptions`.

-With `SimulateServiceStoredChatHistory` = true, the behavior matches that of chat history stored in the underlying AI service exactly.
+With `RequirePerServiceCallChatHistoryPersistence` = true, the behavior matches that of chat history stored in the underlying AI service exactly.

 Per-service-call persistence is useful for:
 - **Crash recovery** — if the process is interrupted mid-loop, the intermediate tool calls and results are already persisted
@@ -29,7 +29,7 @@ The sample asks the agent about the weather and time in three cities. The model
 ```
 ChatClientAgent
  └─ FunctionInvokingChatClient    (handles tool call loop)
-       └─ ServiceStoredSimulatingChatClient  (persists after each service call)
+       └─ PerServiceCallChatHistoryPersistingChatClient  (persists after each service call)
            └─ Leaf IChatClient            (Azure OpenAI)
 ```

@@ -18,7 +18,7 @@ Before you begin, ensure you have the following prerequisites:
 - Azure CLI installed and authenticated (for Azure credential authentication)
 - User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource.

-**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).

 **Note**: These samples use Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 // This sample shows how to create, use, and clean up a FoundryAgent backed by a server-side
-// versioned agent in Azure AI Foundry. It demonstrates the full lifecycle:
+// versioned agent in Microsoft Foundry. It demonstrates the full lifecycle:
 // create agent version -> wrap as FoundryAgent -> run -> delete.

 using Azure.AI.Projects;
@@ -1,6 +1,6 @@
 # Getting started with Foundry Agents

-These samples demonstrate how to use Azure AI Foundry with Agent Framework.
+These samples demonstrate how to use Microsoft Foundry with Agent Framework.

 ## Quick start

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

-// This sample shows how to create and use a simple AI agent with Azure Foundry Agents as the backend, that uses a Hosted MCP Tool.
-// In this case the Azure Foundry Agents service will invoke any MCP tools as required. MCP tools are not invoked by the Agent Framework.
+// This sample shows how to create and use a simple AI agent with Microsoft Foundry Agents as the backend, that uses a Hosted MCP Tool.
+// In this case the Microsoft Foundry Agents service will invoke any MCP tools as required. MCP tools are not invoked by the Agent Framework.
 // The sample first shows how to use MCP tools with auto approval, and then how to set up a tool that requires approval before it can be invoked and how to approve such a tool.

 using Azure.AI.Projects;
@@ -3,14 +3,14 @@
 Before you begin, ensure you have the following prerequisites:

 - .NET 10 SDK or later
- Azure Foundry service endpoint and deployment configured
+- Microsoft Foundry service endpoint and deployment configured
 - Azure CLI installed and authenticated (for Azure credential authentication)

-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

 Set the following environment variables:

 ```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Microsoft Foundry resource endpoint
 $env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"  # Optional, defaults to gpt-4.1-mini
 ```
@@ -11,7 +11,7 @@ Before you begin, ensure you have the following prerequisites:
 - Azure CLI installed and authenticated (for Azure credential authentication)
 - User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource.

-**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).

 **Note**: These samples use Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).

@@ -11,12 +11,12 @@ using Microsoft.Extensions.AI;
 namespace WorkflowFoundryAgentSample;

 /// <summary>
-/// This sample shows how to use Azure Foundry Agents within a workflow.
+/// This sample shows how to use Microsoft Foundry Agents within a workflow.
 /// </summary>
 /// <remarks>
 /// Pre-requisites:
 /// - Foundational samples should be completed first.
-/// - An Azure Foundry project endpoint and model id.
+/// - A Microsoft Foundry project endpoint and model ID.
 /// </remarks>
 public static class Program
 {
@@ -30,7 +30,7 @@ namespace Demo.Workflows.Declarative.InvokeMcpTool;
 /// <item>Integrating with MCP-compatible services</item>
 /// </list>
 /// <para>
-/// This sample uses the Microsoft Learn MCP server to search Azure documentation and the Azure foundry MCP server to get AI model details.
+/// This sample uses the Microsoft Learn MCP server to search Azure documentation and the Microsoft Foundry MCP server to get AI model details.
 /// When you run the sample, provide an AI model (e.g. gpt-4.1-mini) as input,
 /// The workflow will use the MCP tools to find relevant information about the model from Microsoft Learn and foundry, then an agent will summarize the results.
 /// </para>
@@ -6,7 +6,7 @@ to build a `Workflow` that may be executed using the same pattern as any code-ba
 ## Configuration

 These samples must be configured to create and use agents your 
-[Azure Foundry Project](https://learn.microsoft.com/azure/ai-foundry).
+[Microsoft Foundry Project](https://learn.microsoft.com/azure/ai-foundry).

 ### Settings

@@ -18,9 +18,9 @@ The configuraton required by the samples is:

 |Setting Name| Description|
 |:--|:--|
-|AZURE_AI_PROJECT_ENDPOINT| The endpoint URL of your Azure Foundry Project.|
+|AZURE_AI_PROJECT_ENDPOINT| The endpoint URL of your Microsoft Foundry Project.|
 |AZURE_AI_MODEL_DEPLOYMENT_NAME| The name of the model deployment to use
-|AZURE_AI_BING_CONNECTION_ID| The name of the Bing Grounding connection configured in your Azure Foundry Project.|
+|AZURE_AI_BING_CONNECTION_ID| The name of the Bing Grounding connection configured in your Microsoft Foundry Project.|

 To set your secrets with .NET Secret Manager:

@@ -42,13 +42,13 @@ To set your secrets with .NET Secret Manager:
    dotnet user-secrets init
    ```

-4. Define setting that identifies your Azure Foundry Project (endpoint):
+4. Define setting that identifies your Microsoft Foundry Project (endpoint):

    ```
    dotnet user-secrets set "AZURE_AI_PROJECT_ENDPOINT" "https://..."
    ```

-5. Define setting that identifies your Azure Foundry Model Deployment (endpoint):
+5. Define setting that identifies your Microsoft Foundry Model Deployment (endpoint):

    ```
    dotnet user-secrets set "AZURE_AI_MODEL_DEPLOYMENT_NAME" "gpt-5"
@@ -70,7 +70,7 @@ $env:AZURE_AI_BING_CONNECTION_ID="mybinggrounding"

 ### Authorization

-Use [_Azure CLI_](https://learn.microsoft.com/cli/azure/authenticate-azure-cli) to authorize access to your Azure Foundry Project:
+Use [_Azure CLI_](https://learn.microsoft.com/cli/azure/authenticate-azure-cli) to authorize access to your Microsoft Foundry Project:

 ```
 az login
@@ -26,7 +26,7 @@ Once completed, please proceed to the other samples listed below.

 | Sample | Concepts |
 |--------|----------|
-| [Foundry Agents in Workflows](./Agents/FoundryAgent) | Demonstrates using Azure Foundry agents in a workflow through `ChatClientAgent` |
+| [Foundry Agents in Workflows](./Agents/FoundryAgent) | Demonstrates using Microsoft Foundry agents in a workflow through `ChatClientAgent` |
 | [Custom Agent Executors](./Agents/CustomAgentExecutors) | Shows how to create a custom agent executor for more complex scenarios |
 | [Workflow as an Agent](./Agents/WorkflowAsAnAgent) | Illustrates how to encapsulate a workflow as an agent |
 | [Group Chat with Tool Approval](./Agents/GroupChatToolApproval) | Shows multi-agent group chat with tool approval requests and human-in-the-loop interaction |
@@ -51,7 +51,7 @@ dotnet run --urls "http://localhost:5002;https://localhost:5012" --agentType "lo

 ### Configuring for use with Azure AI Agents

-You must create the agents in an Azure AI Foundry project and then provide the project endpoint and agents ids. The instructions for each agent are as follows:
+You must create the agents in a Microsoft Foundry project and then provide the project endpoint and agent IDs. The instructions for each agent are as follows:

 - Invoice Agent
    ```
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 // Seattle Hotel Agent - A simple agent with a tool to find hotels in Seattle.
-// Uses Microsoft Agent Framework with Azure AI Foundry.
+// Uses Microsoft Agent Framework with Microsoft Foundry.
 // Ready for deployment to Foundry Hosted Agent service.

 using System.ClientModel.Primitives;
@@ -4,7 +4,7 @@ This sample demonstrates how to build a hosted agent that uses local C# function

 Key features:
 - Defining local C# functions as agent tools using `AIFunctionFactory`
- Using `AIProjectClient` to discover the OpenAI connection from the Azure AI Foundry project
+- Using `AIProjectClient` to discover the OpenAI connection from the Microsoft Foundry project
 - Building a `ChatClientAgent` with custom instructions and tools
 - Deploying to the Foundry Hosted Agent service

@@ -15,7 +15,7 @@ Key features:
 Before running this sample, ensure you have:

 1. .NET 10 SDK installed
-2. An Azure AI Foundry Project with a chat model deployed (e.g., gpt-4o-mini)
+2. A Microsoft Foundry Project with a chat model deployed (e.g., gpt-4o-mini)
 3. Azure CLI installed and authenticated (`az login`)

 ## Environment Variables
@@ -23,7 +23,7 @@ Before running this sample, ensure you have:
 Set the following environment variables:

 ```powershell
-# Replace with your Azure AI Foundry project endpoint
+# Replace with your Microsoft Foundry project endpoint
 $env:AZURE_AI_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project-name"

 # Optional, defaults to gpt-4o-mini
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 // This sample demonstrates a multi-agent workflow with Writer and Reviewer agents
-// using Azure AI Foundry AIProjectClient and the Agent Framework WorkflowBuilder.
+// using Microsoft Foundry AIProjectClient and the Agent Framework WorkflowBuilder.

 #pragma warning disable CA2252 // AIProjectClient and Agents API require opting into preview features

@@ -42,7 +42,7 @@ which provisions a REST API endpoint compatible with the OpenAI Responses protoc

 Before running this sample, ensure you have:

-1. **Azure AI Foundry Project**
+1. **Microsoft Foundry Project**
   - Project created.
   - Chat model deployed (e.g., `gpt-4o` or `gpt-4.1`)
   - Note your project endpoint URL and model deployment name
@@ -4,7 +4,7 @@ name: FoundryMultiAgent
 displayName: "Foundry Multi-Agent Workflow"
 description: >
  A multi-agent workflow featuring a Writer and Reviewer that collaborate
-  to create and refine content using Azure AI Foundry PersistentAgentsClient.
+  to create and refine content using Microsoft Foundry PersistentAgentsClient.
 metadata:
  authors:
    - Microsoft Agent Framework Team
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 // Seattle Hotel Agent - A simple agent with a tool to find hotels in Seattle.
-// Uses Microsoft Agent Framework with Azure AI Foundry.
+// Uses Microsoft Agent Framework with Microsoft Foundry.
 // Ready for deployment to Foundry Hosted Agent service.

 #pragma warning disable CA2252 // AIProjectClient and Agents API require opting into preview features
@@ -39,7 +39,7 @@ which provisions a REST API endpoint compatible with the OpenAI Responses protoc

 Before running this sample, ensure you have:

-1. **Azure AI Foundry Project**
+1. **Microsoft Foundry Project**
   - Project created.
   - Chat model deployed (e.g., `gpt-4o` or `gpt-4.1`)
   - Note your project endpoint URL and model deployment name
@@ -57,7 +57,7 @@ Before running this sample, ensure you have:

 Set the following environment variables (matching `agent.yaml`):

- `AZURE_AI_PROJECT_ENDPOINT` - Your Azure AI Foundry project endpoint URL (required)
+- `AZURE_AI_PROJECT_ENDPOINT` - Your Microsoft Foundry project endpoint URL (required)
 - `MODEL_DEPLOYMENT_NAME` - The deployment name for your chat model (defaults to `gpt-4o-mini`)

 **PowerShell:**
@@ -20,7 +20,7 @@ Before running any sample, ensure you have:

 1. **.NET 10 SDK** or later — [Download](https://dotnet.microsoft.com/download/dotnet/10.0)
 2. **Azure CLI** installed — [Install guide](https://learn.microsoft.com/cli/azure/install-azure-cli)
-3. **Azure OpenAI** or **Azure AI Foundry project** with a chat model deployed (e.g., `gpt-4o-mini`)
+3. **Azure OpenAI** or **Microsoft Foundry project** with a chat model deployed (e.g., `gpt-4o-mini`)

 ### Authenticate with Azure CLI

@@ -39,14 +39,14 @@ Most samples require one or more of these environment variables:
 |----------|---------|-------------|
 | `AZURE_OPENAI_ENDPOINT` | Most samples | Your Azure OpenAI resource endpoint URL |
 | `AZURE_OPENAI_DEPLOYMENT_NAME` | Most samples | Chat model deployment name (defaults to `gpt-4o-mini`) |
-| `AZURE_AI_PROJECT_ENDPOINT` | AgentWithLocalTools, FoundryMultiAgent, FoundrySingleAgent | Azure AI Foundry project endpoint |
+| `AZURE_AI_PROJECT_ENDPOINT` | AgentWithLocalTools, FoundryMultiAgent, FoundrySingleAgent | Microsoft Foundry project endpoint |
 | `MODEL_DEPLOYMENT_NAME` | AgentWithLocalTools, FoundryMultiAgent, FoundrySingleAgent | Chat model deployment name (defaults to `gpt-4o-mini`) |

 See each sample's README for the specific variables required.

-## Azure AI Foundry Setup (for samples that use Foundry)
+## Microsoft Foundry Setup (for samples that use Foundry)

-Some samples (`AgentWithLocalTools`, `FoundrySingleAgent`, `FoundryMultiAgent`) connect to an Azure AI Foundry project. If you're using these samples, you'll need additional setup.
+Some samples (`AgentWithLocalTools`, `FoundrySingleAgent`, `FoundryMultiAgent`) connect to a Microsoft Foundry project. If you're using these samples, you'll need additional setup.

 ### Azure AI Developer Role

@@ -61,7 +61,7 @@ az role assignment create `

 > **Note**: You need **Owner** or **User Access Administrator** permissions on the resource to assign roles. If you don't have this, you may need to request JIT (Just-In-Time) elevated access via [Azure PIM](https://portal.azure.com/#view/Microsoft_Azure_PIMCommon/ActivationMenuBlade/~/aadmigratedresource).

-For more details on permissions, see [Azure AI Foundry Permissions](https://aka.ms/FoundryPermissions).
+For more details on permissions, see [Microsoft Foundry Permissions](https://aka.ms/FoundryPermissions).

 ## Running a Sample

@@ -28,7 +28,7 @@ dotnet/samples/
 │   ├── AGUI/                          # AG-UI protocol samples
 │   ├── DeclarativeAgents/             # Declarative agent definitions
 │   ├── DevUI/                         # DevUI samples
-│   ├── AgentsWithFoundry/             # Azure AI Foundry samples (FoundryAgent + AsAIAgent extensions)
+│   ├── AgentsWithFoundry/             # Microsoft Foundry samples (FoundryAgent + AsAIAgent extensions)
 │   └── ModelContextProtocol/          # MCP server/client patterns
 ├── 03-workflows/                      # Workflow patterns
 │   ├── _StartHere/                    # Introductory workflow samples
@@ -3,7 +3,7 @@
 The agent framework samples are designed to help you get started with building AI-powered agents
 from various providers.

-The Agent Framework supports building agents using various infererence and inference-style services.
+The Agent Framework supports building agents using various inference and inference-style services.
 All these are supported using the single `ChatClientAgent` class.

 The Agent Framework also supports creating proxy agents, that allow accessing remote agents as if they
@@ -21,6 +21,15 @@ internal interface ICheckpointingHandle
    /// <summary>
    /// Restores the system state from the specified checkpoint asynchronously.
    /// </summary>
+    /// <remarks>
+    /// This contract is used by live runtime restore paths. Implementations may re-emit pending
+    /// external request events as part of the restore once the active event stream is ready to
+    /// observe them.
+    ///
+    /// Initial resume paths that create a new event stream should restore state first and defer
+    /// any replay until after the subscriber is attached, rather than calling this contract
+    /// directly before the stream is ready.
+    /// </remarks>
    /// <param name="checkpointInfo">The checkpoint information that identifies the state to restore. Cannot be null.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the restore operation.</param>
    /// <returns>A <see cref="ValueTask"/> that represents the asynchronous restore operation.</returns>
@@ -36,9 +36,10 @@ internal sealed class AsyncRunHandle : ICheckpointingHandle, IAsyncDisposable

        this._eventStream.Start();

-        // If there are already unprocessed messages (e.g., from a checkpoint restore that happened
-        // before this handle was created), signal the run loop to start processing them
-        if (stepRunner.HasUnprocessedMessages)
+        // If there are already unprocessed messages or unserviced requests (e.g., from a
+        // checkpoint restore that happened before this handle was created), signal the run
+        // loop to start processing them
+        if (stepRunner.HasUnprocessedMessages || stepRunner.HasUnservicedRequests)
        {
            this.SignalInputToRunLoop();
        }
@@ -192,13 +193,17 @@ internal sealed class AsyncRunHandle : ICheckpointingHandle, IAsyncDisposable
        {
            streamingEventStream.ClearBufferedEvents();
        }
+        else if (this._eventStream is LockstepRunEventStream lockstepEventStream)
+        {
+            lockstepEventStream.ClearBufferedEvents();
+        }

-        // Restore the workflow state - this will republish unserviced requests as new events
+        // Restore the workflow state through the live runtime-restore path.
+        // This can re-emit pending requests into the already-active event stream.
        await this._checkpointingHandle.RestoreCheckpointAsync(checkpointInfo, cancellationToken).ConfigureAwait(false);

-        // After restore, signal the run loop to process any restored messages
-        // This is necessary because ClearBufferedEvents() doesn't signal, and the restored
-        // queued messages won't automatically wake up the run loop
+        // After restore, signal the run loop to process any restored messages. Initial resume
+        // paths handle this separately when they create the event stream after restoring state.
        this.SignalInputToRunLoop();
    }
 }
@@ -27,6 +27,14 @@ internal interface ISuperStepRunner

    ConcurrentEventSink OutgoingEvents { get; }

+    /// <summary>
+    /// Re-emits <see cref="RequestInfoEvent"/>s for any pending external requests.
+    /// Called by event streams after subscribing to <see cref="OutgoingEvents"/> so that
+    /// requests restored from a checkpoint are observable even when the restore happened
+    /// before the subscription was active.
+    /// </summary>
+    ValueTask RepublishPendingEventsAsync(CancellationToken cancellationToken = default);
+
    ValueTask<bool> RunSuperStepAsync(CancellationToken cancellationToken);

    // This cannot be cancelled
@@ -15,6 +15,7 @@ internal sealed class LockstepRunEventStream : IRunEventStream
 {
    private readonly CancellationTokenSource _stopCancellation = new();
    private readonly InputWaiter _inputWaiter = new();
+    private ConcurrentQueue<WorkflowEvent> _eventSink = new();
    private int _isDisposed;

    private readonly ISuperStepRunner _stepRunner;
@@ -35,6 +36,8 @@ internal sealed class LockstepRunEventStream : IRunEventStream
        // doesn't leak into caller code via AsyncLocal.
        Activity? previousActivity = Activity.Current;

+        this._stepRunner.OutgoingEvents.EventRaised += this.OnWorkflowEventAsync;
+
        this._sessionActivity = this._stepRunner.TelemetryContext.StartWorkflowSessionActivity();
        this._sessionActivity?.SetTag(Tags.WorkflowId, this._stepRunner.StartExecutorId)
                              .SetTag(Tags.SessionId, this._stepRunner.SessionId);
@@ -56,10 +59,6 @@ internal sealed class LockstepRunEventStream : IRunEventStream

        using CancellationTokenSource linkedSource = CancellationTokenSource.CreateLinkedTokenSource(this._stopCancellation.Token, cancellationToken);

-        ConcurrentQueue<WorkflowEvent> eventSink = [];
-
-        this._stepRunner.OutgoingEvents.EventRaised += OnWorkflowEventAsync;
-
        // Re-establish session as parent so the run activity nests correctly.
        Activity.Current = this._sessionActivity;

@@ -73,7 +72,31 @@ internal sealed class LockstepRunEventStream : IRunEventStream
            runActivity?.AddEvent(new ActivityEvent(EventNames.WorkflowStarted));

            // Emit WorkflowStartedEvent to the event stream for consumers
-            eventSink.Enqueue(new WorkflowStartedEvent());
+            this._eventSink.Enqueue(new WorkflowStartedEvent());
+
+            // Re-emit any pending external requests that were restored from a checkpoint
+            // before this subscription was active. For non-resume starts this is a no-op.
+            // This runs after WorkflowStartedEvent so consumers always see the started event first.
+            await this._stepRunner.RepublishPendingEventsAsync(linkedSource.Token).ConfigureAwait(false);
+
+            // When resuming from a checkpoint with only pending requests (no queued messages),
+            // the inner processing loop won't execute, so we must drain events now.
+            // For normal starts this is a no-op since the inner loop handles the drain.
+            if (!this._stepRunner.HasUnprocessedMessages)
+            {
+                var (drainedEvents, shouldHalt) = this.DrainAndFilterEvents();
+                foreach (WorkflowEvent raisedEvent in drainedEvents)
+                {
+                    yield return raisedEvent;
+                }
+
+                if (shouldHalt)
+                {
+                    yield break;
+                }
+
+                this.RunStatus = this._stepRunner.HasUnservicedRequests ? RunStatus.PendingRequests : RunStatus.Idle;
+            }

            do
            {
@@ -107,26 +130,19 @@ internal sealed class LockstepRunEventStream : IRunEventStream
                        yield break; // Exit if cancellation is requested
                    }

-                    bool hadRequestHaltEvent = false;
-                    foreach (WorkflowEvent raisedEvent in Interlocked.Exchange(ref eventSink, []))
+                    var (drainedEvents, shouldHalt) = this.DrainAndFilterEvents();
+
+                    foreach (WorkflowEvent raisedEvent in drainedEvents)
                    {
                        if (linkedSource.Token.IsCancellationRequested)
                        {
                            yield break; // Exit if cancellation is requested
                        }

-                        // TODO: Do we actually want to interpret this as a termination request?
-                        if (raisedEvent is RequestHaltEvent)
-                        {
-                            hadRequestHaltEvent = true;
-                        }
-                        else
-                        {
-                            yield return raisedEvent;
-                        }
+                        yield return raisedEvent;
                    }

-                    if (hadRequestHaltEvent || linkedSource.Token.IsCancellationRequested)
+                    if (shouldHalt || linkedSource.Token.IsCancellationRequested)
                    {
                        // If we had a completion event, we are done.
                        yield break;
@@ -151,25 +167,23 @@ internal sealed class LockstepRunEventStream : IRunEventStream
        finally
        {
            this.RunStatus = this._stepRunner.HasUnservicedRequests ? RunStatus.PendingRequests : RunStatus.Idle;
-            this._stepRunner.OutgoingEvents.EventRaised -= OnWorkflowEventAsync;

            // Explicitly dispose the Activity so Activity.Stop fires deterministically,
            // regardless of how the async iterator enumerator is disposed.
            runActivity?.Dispose();
        }

-        ValueTask OnWorkflowEventAsync(object? sender, WorkflowEvent e)
-        {
-            eventSink.Enqueue(e);
-            return default;
-        }
-
        // If we are Idle or Ended, we should break out of the loop
        // If we are PendingRequests and not blocking on pending requests, we should break out of the loop
        // If cancellation is requested, we should break out of the loop
        bool ShouldBreak() => this.RunStatus is RunStatus.Idle or RunStatus.Ended ||
-                              (this.RunStatus == RunStatus.PendingRequests && !blockOnPendingRequest) ||
-                              linkedSource.Token.IsCancellationRequested;
+                               (this.RunStatus == RunStatus.PendingRequests && !blockOnPendingRequest) ||
+                               linkedSource.Token.IsCancellationRequested;
+    }
+
+    internal void ClearBufferedEvents()
+    {
+        Interlocked.Exchange(ref this._eventSink, new ConcurrentQueue<WorkflowEvent>());
    }

    /// <summary>
@@ -192,6 +206,7 @@ internal sealed class LockstepRunEventStream : IRunEventStream
        if (Interlocked.Exchange(ref this._isDisposed, 1) == 0)
        {
            this._stopCancellation.Cancel();
+            this._stepRunner.OutgoingEvents.EventRaised -= this.OnWorkflowEventAsync;

            // Stop the session activity
            if (this._sessionActivity is not null)
@@ -207,4 +222,32 @@ internal sealed class LockstepRunEventStream : IRunEventStream

        return default;
    }
+
+    private ValueTask OnWorkflowEventAsync(object? sender, WorkflowEvent e)
+    {
+        this._eventSink.Enqueue(e);
+        return default;
+    }
+
+    // Atomically drains the event sink and separates workflow events from halt signals.
+    // Used by both the early-drain (resume with pending requests only) and
+    // the inner superstep drain to keep halt-detection logic in one place.
+    private (List<WorkflowEvent> Events, bool ShouldHalt) DrainAndFilterEvents()
+    {
+        List<WorkflowEvent> events = [];
+        bool shouldHalt = false;
+        foreach (WorkflowEvent e in Interlocked.Exchange(ref this._eventSink, new ConcurrentQueue<WorkflowEvent>()))
+        {
+            if (e is RequestHaltEvent)
+            {
+                shouldHalt = true;
+            }
+            else
+            {
+                events.Add(e);
+            }
+        }
+
+        return (events, shouldHalt);
+    }
 }
@@ -23,7 +23,8 @@ internal sealed class StreamingRunEventStream : IRunEventStream
    private readonly CancellationTokenSource _runLoopCancellation;
    private readonly bool _disableRunLoop;
    private Task? _runLoopTask;
-    private RunStatus _runStatus = RunStatus.NotStarted;
+    private volatile RunStatus _runStatus = RunStatus.NotStarted;
+
    private int _completionEpoch; // Tracks which completion signal belongs to which consumer iteration

    public StreamingRunEventStream(ISuperStepRunner stepRunner, bool disableRunLoop = false)
@@ -60,6 +61,10 @@ internal sealed class StreamingRunEventStream : IRunEventStream
        // Subscribe to events - they will flow directly to the channel as they're raised
        this._stepRunner.OutgoingEvents.EventRaised += OnEventRaisedAsync;

+        // Re-emit any pending external requests that were restored from a checkpoint
+        // before this subscription was active. For non-resume starts this is a no-op.
+        await this._stepRunner.RepublishPendingEventsAsync(linkedSource.Token).ConfigureAwait(false);
+
        // Start the session-level activity that spans the entire run loop lifetime.
        // Individual run-stage activities are nested within this session activity.
        Activity? sessionActivity = this._stepRunner.TelemetryContext.StartWorkflowSessionActivity();
@@ -123,7 +128,7 @@ internal sealed class StreamingRunEventStream : IRunEventStream

                // Wait for next input from the consumer
                // Works for both Idle (no work) and PendingRequests (waiting for responses)
-                await this._inputWaiter.WaitForInputAsync(TimeSpan.FromSeconds(1), linkedSource.Token).ConfigureAwait(false);
+                await this._inputWaiter.WaitForInputAsync(linkedSource.Token).ConfigureAwait(false);

                // When signaled, resume running
                this._runStatus = RunStatus.Running;
@@ -205,7 +210,10 @@ internal sealed class StreamingRunEventStream : IRunEventStream
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        // Get the current epoch - we'll only respond to completion signals from this epoch or later
-        int myEpoch = Volatile.Read(ref this._completionEpoch) + 1;
+        int currentEpoch = Volatile.Read(ref this._completionEpoch);
+
+        bool expectingFreshWork = this._stepRunner.HasUnprocessedMessages || this._runStatus == RunStatus.Running;
+        int myEpoch = expectingFreshWork ? currentEpoch + 1 : currentEpoch;

        // Use custom async enumerable to avoid exceptions on cancellation.
        NonThrowingChannelReaderAsyncEnumerable<WorkflowEvent> eventStream = new(this._eventChannel.Reader);
@@ -50,10 +50,13 @@ public sealed class InProcessExecutionEnvironment : IWorkflowExecutionEnvironmen
        return runner.BeginStreamAsync(this.ExecutionMode, cancellationToken);
    }

-    internal ValueTask<AsyncRunHandle> ResumeRunAsync(Workflow workflow, CheckpointInfo fromCheckpoint, IEnumerable<Type> knownValidInputTypes, CancellationToken cancellationToken)
+    internal ValueTask<AsyncRunHandle> ResumeRunAsync(Workflow workflow, CheckpointInfo fromCheckpoint, IEnumerable<Type> knownValidInputTypes, CancellationToken cancellationToken = default)
+        => this.ResumeRunAsync(workflow, fromCheckpoint, knownValidInputTypes, republishPendingEvents: true, cancellationToken);
+
+    internal ValueTask<AsyncRunHandle> ResumeRunAsync(Workflow workflow, CheckpointInfo fromCheckpoint, IEnumerable<Type> knownValidInputTypes, bool republishPendingEvents, CancellationToken cancellationToken = default)
    {
        InProcessRunner runner = InProcessRunner.CreateTopLevelRunner(workflow, this.CheckpointManager, fromCheckpoint.SessionId, this.EnableConcurrentRuns, knownValidInputTypes);
-        return runner.ResumeStreamAsync(this.ExecutionMode, fromCheckpoint, cancellationToken);
+        return runner.ResumeStreamAsync(this.ExecutionMode, fromCheckpoint, republishPendingEvents, cancellationToken);
    }

    /// <inheritdoc/>
@@ -104,6 +107,32 @@ public sealed class InProcessExecutionEnvironment : IWorkflowExecutionEnvironmen
        return new(runHandle);
    }

+    /// <summary>
+    /// Resumes a streaming workflow run from a checkpoint with control over whether
+    /// pending request events are republished through the event stream.
+    /// </summary>
+    /// <param name="workflow">The workflow to resume.</param>
+    /// <param name="fromCheckpoint">The checkpoint to resume from.</param>
+    /// <param name="republishPendingEvents">
+    /// When <see langword="true"/>, any pending request events are republished through the event
+    /// stream after subscribing. When <see langword="false"/>, the caller is responsible for
+    /// handling pending requests (e.g., <see cref="WorkflowSession"/> already sends responses).
+    /// </param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    internal async ValueTask<StreamingRun> ResumeStreamingInternalAsync(
+        Workflow workflow,
+        CheckpointInfo fromCheckpoint,
+        bool republishPendingEvents,
+        CancellationToken cancellationToken = default)
+    {
+        this.VerifyCheckpointingConfigured();
+
+        AsyncRunHandle runHandle = await this.ResumeRunAsync(workflow, fromCheckpoint, [], republishPendingEvents, cancellationToken)
+                                             .ConfigureAwait(false);
+
+        return new(runHandle);
+    }
+
    private async ValueTask<AsyncRunHandle> BeginRunHandlingChatProtocolAsync<TInput>(Workflow workflow,
        TInput input,
        string? sessionId = null,
@@ -71,6 +71,28 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
    /// <inheritdoc cref="ISuperStepRunner.StartExecutorId"/>
    public string StartExecutorId { get; }

+    /// <summary>
+    /// Gating flag for deferred event republishing after checkpoint restore.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Written with <see cref="Volatile.Write(ref int, int)"/> in <see cref="ResumeStreamAsync(ExecutionMode, CheckpointInfo, bool, CancellationToken)"/>
+    /// and consumed atomically with <see cref="Interlocked.Exchange(ref int, int)"/> in
+    /// <see cref="ISuperStepRunner.RepublishPendingEventsAsync"/>. The write does not need a full
+    /// memory barrier because it is sequenced before the <see cref="AsyncRunHandle"/> constructor
+    /// by the <see langword="await"/> in <see cref="ResumeStreamAsync(ExecutionMode, CheckpointInfo, bool, CancellationToken)"/>. The constructor is the
+    /// only code path that triggers consumption (via the event stream's subscribe and republish flow).
+    /// </para>
+    /// <para>
+    /// Note: <see cref="AsyncRunHandle"/> also reads <see cref="ISuperStepRunner.HasUnservicedRequests"/>
+    /// in its constructor to signal the run loop, but that property reads from
+    /// <see cref="InProcessRunnerContext"/>'s request dictionary (restored during
+    /// <see cref="RestoreCheckpointCoreAsync"/>), not from this flag. The two are independent:
+    /// <c>HasUnservicedRequests</c> triggers the run loop; <c>_needsRepublish</c> triggers event emission.
+    /// </para>
+    /// </remarks>
+    private int _needsRepublish;
+
    /// <inheritdoc cref="ISuperStepRunner.TelemetryContext"/>
    public WorkflowTelemetryContext TelemetryContext => this.Workflow.TelemetryContext;

@@ -145,7 +167,10 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
        return new(new AsyncRunHandle(this, this, mode));
    }

-    public async ValueTask<AsyncRunHandle> ResumeStreamAsync(ExecutionMode mode, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default)
+    public ValueTask<AsyncRunHandle> ResumeStreamAsync(ExecutionMode mode, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default)
+        => this.ResumeStreamAsync(mode, fromCheckpoint, republishPendingEvents: true, cancellationToken);
+
+    public async ValueTask<AsyncRunHandle> ResumeStreamAsync(ExecutionMode mode, CheckpointInfo fromCheckpoint, bool republishPendingEvents, CancellationToken cancellationToken = default)
    {
        this.RunContext.CheckEnded();
        Throw.IfNull(fromCheckpoint);
@@ -154,7 +179,18 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
            throw new InvalidOperationException("This runner was not configured with a CheckpointManager, so it cannot restore checkpoints.");
        }

-        await this.RestoreCheckpointAsync(fromCheckpoint, cancellationToken).ConfigureAwait(false);
+        // Restore checkpoint state without republishing pending request events.
+        // The event stream will republish them after subscribing so that events
+        // are never lost to an absent subscriber.
+        await this.RestoreCheckpointCoreAsync(fromCheckpoint, cancellationToken).ConfigureAwait(false);
+
+        if (republishPendingEvents)
+        {
+            // Signal the event stream to republish pending requests after subscribing.
+            // This is consumed atomically by RepublishPendingEventsAsync.
+            Volatile.Write(ref this._needsRepublish, 1);
+        }
+
        return new AsyncRunHandle(this, this, mode);
    }

@@ -163,6 +199,16 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
    bool ISuperStepRunner.TryGetResponsePortExecutorId(string portId, out string? executorId)
        => this.RunContext.TryGetResponsePortExecutorId(portId, out executorId);

+    ValueTask ISuperStepRunner.RepublishPendingEventsAsync(CancellationToken cancellationToken)
+    {
+        if (Interlocked.Exchange(ref this._needsRepublish, 0) != 0)
+        {
+            return this.RunContext.RepublishUnservicedRequestsAsync(cancellationToken);
+        }
+
+        return default;
+    }
+
    public bool IsCheckpointingEnabled => this.RunContext.IsCheckpointingEnabled;

    public IReadOnlyList<CheckpointInfo> Checkpoints => this._checkpoints;
@@ -310,7 +356,31 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
        this._checkpoints.Add(this._lastCheckpointInfo);
    }

+    /// <summary>
+    /// Restores checkpoint state and re-emits any pending external request events.
+    /// </summary>
+    /// <remarks>
+    /// This is the <see cref="ICheckpointingHandle"/> implementation used for runtime restores
+    /// where the event stream subscription is already active. For initial resumes,
+    /// <see cref="ResumeStreamAsync(ExecutionMode, CheckpointInfo, CancellationToken)"/> calls
+    /// <see cref="RestoreCheckpointCoreAsync"/> directly and defers republishing to the event stream.
+    /// </remarks>
    public async ValueTask RestoreCheckpointAsync(CheckpointInfo checkpointInfo, CancellationToken cancellationToken = default)
+    {
+        await this.RestoreCheckpointCoreAsync(checkpointInfo, cancellationToken).ConfigureAwait(false);
+
+        // Republish pending request events. This is safe for runtime restores where
+        // the event stream is already subscribed. For initial resumes the event stream
+        // handles republishing itself, so ResumeStreamAsync calls RestoreCheckpointCoreAsync directly.
+        await this.RunContext.RepublishUnservicedRequestsAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Restores checkpoint state (queued messages, executor state, edge state, etc.)
+    /// without republishing pending request events. The caller is responsible for
+    /// ensuring events are republished after an event subscriber is attached.
+    /// </summary>
+    private async ValueTask RestoreCheckpointCoreAsync(CheckpointInfo checkpointInfo, CancellationToken cancellationToken = default)
    {
        this.RunContext.CheckEnded();
        Throw.IfNull(checkpointInfo);
@@ -335,11 +405,9 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
        await this.RunContext.ImportStateAsync(checkpoint).ConfigureAwait(false);

        Task executorNotifyTask = this.RunContext.NotifyCheckpointLoadedAsync(cancellationToken);
-        ValueTask republishRequestsTask = this.RunContext.RepublishUnservicedRequestsAsync(cancellationToken);

        await this.EdgeMap.ImportStateAsync(checkpoint).ConfigureAwait(false);
        await Task.WhenAll(executorNotifyTask,
-                           republishRequestsTask.AsTask(),
                           restoreCheckpointIndexTask.AsTask()).ConfigureAwait(false);

        this._lastCheckpointInfo = checkpointInfo;
@@ -14,6 +14,7 @@ internal sealed class RequestPortOptions;

 internal sealed class RequestInfoExecutor : Executor
 {
+    private const string WrappedRequestsStateKey = nameof(WrappedRequestsStateKey);
    private readonly Dictionary<string, ExternalRequest> _wrappedRequests = [];
    private RequestPort Port { get; }
    private IExternalRequestSink? RequestSink { get; set; }
@@ -124,22 +125,46 @@ internal sealed class RequestInfoExecutor : Executor
            return null;
        }

-        if (this._allowWrapped && this._wrappedRequests.TryGetValue(message.RequestId, out ExternalRequest? originalRequest))
-        {
-            await context.SendMessageAsync(originalRequest.RewrapResponse(message), cancellationToken: cancellationToken).ConfigureAwait(false);
-        }
-        else
-        {
-            await context.SendMessageAsync(message, cancellationToken: cancellationToken).ConfigureAwait(false);
-        }
-
        if (!message.Data.IsType(this.Port.Response, out object? data))
        {
            throw this.Port.CreateExceptionForType(message);
        }

-        await context.SendMessageAsync(data, cancellationToken: cancellationToken).ConfigureAwait(false);
+        if (this._allowWrapped && this._wrappedRequests.TryGetValue(message.RequestId, out ExternalRequest? originalRequest))
+        {
+            await context.SendMessageAsync(originalRequest.RewrapResponse(message), cancellationToken: cancellationToken).ConfigureAwait(false);
+            this._wrappedRequests.Remove(message.RequestId);
+        }
+        else
+        {
+            await context.SendMessageAsync(message, cancellationToken: cancellationToken).ConfigureAwait(false);
+            await context.SendMessageAsync(data, cancellationToken: cancellationToken).ConfigureAwait(false);
+        }

        return message;
    }
+
+    protected internal override async ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        await context.QueueStateUpdateAsync(WrappedRequestsStateKey,
+                                            new Dictionary<string, ExternalRequest>(this._wrappedRequests, StringComparer.Ordinal),
+                                            cancellationToken: cancellationToken).ConfigureAwait(false);
+        await base.OnCheckpointingAsync(context, cancellationToken).ConfigureAwait(false);
+    }
+
+    protected internal override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        await base.OnCheckpointRestoredAsync(context, cancellationToken).ConfigureAwait(false);
+
+        this._wrappedRequests.Clear();
+
+        Dictionary<string, ExternalRequest> wrappedRequests =
+            await context.ReadStateAsync<Dictionary<string, ExternalRequest>>(WrappedRequestsStateKey, cancellationToken: cancellationToken)
+                         .ConfigureAwait(false) ?? [];
+
+        foreach (KeyValuePair<string, ExternalRequest> wrappedRequest in wrappedRequests)
+        {
+            this._wrappedRequests[wrappedRequest.Key] = wrappedRequest.Value;
+        }
+    }
 }
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System;
+using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
@@ -23,6 +24,7 @@ internal class WorkflowHostExecutor : Executor, IAsyncDisposable
    private InProcessRunner? _activeRunner;
    private InMemoryCheckpointManager? _checkpointManager;
    private readonly ExecutorOptions _options;
+    private readonly ConcurrentDictionary<string, RequestPortInfo> _pendingResponsePorts = new(StringComparer.Ordinal);

    private ISuperStepJoinContext? _joinContext;
    private string? _joinId;
@@ -163,6 +165,11 @@ internal class WorkflowHostExecutor : Executor, IAsyncDisposable

    private ExternalResponse? CheckAndUnqualifyResponse([DisallowNull] ExternalResponse response)
    {
+        if (this._pendingResponsePorts.TryRemove(response.RequestId, out RequestPortInfo? originalPort))
+        {
+            return response with { PortInfo = originalPort };
+        }
+
        if (!Throw.IfNull(response).PortInfo.PortId.StartsWith($"{this.Id}.", StringComparison.Ordinal))
        {
            return null;
@@ -193,6 +200,7 @@ internal class WorkflowHostExecutor : Executor, IAsyncDisposable
                    break;
                case RequestInfoEvent requestInfoEvt:
                    ExternalRequest request = requestInfoEvt.Request;
+                    this._pendingResponsePorts[request.RequestId] = request.PortInfo;
                    resultTask = this._joinContext?.SendMessageAsync(this.Id, this.QualifyRequestPortId(request)).AsTask() ?? Task.CompletedTask;
                    break;
                case WorkflowErrorEvent errorEvent:
@@ -246,9 +254,13 @@ internal class WorkflowHostExecutor : Executor, IAsyncDisposable
    }

    private const string CheckpointManagerStateKey = nameof(CheckpointManager);
+    private const string PendingResponsePortsStateKey = nameof(PendingResponsePortsStateKey);
    protected internal override async ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
    {
        await context.QueueStateUpdateAsync(CheckpointManagerStateKey, this._checkpointManager, cancellationToken: cancellationToken).ConfigureAwait(false);
+        await context.QueueStateUpdateAsync(PendingResponsePortsStateKey,
+                                            new Dictionary<string, RequestPortInfo>(this._pendingResponsePorts, StringComparer.Ordinal),
+                                            cancellationToken: cancellationToken).ConfigureAwait(false);

        await base.OnCheckpointingAsync(context, cancellationToken).ConfigureAwait(false);
    }
@@ -269,6 +281,15 @@ internal class WorkflowHostExecutor : Executor, IAsyncDisposable
            await this.ResetAsync().ConfigureAwait(false);
        }

+        this._pendingResponsePorts.Clear();
+        Dictionary<string, RequestPortInfo> pendingResponsePorts =
+            await context.ReadStateAsync<Dictionary<string, RequestPortInfo>>(PendingResponsePortsStateKey, cancellationToken: cancellationToken)
+                         .ConfigureAwait(false) ?? [];
+        foreach (KeyValuePair<string, RequestPortInfo> pendingResponsePort in pendingResponsePorts)
+        {
+            this._pendingResponsePorts[pendingResponsePort.Key] = pendingResponsePort.Value;
+        }
+
        await this.EnsureRunSendMessageAsync(resume: true, cancellationToken: cancellationToken).ConfigureAwait(false);
    }

@@ -280,6 +301,8 @@ internal class WorkflowHostExecutor : Executor, IAsyncDisposable
            this._run = null;
        }

+        this._pendingResponsePorts.Clear();
+
        if (this._activeRunner != null)
        {
            this._activeRunner.OutgoingEvents.EventRaised -= this.ForwardWorkflowEventAsync;
@@ -19,7 +19,14 @@ namespace Microsoft.Agents.AI.Workflows;
 internal sealed class WorkflowSession : AgentSession
 {
    private readonly Workflow _workflow;
-    private readonly IWorkflowExecutionEnvironment _executionEnvironment;
+
+    /// <summary>
+    /// The execution environment for this session. Concrete type is required because
+    /// <see cref="CreateOrResumeRunAsync"/> uses the internal
+    /// <see cref="InProcessExecutionEnvironment.ResumeStreamingInternalAsync"/> API.
+    /// </summary>
+    private readonly InProcessExecutionEnvironment _inProcEnvironment;
+
    private readonly bool _includeExceptionDetails;
    private readonly bool _includeWorkflowOutputsInResponse;

@@ -63,17 +70,22 @@ internal sealed class WorkflowSession : AgentSession
    public WorkflowSession(Workflow workflow, string sessionId, IWorkflowExecutionEnvironment executionEnvironment, bool includeExceptionDetails = false, bool includeWorkflowOutputsInResponse = false)
    {
        this._workflow = Throw.IfNull(workflow);
-        this._executionEnvironment = Throw.IfNull(executionEnvironment);
        this._includeExceptionDetails = includeExceptionDetails;
        this._includeWorkflowOutputsInResponse = includeWorkflowOutputsInResponse;

-        if (VerifyCheckpointingConfiguration(executionEnvironment, out InProcessExecutionEnvironment? inProcEnv))
+        IWorkflowExecutionEnvironment env = Throw.IfNull(executionEnvironment);
+        if (VerifyCheckpointingConfiguration(env, out InProcessExecutionEnvironment? inProcEnv))
        {
            // We have an InProcessExecutionEnvironment which is not configured for checkpointing. Ensure it has an externalizable checkpoint manager,
            // since we are responsible for maintaining the state.
-            this._executionEnvironment = inProcEnv.WithCheckpointing(this.EnsureExternalizedInMemoryCheckpointing());
+            env = inProcEnv.WithCheckpointing(this.EnsureExternalizedInMemoryCheckpointing());
        }

+        this._inProcEnvironment = env as InProcessExecutionEnvironment
+            ?? throw new InvalidOperationException(
+                $"WorkflowSession requires an {nameof(InProcessExecutionEnvironment)}, " +
+                $"but received {env.GetType().Name}.");
+
        this.SessionId = Throw.IfNullOrEmpty(sessionId);
        this.ChatHistoryProvider = new WorkflowChatHistoryProvider();
    }
@@ -86,24 +98,30 @@ internal sealed class WorkflowSession : AgentSession
    public WorkflowSession(Workflow workflow, JsonElement serializedSession, IWorkflowExecutionEnvironment executionEnvironment, bool includeExceptionDetails = false, bool includeWorkflowOutputsInResponse = false, JsonSerializerOptions? jsonSerializerOptions = null)
    {
        this._workflow = Throw.IfNull(workflow);
-        this._executionEnvironment = Throw.IfNull(executionEnvironment);
        this._includeExceptionDetails = includeExceptionDetails;
        this._includeWorkflowOutputsInResponse = includeWorkflowOutputsInResponse;

+        IWorkflowExecutionEnvironment env = Throw.IfNull(executionEnvironment);
+
        JsonMarshaller marshaller = new(jsonSerializerOptions);
        SessionState sessionState = marshaller.Marshal<SessionState>(serializedSession);

        this._inMemoryCheckpointManager = sessionState.CheckpointManager;
        if (this._inMemoryCheckpointManager != null &&
-            VerifyCheckpointingConfiguration(executionEnvironment, out InProcessExecutionEnvironment? inProcEnv))
+            VerifyCheckpointingConfiguration(env, out InProcessExecutionEnvironment? inProcEnv))
        {
-            this._executionEnvironment = inProcEnv.WithCheckpointing(this.EnsureExternalizedInMemoryCheckpointing());
+            env = inProcEnv.WithCheckpointing(this.EnsureExternalizedInMemoryCheckpointing());
        }
        else if (this._inMemoryCheckpointManager != null)
        {
            throw new ArgumentException("The session was saved with an externalized checkpoint manager, but the incoming execution environment does not support it.", nameof(executionEnvironment));
        }

+        this._inProcEnvironment = env as InProcessExecutionEnvironment
+            ?? throw new InvalidOperationException(
+                $"WorkflowSession requires an {nameof(InProcessExecutionEnvironment)}, " +
+                $"but received {env.GetType().Name}.");
+
        this.SessionId = sessionState.SessionId;
        this.ChatHistoryProvider = new WorkflowChatHistoryProvider();

@@ -160,10 +178,15 @@ internal sealed class WorkflowSession : AgentSession
        // and does not need to be checked again here.
        if (this.LastCheckpoint is not null)
        {
+            // Use the internal resume path that suppresses pending request republishing.
+            // WorkflowSession handles pending requests itself by converting matching responses
+            // via SendMessagesWithResponseConversionAsync, so event-stream republishing would
+            // cause unwanted duplicate events visible to the consumer.
            StreamingRun run =
-                await this._executionEnvironment
-                            .ResumeStreamingAsync(this._workflow,
+                await this._inProcEnvironment
+                            .ResumeStreamingInternalAsync(this._workflow,
                                               this.LastCheckpoint,
+                                               republishPendingEvents: false,
                                               cancellationToken)
                            .ConfigureAwait(false);

@@ -172,7 +195,7 @@ internal sealed class WorkflowSession : AgentSession
            return new ResumeRunResult(run, dispatchInfo);
        }

-        StreamingRun newRun = await this._executionEnvironment
+        StreamingRun newRun = await this._inProcEnvironment
                            .RunStreamingAsync(this._workflow,
                                         messages,
                                         this.SessionId,
@@ -139,8 +139,8 @@ public sealed partial class ChatClientAgent : AIAgent

        this._logger = (loggerFactory ?? chatClient.GetService<ILoggerFactory>() ?? NullLoggerFactory.Instance).CreateLogger<ChatClientAgent>();

-        // Warn if using a custom chat client stack with simulated service stored persistence but no ServiceStoredSimulatingChatClient.
-        this.WarnOnMissingServiceStoredSimulatingClient();
+        // Warn if using a custom chat client stack with simulated service stored persistence but no PerServiceCallChatHistoryPersistingChatClient.
+        this.WarnOnMissingPerServiceCallChatHistoryPersistingChatClient();
    }

    /// <summary>
@@ -454,7 +454,7 @@ public sealed partial class ChatClientAgent : AIAgent
    /// Notifies the <see cref="ChatHistoryProvider"/> and all <see cref="AIContextProviders"/> of successfully completed messages.
    /// </summary>
    /// <remarks>
-    /// This method is also called by <see cref="ServiceStoredSimulatingChatClient"/> to persist messages per-service-call.
+    /// This method is also called by <see cref="PerServiceCallChatHistoryPersistingChatClient"/> to persist messages per-service-call.
    /// </remarks>
    internal async Task NotifyProvidersOfNewMessagesAsync(
        ChatClientAgentSession session,
@@ -486,7 +486,7 @@ public sealed partial class ChatClientAgent : AIAgent
    /// Notifies the <see cref="ChatHistoryProvider"/> and all <see cref="AIContextProviders"/> of a failure during a service call.
    /// </summary>
    /// <remarks>
-    /// This method is also called by <see cref="ServiceStoredSimulatingChatClient"/> to report failures per-service-call.
+    /// This method is also called by <see cref="PerServiceCallChatHistoryPersistingChatClient"/> to report failures per-service-call.
    /// </remarks>
    internal async Task NotifyProvidersOfFailureAsync(
        ChatClientAgentSession session,
@@ -701,7 +701,7 @@ public sealed partial class ChatClientAgent : AIAgent
            throw new InvalidOperationException("A session must be provided when continuing a background response with a continuation token.");
        }

-        if ((continuationToken is not null || chatOptions?.AllowBackgroundResponses is true) && this.SimulatesServiceStoredChatHistory && this._logger.IsEnabled(LogLevel.Warning))
+        if ((continuationToken is not null || chatOptions?.AllowBackgroundResponses is true) && this.RequiresPerServiceCallChatHistoryPersistence && this._logger.IsEnabled(LogLevel.Warning))
        {
            var warningAgentName = this.GetLoggingAgentName();
            this._logger.LogAgentChatClientBackgroundResponseFallback(this.Id, warningAgentName);
@@ -740,10 +740,10 @@ public sealed partial class ChatClientAgent : AIAgent
        IEnumerable<ChatMessage> inputMessagesForChatClient = inputMessages;

        // Populate the session messages only if we are not continuing an existing response as it's not allowed.
-        // When SimulateServiceStoredChatHistory is active, the ServiceStoredSimulatingChatClient
+        // When RequirePerServiceCallChatHistoryPersistence is active, the PerServiceCallChatHistoryPersistingChatClient
        // owns the chat history lifecycle — it loads history before each service call. The agent
        // must not load history itself, as that would result in duplicate messages.
-        if (chatOptions?.ContinuationToken is null && !this.SimulatesServiceStoredChatHistory)
+        if (chatOptions?.ContinuationToken is null && !this.RequiresPerServiceCallChatHistoryPersistence)
        {
            // Add any existing messages from the session to the messages to be sent to the chat client.
            // The ChatHistoryProvider returns the merged result (history + input messages).
@@ -837,14 +837,14 @@ public sealed partial class ChatClientAgent : AIAgent
    /// Updates the session conversation ID at the end of an agent run.
    /// </summary>
    /// <remarks>
-    /// When a <see cref="ServiceStoredSimulatingChatClient"/> handles per-service-call
+    /// When a <see cref="PerServiceCallChatHistoryPersistingChatClient"/> handles per-service-call
    /// conversation ID updates, this end-of-run update is skipped. When the decorator is
    /// absent, the update is performed here. When <paramref name="forceUpdate"/> is <see langword="true"/>
    /// (continuation token scenarios), the update is always performed.
    /// </remarks>
    private void UpdateSessionConversationIdAtEndOfRun(ChatClientAgentSession session, string? responseConversationId, CancellationToken cancellationToken, bool forceUpdate = false)
    {
-        if (!forceUpdate && this.SimulatesServiceStoredChatHistory)
+        if (!forceUpdate && this.RequiresPerServiceCallChatHistoryPersistence)
        {
            return;
        }
@@ -856,7 +856,7 @@ public sealed partial class ChatClientAgent : AIAgent
    /// Notifies providers of successfully completed messages at the end of an agent run.
    /// </summary>
    /// <remarks>
-    /// When a <see cref="ServiceStoredSimulatingChatClient"/> handles per-service-call
+    /// When a <see cref="PerServiceCallChatHistoryPersistingChatClient"/> handles per-service-call
    /// notification, this end-of-run notification is skipped. When no decorator is present,
    /// all messages are persisted.
    /// When <paramref name="forceNotify"/> is <see langword="true"/> (continuation token or
@@ -871,7 +871,7 @@ public sealed partial class ChatClientAgent : AIAgent
        CancellationToken cancellationToken,
        bool forceNotify = false)
    {
-        if (!forceNotify && this.SimulatesServiceStoredChatHistory)
+        if (!forceNotify && this.RequiresPerServiceCallChatHistoryPersistence)
        {
            return Task.CompletedTask;
        }
@@ -883,7 +883,7 @@ public sealed partial class ChatClientAgent : AIAgent
    /// Notifies providers of a failure at the end of an agent run.
    /// </summary>
    /// <remarks>
-    /// When a <see cref="ServiceStoredSimulatingChatClient"/> handles per-service-call
+    /// When a <see cref="PerServiceCallChatHistoryPersistingChatClient"/> handles per-service-call
    /// notification (including failure), this end-of-run notification is skipped to avoid
    /// duplicate notification. In all other cases, failure is reported at the end of the run.
    /// </remarks>
@@ -894,7 +894,7 @@ public sealed partial class ChatClientAgent : AIAgent
        ChatOptions? chatOptions,
        CancellationToken cancellationToken)
    {
-        if (this.SimulatesServiceStoredChatHistory)
+        if (this.RequiresPerServiceCallChatHistoryPersistence)
        {
            return Task.CompletedTask;
        }
@@ -905,14 +905,14 @@ public sealed partial class ChatClientAgent : AIAgent
    /// <summary>
    /// Gets a value indicating whether the agent is configured to simulate service-stored chat history.
    /// When <see langword="true"/>, end-of-run persistence and history loading are skipped because a
-    /// per-service-call decorator (such as <see cref="ServiceStoredSimulatingChatClient"/> or a
+    /// per-service-call decorator (such as <see cref="PerServiceCallChatHistoryPersistingChatClient"/> or a
    /// user-supplied equivalent) is expected to handle the history lifecycle.
    /// </summary>
-    private bool SimulatesServiceStoredChatHistory
+    private bool RequiresPerServiceCallChatHistoryPersistence
    {
        get
        {
-            return this._agentOptions?.SimulateServiceStoredChatHistory is true;
+            return this._agentOptions?.RequirePerServiceCallChatHistoryPersistence is true;
        }
    }

@@ -923,7 +923,7 @@ public sealed partial class ChatClientAgent : AIAgent
    /// The base class sets <see cref="AIAgent.CurrentRunContext"/> with the raw session parameter
    /// (which may be null) and restores it after each yield in streaming scenarios. After
    /// <see cref="PrepareSessionAndMessagesAsync"/> resolves or creates a session, we update the
-    /// context so the <see cref="ServiceStoredSimulatingChatClient"/> decorator always has a valid session.
+    /// context so the <see cref="PerServiceCallChatHistoryPersistingChatClient"/> decorator always has a valid session.
    /// The original agent from the context is preserved to maintain the top-of-stack agent in
    /// decorated agent scenarios.
    /// </remarks>
@@ -939,19 +939,19 @@ public sealed partial class ChatClientAgent : AIAgent
    /// <summary>
    /// Checks for potential misconfiguration when using a custom chat client stack and logs warnings.
    /// </summary>
-    private void WarnOnMissingServiceStoredSimulatingClient()
+    private void WarnOnMissingPerServiceCallChatHistoryPersistingChatClient()
    {
        if (this._agentOptions?.UseProvidedChatClientAsIs is not true)
        {
            return;
        }

-        if (this._agentOptions?.SimulateServiceStoredChatHistory is not true)
+        if (this._agentOptions?.RequirePerServiceCallChatHistoryPersistence is not true)
        {
            return;
        }

-        var persistingClient = this.ChatClient.GetService<ServiceStoredSimulatingChatClient>();
+        var persistingClient = this.ChatClient.GetService<PerServiceCallChatHistoryPersistingChatClient>();
        if (persistingClient is null && this._logger.IsEnabled(LogLevel.Warning))
        {
            var loggingAgentName = this.GetLoggingAgentName();
@@ -998,7 +998,7 @@ public sealed partial class ChatClientAgent : AIAgent
    /// </summary>
    /// <remarks>
    /// This method is used by both the agent (during <see cref="PrepareSessionAndMessagesAsync"/>) and by
-    /// <see cref="ServiceStoredSimulatingChatClient"/> to load history before each service call.
+    /// <see cref="PerServiceCallChatHistoryPersistingChatClient"/> to load history before each service call.
    /// </remarks>
    internal async Task<IEnumerable<ChatMessage>> LoadChatHistoryAsync(
        ChatClientAgentSession session,
@@ -72,12 +72,12 @@ internal static partial class ChatClientAgentLogMessages

    /// <summary>
    /// Logs a warning when <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="true"/>
-    /// and <see cref="ChatClientAgentOptions.SimulateServiceStoredChatHistory"/> is <see langword="true"/>,
-    /// but no <see cref="ServiceStoredSimulatingChatClient"/> is found in the custom chat client stack.
+    /// and <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> is <see langword="true"/>,
+    /// but no <see cref="PerServiceCallChatHistoryPersistingChatClient"/> is found in the custom chat client stack.
    /// </summary>
    [LoggerMessage(
        Level = LogLevel.Warning,
-        Message = "Agent {AgentId}/{AgentName}: SimulateServiceStoredChatHistory is enabled with a custom chat client stack (UseProvidedChatClientAsIs), but no ServiceStoredSimulatingChatClient was found in the pipeline. Chat history will not be persisted by ChatClientAgent. Consider adding a ServiceStoredSimulatingChatClient to the pipeline using the UseServiceStoredChatHistorySimulation extension method if you have not added your own persistence mechanism.")]
+        Message = "Agent {AgentId}/{AgentName}: RequirePerServiceCallChatHistoryPersistence is enabled with a custom chat client stack (UseProvidedChatClientAsIs), but no PerServiceCallChatHistoryPersistingChatClient was found in the pipeline. Chat history will not be persisted by ChatClientAgent. Consider adding a PerServiceCallChatHistoryPersistingChatClient to the pipeline using the UsePerServiceCallChatHistoryPersistence extension method if you have not added your own persistence mechanism.")]
    public static partial void LogAgentChatClientMissingPersistingClient(
        this ILogger logger,
        string agentId,
@@ -92,7 +92,7 @@ internal static partial class ChatClientAgentLogMessages
    /// </summary>
    [LoggerMessage(
        Level = LogLevel.Warning,
-        Message = "Agent {AgentId}/{AgentName}: SimulateServiceStoredChatHistory is enabled but we have to fall back to end-of-run persistence because the run involves background responses.")]
+        Message = "Agent {AgentId}/{AgentName}: RequirePerServiceCallChatHistoryPersistence is enabled but we have to fall back to end-of-run persistence because the run involves background responses.")]
    public static partial void LogAgentChatClientBackgroundResponseFallback(
        this ILogger logger,
        string agentId,
@@ -92,38 +92,56 @@ public sealed class ChatClientAgentOptions
    public bool ThrowOnChatHistoryProviderConflict { get; set; } = true;

    /// <summary>
-    /// Gets or sets a value indicating whether the <see cref="ChatClientAgent"/> should simulate
-    /// service-stored chat history behavior using its configured <see cref="ChatHistoryProvider"/>.
+    /// Gets or sets a value indicating whether the <see cref="ChatClientAgent"/> should persist
+    /// chat history after each individual service call within the <see cref="FunctionInvokingChatClient"/>
+    /// loop, rather than at the end of the full agent run.
    /// </summary>
    /// <remarks>
    /// <para>
-    /// When set to <see langword="true"/>, a <see cref="ServiceStoredSimulatingChatClient"/> decorator is
-    /// injected between the <see cref="FunctionInvokingChatClient"/> and the leaf <see cref="IChatClient"/>
-    /// in the chat client pipeline. This decorator takes full ownership of the chat history lifecycle:
-    /// it loads history from the <see cref="ChatHistoryProvider"/> before each service call and persists
-    /// new messages after each service call. It also returns a sentinel <see cref="ChatOptions.ConversationId"/>
-    /// on the response, causing the <see cref="FunctionInvokingChatClient"/> to treat the conversation
-    /// as service-managed — clearing accumulated history and not injecting duplicate
-    /// <see cref="FunctionCallContent"/> during approval-response processing.
-    /// </para>
-    /// <para>
-    /// This mode aligns the behavior of framework-managed chat history with service-stored chat history,
-    /// ensuring consistency in how messages are stored and loaded, including during function calling loops
-    /// and tool-call termination scenarios.
+    /// When set to <see langword="true"/>, a <see cref="PerServiceCallChatHistoryPersistingChatClient"/>
+    /// decorator becomes active in the chat client pipeline. It handles two complementary scenarios:
    /// </para>
+    /// <list type="bullet">
+    /// <item>
+    /// <term>Framework-managed chat history</term>
+    /// <description>
+    /// The decorator loads history from the <see cref="ChatHistoryProvider"/> before each service call
+    /// and persists new request and response messages after each call. It returns a sentinel
+    /// <see cref="ChatOptions.ConversationId"/> on the response, causing the
+    /// <see cref="FunctionInvokingChatClient"/> to treat the conversation as service-managed — clearing
+    /// accumulated history between iterations and not injecting duplicate <see cref="FunctionCallContent"/>
+    /// during approval-response processing.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <term>AI Service-stored chat history</term>
+    /// <description>
+    /// When the service manages its own chat history (returning a real <see cref="ChatOptions.ConversationId"/>),
+    /// the decorator updates <see cref="ChatClientAgentSession.ConversationId"/> after each service call so
+    /// that intermediate ConversationId changes are captured immediately. For some services (e.g., the
+    /// Conversations API with the Responses API), there is only one thread with one ID, so every service
+    /// call updates it anyway and updating the <see cref="ChatClientAgentSession.ConversationId"/> has little effect
+    /// since it's the same ID. For other services (e.g., Responses API with Response IDs), a new ID is generated
+    /// with each service call, so updating the <see cref="ChatClientAgentSession.ConversationId"/> ensures that the
+    /// latest ID is always captured, even mid-run.
+    /// Enabling this option ensures consistent per-service-call behavior across all service types.
+    /// </description>
+    /// </item>
+    /// </list>
    /// <para>
    /// When set to <see langword="false"/> (the default), the <see cref="ChatClientAgent"/> handles
-    /// chat history persistence at the end of the full agent run via the <see cref="ChatHistoryProvider"/>
-    /// pipeline.
+    /// chat history persistence at the end of the full agent run via the <see cref="ChatHistoryProvider"/> if using
+    /// framework-managed chat history. For AI service-stored chat history, the <see cref="ChatClientAgentSession.ConversationId"/>
+    /// updates happen only at the end of the run.
    /// </para>
    /// <para>
    /// When setting the <see cref="UseProvidedChatClientAsIs"/> setting to <see langword="true"/> and
-    /// <see cref="SimulateServiceStoredChatHistory"/> to <see langword="true"/>, ensure that your custom chat client stack includes a
-    /// <see cref="ServiceStoredSimulatingChatClient"/> to enable per-service-call persistence.
-    /// If no <see cref="ServiceStoredSimulatingChatClient"/> is provided, and you are not storing chat history via other means,
+    /// <see cref="RequirePerServiceCallChatHistoryPersistence"/> to <see langword="true"/>, ensure that your custom chat client stack includes a
+    /// <see cref="PerServiceCallChatHistoryPersistingChatClient"/> to enable per-service-call persistence.
+    /// If no <see cref="PerServiceCallChatHistoryPersistingChatClient"/> is provided, and you are not storing chat history via other means,
    /// no chat history may be stored.
-    /// When using a custom chat client stack, you can add a <see cref="ServiceStoredSimulatingChatClient"/>
-    /// manually via the <see cref="ChatClientBuilderExtensions.UseServiceStoredChatHistorySimulation"/>
+    /// When using a custom chat client stack, you can add a <see cref="PerServiceCallChatHistoryPersistingChatClient"/>
+    /// manually via the <see cref="ChatClientBuilderExtensions.UsePerServiceCallChatHistoryPersistence"/>
    /// extension method.
    /// </para>
    /// </remarks>
@@ -131,7 +149,7 @@ public sealed class ChatClientAgentOptions
    /// Default is <see langword="false"/>.
    /// </value>
    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-    public bool SimulateServiceStoredChatHistory { get; set; }
+    public bool RequirePerServiceCallChatHistoryPersistence { get; set; }

    /// <summary>
    /// Creates a new instance of <see cref="ChatClientAgentOptions"/> with the same values as this instance.
@@ -149,6 +167,6 @@ public sealed class ChatClientAgentOptions
            ClearOnChatHistoryProviderConflict = this.ClearOnChatHistoryProviderConflict,
            WarnOnChatHistoryProviderConflict = this.WarnOnChatHistoryProviderConflict,
            ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,
-            SimulateServiceStoredChatHistory = this.SimulateServiceStoredChatHistory,
+            RequirePerServiceCallChatHistoryPersistence = this.RequirePerServiceCallChatHistoryPersistence,
        };
 }
@@ -86,21 +86,21 @@ public static class ChatClientBuilderExtensions
            services: services);

    /// <summary>
-    /// Adds a <see cref="ServiceStoredSimulatingChatClient"/> to the chat client pipeline.
+    /// Adds a <see cref="PerServiceCallChatHistoryPersistingChatClient"/> to the chat client pipeline.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This decorator should be positioned between the <see cref="FunctionInvokingChatClient"/> and the leaf
-    /// <see cref="IChatClient"/> in the pipeline. It simulates service-stored chat history behavior by
-    /// loading history before each service call, persisting after each call, and returning a sentinel
-    /// <see cref="ChatOptions.ConversationId"/> on the response.
+    /// <see cref="IChatClient"/> in the pipeline. It persists chat history after each individual service call
+    /// and updates the session <see cref="ChatOptions.ConversationId"/> per call for both framework-managed
+    /// and service-stored chat history scenarios.
    /// </para>
    /// <para>
    /// This extension method is intended for use with custom chat client stacks when
    /// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="true"/>.
    /// When <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="false"/> (the default),
-    /// the <see cref="ChatClientAgent"/> automatically injects this decorator when
-    /// <see cref="ChatClientAgentOptions.SimulateServiceStoredChatHistory"/> is <see langword="true"/>.
+    /// the <see cref="ChatClientAgent"/> automatically includes this decorator in the pipeline and activates it when
+    /// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> is <see langword="true"/>.
    /// </para>
    /// <para>
    /// This decorator only works within the context of a running <see cref="ChatClientAgent"/> and will throw an
@@ -110,8 +110,8 @@ public static class ChatClientBuilderExtensions
    /// <param name="builder">The <see cref="ChatClientBuilder"/> to add the decorator to.</param>
    /// <returns>The <paramref name="builder"/> for chaining.</returns>
    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-    public static ChatClientBuilder UseServiceStoredChatHistorySimulation(this ChatClientBuilder builder)
+    public static ChatClientBuilder UsePerServiceCallChatHistoryPersistence(this ChatClientBuilder builder)
    {
-        return builder.Use(innerClient => new ServiceStoredSimulatingChatClient(innerClient));
+        return builder.Use(innerClient => new PerServiceCallChatHistoryPersistingChatClient(innerClient));
    }
 }
@@ -63,16 +63,16 @@ public static class ChatClientExtensions
            });
        }

-        // ServiceStoredSimulatingChatClient is only injected when SimulateServiceStoredChatHistory is enabled.
+        // PerServiceCallChatHistoryPersistingChatClient is only injected when RequirePerServiceCallChatHistoryPersistence is enabled.
        // It is registered after FunctionInvokingChatClient so that it sits between FIC and the leaf client.
        // ChatClientBuilder.Build applies factories in reverse order, making the first Use() call outermost.
        // By adding our decorator second, the resulting pipeline is:
-        //   FunctionInvokingChatClient → ServiceStoredSimulatingChatClient → leaf IChatClient
+        //   FunctionInvokingChatClient → PerServiceCallChatHistoryPersistingChatClient → leaf IChatClient
        // This allows the decorator to simulate service-stored chat history by loading history before
        // each service call, persisting after each call, and returning a sentinel ConversationId.
-        if (options?.SimulateServiceStoredChatHistory is true)
+        if (options?.RequirePerServiceCallChatHistoryPersistence is true)
        {
-            chatBuilder.Use(innerClient => new ServiceStoredSimulatingChatClient(innerClient));
+            chatBuilder.Use(innerClient => new PerServiceCallChatHistoryPersistingChatClient(innerClient));
        }

        var agentChatClient = chatBuilder.Build(services);
@@ -11,23 +11,39 @@ using Microsoft.Extensions.AI;
 namespace Microsoft.Agents.AI;

 /// <summary>
-/// A delegating chat client that simulates service-stored chat history behavior using
-/// framework-managed <see cref="ChatHistoryProvider"/> instances.
+/// A delegating chat client that persists chat history and updates session state after each
+/// individual service call within the <see cref="FunctionInvokingChatClient"/> loop.
 /// </summary>
 /// <remarks>
 /// <para>
 /// This decorator is intended to operate between the <see cref="FunctionInvokingChatClient"/> and the leaf
-/// <see cref="IChatClient"/> in a <see cref="ChatClientAgent"/> pipeline.
+/// <see cref="IChatClient"/> in a <see cref="ChatClientAgent"/> pipeline. It is activated when
+/// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> is <see langword="true"/>.
 /// </para>
 /// <para>
-/// Before each service call, it loads chat history from the agent's <see cref="ChatHistoryProvider"/>
-/// and prepends it to the request messages. After each successful service call, it persists
-/// new request and response messages to the provider. It also returns a sentinel
-/// <see cref="ChatOptions.ConversationId"/> on the response so that the
-/// <see cref="FunctionInvokingChatClient"/> treats the conversation as service-managed —
-/// clearing accumulated history between iterations and not injecting duplicate
-/// <see cref="FunctionCallContent"/> during approval-response processing.
+/// When active, it handles two complementary scenarios:
 /// </para>
+/// <list type="bullet">
+/// <item>
+/// <term>Framework-managed chat history</term>
+/// <description>
+/// Before each service call, the decorator loads history from the agent's <see cref="ChatHistoryProvider"/>
+/// and prepends it to the request messages. After each successful call, it persists new messages to
+/// the provider and returns a sentinel <see cref="ChatOptions.ConversationId"/> so that
+/// <see cref="FunctionInvokingChatClient"/> treats the conversation as service-managed — clearing
+/// accumulated history between iterations and not injecting duplicate <see cref="FunctionCallContent"/>
+/// during approval-response processing.
+/// </description>
+/// </item>
+/// <item>
+/// <term>Service-stored chat history</term>
+/// <description>
+/// When the underlying service manages its own chat history (real <see cref="ChatOptions.ConversationId"/>),
+/// the decorator updates <see cref="ChatClientAgentSession.ConversationId"/> after each service call so
+/// that intermediate ConversationId changes are captured immediately rather than only at the end of the run.
+/// </description>
+/// </item>
+/// </list>
 /// <para>
 /// This chat client must be used within the context of a running <see cref="ChatClientAgent"/>. It retrieves the
 /// current agent and session from <see cref="AIAgent.CurrentRunContext"/>, which is set automatically when an agent's
@@ -38,7 +54,7 @@ namespace Microsoft.Agents.AI;
 /// available or if the agent is not a <see cref="ChatClientAgent"/>.
 /// </para>
 /// </remarks>
-internal sealed class ServiceStoredSimulatingChatClient : DelegatingChatClient
+internal sealed class PerServiceCallChatHistoryPersistingChatClient : DelegatingChatClient
 {
    /// <summary>
    /// A sentinel value returned on <see cref="ChatResponse.ConversationId"/> to signal
@@ -59,10 +75,10 @@ internal sealed class ServiceStoredSimulatingChatClient : DelegatingChatClient
    internal const string LocalHistoryConversationId = "_agent_local_chat_history";

    /// <summary>
-    /// Initializes a new instance of the <see cref="ServiceStoredSimulatingChatClient"/> class.
+    /// Initializes a new instance of the <see cref="PerServiceCallChatHistoryPersistingChatClient"/> class.
    /// </summary>
    /// <param name="innerClient">The underlying chat client that will handle the core operations.</param>
-    public ServiceStoredSimulatingChatClient(IChatClient innerClient)
+    public PerServiceCallChatHistoryPersistingChatClient(IChatClient innerClient)
        : base(innerClient)
    {
    }
@@ -237,18 +253,18 @@ internal sealed class ServiceStoredSimulatingChatClient : DelegatingChatClient
    {
        var runContext = AIAgent.CurrentRunContext
            ?? throw new InvalidOperationException(
-                $"{nameof(ServiceStoredSimulatingChatClient)} can only be used within the context of a running AIAgent. " +
+                $"{nameof(PerServiceCallChatHistoryPersistingChatClient)} can only be used within the context of a running AIAgent. " +
                "Ensure that the chat client is being invoked as part of an AIAgent.RunAsync or AIAgent.RunStreamingAsync call.");

        var chatClientAgent = runContext.Agent.GetService<ChatClientAgent>()
            ?? throw new InvalidOperationException(
-                $"{nameof(ServiceStoredSimulatingChatClient)} can only be used with a {nameof(ChatClientAgent)}. " +
+                $"{nameof(PerServiceCallChatHistoryPersistingChatClient)} can only be used with a {nameof(ChatClientAgent)}. " +
                $"The current agent is of type '{runContext.Agent.GetType().Name}'.");

        if (runContext.Session is not ChatClientAgentSession chatClientAgentSession)
        {
            throw new InvalidOperationException(
-                $"{nameof(ServiceStoredSimulatingChatClient)} requires a {nameof(ChatClientAgentSession)}. " +
+                $"{nameof(PerServiceCallChatHistoryPersistingChatClient)} requires a {nameof(ChatClientAgentSession)}. " +
                $"The current session is of type '{runContext.Session?.GetType().Name ?? "null"}'.");
        }

@@ -14,7 +14,7 @@ namespace Microsoft.Agents.AI.UnitTests;

 /// <summary>
 /// Shared test helper for <see cref="ChatClientAgent"/> integration tests that verify
-/// end-to-end behavior with <see cref="ServiceStoredSimulatingChatClient"/> and
+/// end-to-end behavior with <see cref="PerServiceCallChatHistoryPersistingChatClient"/> and
 /// <see cref="FunctionInvokingChatClient"/>.
 /// </summary>
 internal static class ChatClientAgentTestHelper
@@ -9,7 +9,7 @@ namespace Microsoft.Agents.AI.UnitTests;

 /// <summary>
 /// Contains unit tests that verify the end-to-end approval flow behavior of the
-/// <see cref="ChatClientAgent"/> class with <see cref="ServiceStoredSimulatingChatClient"/>,
+/// <see cref="ChatClientAgent"/> class with <see cref="PerServiceCallChatHistoryPersistingChatClient"/>,
 /// ensuring that chat history is correctly persisted across multi-turn approval interactions.
 /// </summary>
 public class ChatClientAgent_ApprovalsTests
@@ -48,7 +48,7 @@ public class ChatClientAgent_ApprovalsTests
            agentOptions: new()
            {
                ChatOptions = new() { Tools = [approvalTool] },
-                SimulateServiceStoredChatHistory = true,
+                RequirePerServiceCallChatHistoryPersistence = true,
            },
            callIndex: callIndex,
            capturedInputs: capturedInputs);
@@ -260,7 +260,7 @@ public class ChatClientAgent_ApprovalsTests
            agentOptions: new()
            {
                ChatOptions = new() { Tools = [approvalTool] },
-                SimulateServiceStoredChatHistory = true,
+                RequirePerServiceCallChatHistoryPersistence = true,
            },
            callIndex: callIndex,
            capturedInputs: capturedInputs);
@@ -520,7 +520,7 @@ public class ChatClientAgent_ChatHistoryManagementTests
            agentOptions: new()
            {
                ChatOptions = new() { Instructions = "Be helpful" },
-                SimulateServiceStoredChatHistory = true,
+                RequirePerServiceCallChatHistoryPersistence = true,
            },
            expectedServiceCallCount: 1,
            expectedHistory:
@@ -554,7 +554,7 @@ public class ChatClientAgent_ChatHistoryManagementTests
            agentOptions: new()
            {
                ChatOptions = new() { Tools = [tool] },
-                SimulateServiceStoredChatHistory = true,
+                RequirePerServiceCallChatHistoryPersistence = true,
            },
            expectedServiceCallCount: 2,
            expectedHistory:
@@ -13,15 +13,15 @@ using Moq.Protected;
 namespace Microsoft.Agents.AI.UnitTests;

 /// <summary>
-/// Contains unit tests for the <see cref="ServiceStoredSimulatingChatClient"/> decorator,
+/// Contains unit tests for the <see cref="PerServiceCallChatHistoryPersistingChatClient"/> decorator,
 /// verifying that it persists messages via the <see cref="ChatHistoryProvider"/> after each
 /// individual service call by default, or marks messages for end-of-run persistence when the
-/// <see cref="ChatClientAgentOptions.SimulateServiceStoredChatHistory"/> option is enabled.
+/// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> option is enabled.
 /// </summary>
-public class ServiceStoredSimulatingChatClientTests
+public class PerServiceCallChatHistoryPersistingChatClientTests
 {
    /// <summary>
-    /// Verifies that by default (SimulateServiceStoredChatHistory is false),
+    /// Verifies that by default (RequirePerServiceCallChatHistoryPersistence is false),
    /// the ChatHistoryProvider receives messages after a successful non-streaming call.
    /// </summary>
    [Fact]
@@ -50,7 +50,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -97,7 +97,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -145,7 +145,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -163,7 +163,7 @@ public class ServiceStoredSimulatingChatClientTests
    }

    /// <summary>
-    /// Verifies that the decorator is NOT injected by default (SimulateServiceStoredChatHistory is false).
+    /// Verifies that the decorator is NOT injected by default (RequirePerServiceCallChatHistoryPersistence is false).
    /// </summary>
    [Fact]
    public void ChatClient_DoesNotContainDecorator_ByDefault()
@@ -175,15 +175,15 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new());

        // Assert
-        var decorator = agent.ChatClient.GetService<ServiceStoredSimulatingChatClient>();
+        var decorator = agent.ChatClient.GetService<PerServiceCallChatHistoryPersistingChatClient>();
        Assert.Null(decorator);
    }

    /// <summary>
-    /// Verifies that the decorator is injected when SimulateServiceStoredChatHistory is true.
+    /// Verifies that the decorator is injected when RequirePerServiceCallChatHistoryPersistence is true.
    /// </summary>
    [Fact]
-    public void ChatClient_ContainsDecorator_WhenSimulateServiceStoredChatHistory()
+    public void ChatClient_ContainsDecorator_WhenRequirePerServiceCallChatHistoryPersistence()
    {
        // Arrange
        Mock<IChatClient> mockService = new();
@@ -191,11 +191,11 @@ public class ServiceStoredSimulatingChatClientTests
        // Act
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Assert
-        var decorator = agent.ChatClient.GetService<ServiceStoredSimulatingChatClient>();
+        var decorator = agent.ChatClient.GetService<PerServiceCallChatHistoryPersistingChatClient>();
        Assert.NotNull(decorator);
    }

@@ -215,27 +215,27 @@ public class ServiceStoredSimulatingChatClientTests
        });

        // Assert
-        var decorator = agent.ChatClient.GetService<ServiceStoredSimulatingChatClient>();
+        var decorator = agent.ChatClient.GetService<PerServiceCallChatHistoryPersistingChatClient>();
        Assert.Null(decorator);
    }

    /// <summary>
-    /// Verifies that the SimulateServiceStoredChatHistory option is included in Clone().
+    /// Verifies that the RequirePerServiceCallChatHistoryPersistence option is included in Clone().
    /// </summary>
    [Fact]
-    public void ChatClientAgentOptions_Clone_IncludesSimulateServiceStoredChatHistory()
+    public void ChatClientAgentOptions_Clone_IncludesRequirePerServiceCallChatHistoryPersistence()
    {
        // Arrange
        var options = new ChatClientAgentOptions
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        };

        // Act
        var cloned = options.Clone();

        // Assert
-        Assert.True(cloned.SimulateServiceStoredChatHistory);
+        Assert.True(cloned.RequirePerServiceCallChatHistoryPersistence);
    }

    /// <summary>
@@ -289,7 +289,7 @@ public class ServiceStoredSimulatingChatClientTests
        {
            ChatOptions = new() { Tools = [tool] },
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        }, services: new ServiceCollection().BuildServiceProvider());

        // Act
@@ -358,7 +358,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -407,7 +407,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            AIContextProviders = [mockContextProvider.Object],
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -454,7 +454,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            AIContextProviders = [mockContextProvider.Object],
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -513,7 +513,7 @@ public class ServiceStoredSimulatingChatClientTests
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
            AIContextProviders = [mockContextProvider.Object],
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -587,7 +587,7 @@ public class ServiceStoredSimulatingChatClientTests
        {
            ChatOptions = new() { Tools = [tool] },
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        }, services: new ServiceCollection().BuildServiceProvider());

        // Act
@@ -652,7 +652,7 @@ public class ServiceStoredSimulatingChatClientTests
        {
            ChatOptions = new() { Tools = [tool] },
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        }, services: new ServiceCollection().BuildServiceProvider());

        // Act
@@ -720,8 +720,8 @@ public class ServiceStoredSimulatingChatClientTests

    /// <summary>
    /// Verifies that when per-service-call persistence is active and no real conversation ID exists,
-    /// <see cref="ChatClientAgent"/> sets the <see cref="ServiceStoredSimulatingChatClient.LocalHistoryConversationId"/>
-    /// sentinel on the chat options and <see cref="ServiceStoredSimulatingChatClient"/> strips it before
+    /// <see cref="ChatClientAgent"/> sets the <see cref="PerServiceCallChatHistoryPersistingChatClient.LocalHistoryConversationId"/>
+    /// sentinel on the chat options and <see cref="PerServiceCallChatHistoryPersistingChatClient"/> strips it before
    /// forwarding to the inner client.
    /// </summary>
    [Fact]
@@ -741,7 +741,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatOptions = new() { Instructions = "test" },
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -773,7 +773,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatOptions = new() { Instructions = "test" },
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -808,7 +808,7 @@ public class ServiceStoredSimulatingChatClientTests

        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Create a session with a real conversation ID.
@@ -842,7 +842,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatOptions = new() { Instructions = "test" },
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -862,7 +862,7 @@ public class ServiceStoredSimulatingChatClientTests
    /// skip provider resolution in the agent (the decorator handles it).
    /// </summary>
    [Fact]
-    public async Task RunAsync_SetsSentinelOnSession_WhenSimulateServiceStoredChatHistoryActiveAsync()
+    public async Task RunAsync_SetsSentinelOnSession_WhenRequirePerServiceCallChatHistoryPersistenceActiveAsync()
    {
        // Arrange
        Mock<IChatClient> mockService = new();
@@ -875,7 +875,7 @@ public class ServiceStoredSimulatingChatClientTests

        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -883,7 +883,7 @@ public class ServiceStoredSimulatingChatClientTests
        await agent.RunAsync([new(ChatRole.User, "test")], session);

        // Assert — session should have the sentinel conversation ID
-        Assert.Equal(ServiceStoredSimulatingChatClient.LocalHistoryConversationId, session!.ConversationId);
+        Assert.Equal(PerServiceCallChatHistoryPersistingChatClient.LocalHistoryConversationId, session!.ConversationId);
    }

    /// <summary>
@@ -924,7 +924,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act & Assert — conflict detection should throw
@@ -969,7 +969,7 @@ public class ServiceStoredSimulatingChatClientTests

        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
            AIContextProviders = [mockContextProvider.Object],
        });

@@ -1025,7 +1025,7 @@ public class ServiceStoredSimulatingChatClientTests

        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
            AIContextProviders = [mockContextProvider.Object],
        });

@@ -1077,7 +1077,7 @@ public class ServiceStoredSimulatingChatClientTests

        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
            AIContextProviders = [mockContextProvider.Object],
        });

@@ -1137,7 +1137,7 @@ public class ServiceStoredSimulatingChatClientTests
        // No ChatHistoryProvider — so conflict detection won't throw.
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
            AIContextProviders = [mockContextProvider.Object],
        });

@@ -1192,7 +1192,7 @@ public class ServiceStoredSimulatingChatClientTests
        // No ChatHistoryProvider — so conflict detection won't throw.
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
            AIContextProviders = [mockContextProvider.Object],
        });

@@ -1253,7 +1253,7 @@ public class ServiceStoredSimulatingChatClientTests
        ChatClientAgent agent = new(mockService.Object, options: new()
        {
            ChatHistoryProvider = mockChatHistoryProvider.Object,
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -1270,7 +1270,7 @@ public class ServiceStoredSimulatingChatClientTests
        Assert.Equal("test", messageList[0].Text);

        // Assert — session should NOT have the sentinel (agent handles ConversationId at end-of-run)
-        Assert.NotEqual(ServiceStoredSimulatingChatClient.LocalHistoryConversationId, session!.ConversationId);
+        Assert.NotEqual(PerServiceCallChatHistoryPersistingChatClient.LocalHistoryConversationId, session!.ConversationId);
    }

    /// <summary>
@@ -1291,7 +1291,7 @@ public class ServiceStoredSimulatingChatClientTests

        ChatClientAgent agent = new(mockService.Object, options: new()
        {
-            SimulateServiceStoredChatHistory = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
        });

        // Act
@@ -1309,6 +1309,6 @@ public class ServiceStoredSimulatingChatClientTests
        Assert.NotEmpty(updates);

        // Assert — session should NOT have the sentinel
-        Assert.NotEqual(ServiceStoredSimulatingChatClient.LocalHistoryConversationId, session!.ConversationId);
+        Assert.NotEqual(PerServiceCallChatHistoryPersistingChatClient.LocalHistoryConversationId, session!.ConversationId);
    }
 }
@@ -126,6 +126,13 @@ internal sealed class WorkflowHarness(Workflow workflow, string runId)
                    {
                        hasRequest = true;
                    }
+                    else
+                    {
+                        // This is a republished event for the request we're already responding to
+                        // (emitted by RepublishUnservicedRequestsAsync during checkpoint resume).
+                        // Skip yielding it so downstream code doesn't treat it as a new pending request.
+                        continue;
+                    }
                    break;

                case ConversationUpdateEvent conversationEvent:
@@ -0,0 +1,445 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using FluentAssertions;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.Sample;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+/// <summary>
+/// Regression tests for GH-2485: pending <see cref="RequestInfoEvent"/> objects must be
+/// re-emitted after resuming a workflow from a checkpoint.
+/// </summary>
+public class CheckpointResumeTests
+{
+    /// <summary>
+    /// Verifies that a resumed workflow re-emits <see cref="RequestInfoEvent"/>s for
+    /// pending external requests that existed at the time of the checkpoint.
+    /// </summary>
+    [Theory]
+    [InlineData(ExecutionEnvironment.InProcess_OffThread)]
+    [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
+    internal async Task Checkpoint_Resume_WithPendingRequests_RepublishesRequestInfoEventsAsync(ExecutionEnvironment environment)
+    {
+        // Arrange
+        RequestPort<string, string> requestPort = RequestPort.Create<string, string>("TestPort");
+        ForwardMessageExecutor<string> processor = new("Processor");
+
+        Workflow workflow = new WorkflowBuilder(requestPort)
+            .AddEdge(requestPort, processor)
+            .Build();
+
+        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
+        InProcessExecutionEnvironment env = environment.ToWorkflowExecutionEnvironment();
+
+        // Act 1: Run workflow, collect pending requests and a checkpoint.
+        List<ExternalRequest> originalRequests = [];
+        CheckpointInfo? checkpoint = null;
+
+        await using (StreamingRun firstRun = await env.WithCheckpointing(checkpointManager)
+                                                      .RunStreamingAsync(workflow, "Hello"))
+        {
+            await foreach (WorkflowEvent evt in firstRun.WatchStreamAsync(blockOnPendingRequest: false))
+            {
+                if (evt is RequestInfoEvent requestInfo)
+                {
+                    originalRequests.Add(requestInfo.Request);
+                }
+
+                if (evt is SuperStepCompletedEvent step && step.CompletionInfo?.Checkpoint is { } cp)
+                {
+                    checkpoint = cp;
+                }
+            }
+
+            originalRequests.Should().NotBeEmpty("the workflow should have created at least one external request");
+            checkpoint.Should().NotBeNull("a checkpoint should have been created");
+        }
+
+        // Act 2: Resume from the checkpoint.
+        await using StreamingRun resumed = await env.WithCheckpointing(checkpointManager)
+                                                    .ResumeStreamingAsync(workflow, checkpoint!);
+
+        // Assert: The pending requests should be re-emitted.
+        List<ExternalRequest> reEmittedRequests = [];
+        using CancellationTokenSource cts = new(TimeSpan.FromSeconds(10));
+
+        await foreach (WorkflowEvent evt in resumed.WatchStreamAsync(blockOnPendingRequest: false, cts.Token))
+        {
+            if (evt is RequestInfoEvent requestInfo)
+            {
+                reEmittedRequests.Add(requestInfo.Request);
+            }
+        }
+
+        reEmittedRequests.Should().HaveCount(originalRequests.Count,
+            "all pending requests from the checkpoint should be re-emitted after resume");
+        reEmittedRequests.Select(r => r.RequestId)
+                         .Should().BeEquivalentTo(originalRequests.Select(r => r.RequestId),
+            "the re-emitted request IDs should match the original pending request IDs");
+    }
+
+    /// <summary>
+    /// Verifies that <see cref="RunStatus"/> transitions to <see cref="RunStatus.PendingRequests"/>
+    /// after resuming from a checkpoint with pending external requests (not stuck at NotStarted).
+    /// </summary>
+    [Theory]
+    [InlineData(ExecutionEnvironment.InProcess_OffThread)]
+    [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
+    internal async Task Checkpoint_Resume_WithPendingRequests_RunStatusIsPendingRequestsAsync(ExecutionEnvironment environment)
+    {
+        // Arrange
+        RequestPort<string, string> requestPort = RequestPort.Create<string, string>("TestPort");
+        ForwardMessageExecutor<string> processor = new("Processor");
+
+        Workflow workflow = new WorkflowBuilder(requestPort)
+            .AddEdge(requestPort, processor)
+            .Build();
+
+        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
+        InProcessExecutionEnvironment env = environment.ToWorkflowExecutionEnvironment();
+
+        // First run: collect a checkpoint with pending requests.
+        CheckpointInfo? checkpoint = null;
+
+        await using (StreamingRun firstRun = await env.WithCheckpointing(checkpointManager)
+                                                      .RunStreamingAsync(workflow, "Hello"))
+        {
+            await foreach (WorkflowEvent evt in firstRun.WatchStreamAsync(blockOnPendingRequest: false))
+            {
+                if (evt is SuperStepCompletedEvent step && step.CompletionInfo?.Checkpoint is { } cp)
+                {
+                    checkpoint = cp;
+                }
+            }
+
+            checkpoint.Should().NotBeNull();
+        }
+
+        // Act: Resume from the checkpoint and consume events so the run loop processes.
+        await using StreamingRun resumed = await env.WithCheckpointing(checkpointManager)
+                                                    .ResumeStreamingAsync(workflow, checkpoint!);
+
+        using CancellationTokenSource cts = new(TimeSpan.FromSeconds(10));
+        await foreach (WorkflowEvent _ in resumed.WatchStreamAsync(blockOnPendingRequest: false, cts.Token))
+        {
+            // Consume all events until the stream completes.
+        }
+
+        // Assert
+        RunStatus status = await resumed.GetStatusAsync();
+        status.Should().Be(RunStatus.PendingRequests,
+            "the resumed workflow should report PendingRequests after rehydration");
+    }
+
+    /// <summary>
+    /// Verifies the full roundtrip: resume from checkpoint, observe the re-emitted request,
+    /// send a response, and verify the workflow completes without duplicating the request.
+    /// </summary>
+    [Theory]
+    [InlineData(ExecutionEnvironment.InProcess_OffThread)]
+    [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
+    internal async Task Checkpoint_Resume_RespondToPendingRequest_CompletesWithoutDuplicateAsync(ExecutionEnvironment environment)
+    {
+        // Arrange
+        RequestPort<string, string> requestPort = RequestPort.Create<string, string>("TestPort");
+        ForwardMessageExecutor<string> processor = new("Processor");
+
+        Workflow workflow = new WorkflowBuilder(requestPort)
+            .AddEdge(requestPort, processor)
+            .Build();
+
+        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
+        InProcessExecutionEnvironment env = environment.ToWorkflowExecutionEnvironment();
+
+        // First run: collect checkpoint + pending request.
+        ExternalRequest? pendingRequest = null;
+        CheckpointInfo? checkpoint = null;
+
+        await using (StreamingRun firstRun = await env.WithCheckpointing(checkpointManager)
+                                                      .RunStreamingAsync(workflow, "Hello"))
+        {
+            await foreach (WorkflowEvent evt in firstRun.WatchStreamAsync(blockOnPendingRequest: false))
+            {
+                if (evt is RequestInfoEvent requestInfo)
+                {
+                    pendingRequest = requestInfo.Request;
+                }
+
+                if (evt is SuperStepCompletedEvent step && step.CompletionInfo?.Checkpoint is { } cp)
+                {
+                    checkpoint = cp;
+                }
+            }
+
+            pendingRequest.Should().NotBeNull();
+            checkpoint.Should().NotBeNull();
+        }
+
+        // Act: Resume and respond to the restored request.
+        await using StreamingRun resumed = await env.WithCheckpointing(checkpointManager)
+                                                    .ResumeStreamingAsync(workflow, checkpoint!);
+
+        int requestEventCount = 0;
+
+        using CancellationTokenSource cts = new(TimeSpan.FromSeconds(10));
+
+        // Use blockOnPendingRequest: false for the first pass to see the re-emitted requests.
+        await foreach (WorkflowEvent evt in resumed.WatchStreamAsync(blockOnPendingRequest: false, cts.Token))
+        {
+            if (evt is RequestInfoEvent requestInfo)
+            {
+                requestEventCount++;
+                requestInfo.Request.RequestId.Should().Be(pendingRequest!.RequestId,
+                    "the re-emitted request should match the original");
+            }
+        }
+
+        requestEventCount.Should().Be(1,
+            "the pending request should be emitted exactly once (no duplicates)");
+
+        // Assert intermediate state before responding: the run should be in PendingRequests
+        // and we should have observed the re-emitted request. If the first WatchStreamAsync
+        // didn't complete or yielded nothing, these assertions catch it with a clear message.
+        RunStatus statusBeforeResponse = await resumed.GetStatusAsync();
+        statusBeforeResponse.Should().Be(RunStatus.PendingRequests,
+            "the run should be in PendingRequests state before we send a response");
+
+        // Now send the response and verify the workflow processes it.
+        ExternalResponse response = pendingRequest!.CreateResponse("World");
+        await resumed.SendResponseAsync(response);
+
+        // Consume the resulting events to verify the workflow progresses without errors.
+        List<WorkflowEvent> postResponseEvents = [];
+
+        using CancellationTokenSource cts2 = new(TimeSpan.FromSeconds(10));
+        await foreach (WorkflowEvent evt in resumed.WatchStreamAsync(blockOnPendingRequest: false, cts2.Token))
+        {
+            postResponseEvents.Add(evt);
+        }
+
+        postResponseEvents.Should().NotBeEmpty(
+            "the workflow should process the response and produce events");
+        postResponseEvents.OfType<WorkflowErrorEvent>().Should().BeEmpty(
+            "no errors should occur when processing the restored request's response");
+    }
+
+    /// <summary>
+    /// Verifies that restoring a live run to a checkpoint re-emits pending requests and allows
+    /// the workflow to continue from that restored point.
+    /// </summary>
+    [Theory]
+    [InlineData(ExecutionEnvironment.InProcess_OffThread)]
+    [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
+    internal async Task Checkpoint_Restore_WithPendingRequests_RepublishesRequestInfoEventsAsync(ExecutionEnvironment environment)
+    {
+        // Arrange
+        Workflow workflow = CreateSimpleRequestWorkflow();
+        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
+        InProcessExecutionEnvironment env = environment.ToWorkflowExecutionEnvironment();
+
+        await using StreamingRun run = await env.WithCheckpointing(checkpointManager)
+                                                .RunStreamingAsync(workflow, "Hello");
+
+        (ExternalRequest pendingRequest, CheckpointInfo checkpoint) = await CapturePendingRequestAndCheckpointAsync(run);
+
+        // Advance the run past the checkpoint so the restore has meaningful work to undo.
+        await run.SendResponseAsync(pendingRequest.CreateResponse("World"));
+
+        List<WorkflowEvent> firstCompletionEvents = await ReadToHaltAsync(run);
+        firstCompletionEvents.OfType<WorkflowErrorEvent>().Should().BeEmpty(
+            "the workflow should continue cleanly before we restore");
+        RunStatus statusAfterFirstResponse = await run.GetStatusAsync();
+        statusAfterFirstResponse.Should().Be(RunStatus.Idle,
+            "the workflow should finish processing the first response before we restore");
+
+        // Act
+        await run.RestoreCheckpointAsync(checkpoint);
+
+        // Assert
+        List<WorkflowEvent> restoredEvents = await ReadToHaltAsync(run);
+        ExternalRequest[] replayedRequests = [.. restoredEvents.OfType<RequestInfoEvent>().Select(evt => evt.Request)];
+
+        replayedRequests.Should().ContainSingle("runtime restore should re-emit the restored pending request");
+        replayedRequests[0].RequestId.Should().Be(pendingRequest.RequestId,
+            "the replayed request should match the request captured at the checkpoint");
+
+        await run.SendResponseAsync(replayedRequests[0].CreateResponse("Again"));
+
+        List<WorkflowEvent> secondCompletionEvents = await ReadToHaltAsync(run);
+        secondCompletionEvents.OfType<WorkflowErrorEvent>().Should().BeEmpty(
+            "runtime restore replay should not introduce workflow errors");
+        RunStatus statusAfterRestoreResponse = await run.GetStatusAsync();
+        statusAfterRestoreResponse.Should().Be(RunStatus.Idle,
+            "the workflow should be able to continue after the runtime restore replay");
+    }
+
+    /// <summary>
+    /// Verifies that a resumed parent workflow re-emits pending requests that originated in a subworkflow.
+    /// </summary>
+    [Theory]
+    [InlineData(ExecutionEnvironment.InProcess_OffThread)]
+    [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
+    internal async Task Checkpoint_Resume_SubworkflowWithPendingRequests_RepublishesQualifiedRequestInfoEventsAsync(ExecutionEnvironment environment)
+    {
+        // Arrange
+        Workflow workflow = CreateCheckpointedSubworkflowRequestWorkflow();
+        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
+        InProcessExecutionEnvironment env = environment.ToWorkflowExecutionEnvironment();
+
+        ExternalRequest pendingRequest;
+        CheckpointInfo checkpoint;
+
+        await using (StreamingRun firstRun = await env.WithCheckpointing(checkpointManager)
+                                                      .RunStreamingAsync(workflow, "Hello"))
+        {
+            (pendingRequest, checkpoint) = await CapturePendingRequestAndCheckpointAsync(firstRun);
+        }
+
+        // Act
+        await using StreamingRun resumed = await env.WithCheckpointing(checkpointManager)
+                                                    .ResumeStreamingAsync(workflow, checkpoint);
+
+        // Assert
+        List<WorkflowEvent> resumedEvents = await ReadToHaltAsync(resumed);
+        ExternalRequest[] replayedRequests = [.. resumedEvents.OfType<RequestInfoEvent>().Select(evt => evt.Request)];
+
+        replayedRequests.Should().ContainSingle("the resumed parent workflow should surface the subworkflow request once");
+        replayedRequests[0].RequestId.Should().Be(pendingRequest.RequestId,
+            "the replayed subworkflow request should match the checkpointed request");
+        replayedRequests[0].PortInfo.PortId.Should().Be(pendingRequest.PortInfo.PortId,
+            "the replayed request should remain qualified through the subworkflow boundary");
+
+        await resumed.SendResponseAsync(replayedRequests[0].CreateResponse("World"));
+
+        List<WorkflowEvent> completionEvents = await ReadToHaltAsync(resumed);
+        completionEvents.OfType<RequestInfoEvent>().Should().BeEmpty(
+            "the resumed subworkflow request should not be replayed twice");
+        completionEvents.OfType<WorkflowErrorEvent>().Should().BeEmpty(
+            "subworkflow replay should not introduce workflow errors");
+        RunStatus statusAfterSubworkflowResponse = await resumed.GetStatusAsync();
+        statusAfterSubworkflowResponse.Should().Be(RunStatus.Idle,
+            "the resumed subworkflow should continue after responding to the replayed request");
+    }
+
+    /// <summary>
+    /// Verifies that when <c>republishPendingEvents</c> is <see langword="false"/>,
+    /// no <see cref="RequestInfoEvent"/> is re-emitted after resuming from a checkpoint.
+    /// </summary>
+    [Theory]
+    [InlineData(ExecutionEnvironment.InProcess_OffThread)]
+    [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
+    internal async Task Checkpoint_Resume_WithRepublishDisabled_DoesNotEmitRequestInfoEventsAsync(ExecutionEnvironment environment)
+    {
+        // Arrange
+        RequestPort<string, string> requestPort = RequestPort.Create<string, string>("TestPort");
+        ForwardMessageExecutor<string> processor = new("Processor");
+
+        Workflow workflow = new WorkflowBuilder(requestPort)
+            .AddEdge(requestPort, processor)
+            .Build();
+
+        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
+        InProcessExecutionEnvironment env = environment.ToWorkflowExecutionEnvironment();
+
+        // First run: collect a checkpoint with pending requests.
+        CheckpointInfo? checkpoint = null;
+
+        await using (StreamingRun firstRun = await env.WithCheckpointing(checkpointManager)
+                                                      .RunStreamingAsync(workflow, "Hello"))
+        {
+            await foreach (WorkflowEvent evt in firstRun.WatchStreamAsync(blockOnPendingRequest: false))
+            {
+                if (evt is SuperStepCompletedEvent step && step.CompletionInfo?.Checkpoint is { } cp)
+                {
+                    checkpoint = cp;
+                }
+            }
+
+            checkpoint.Should().NotBeNull();
+        }
+
+        // Act: Resume with republishPendingEvents: false via the internal API.
+        await using StreamingRun resumed = await env.WithCheckpointing(checkpointManager)
+                                                    .ResumeStreamingInternalAsync(workflow, checkpoint!, republishPendingEvents: false);
+
+        // Assert: No RequestInfoEvent should appear in the event stream.
+        int requestEventCount = 0;
+        using CancellationTokenSource cts = new(TimeSpan.FromSeconds(10));
+        await foreach (WorkflowEvent evt in resumed.WatchStreamAsync(blockOnPendingRequest: false, cts.Token))
+        {
+            if (evt is RequestInfoEvent)
+            {
+                requestEventCount++;
+            }
+        }
+
+        requestEventCount.Should().Be(0,
+            "no RequestInfoEvent should be emitted when republishPendingEvents is false");
+    }
+
+    private static Workflow CreateSimpleRequestWorkflow(
+        string requestPortId = "TestPort",
+        string processorId = "Processor")
+    {
+        RequestPort<string, string> requestPort = RequestPort.Create<string, string>(requestPortId);
+        ForwardMessageExecutor<string> processor = new(processorId);
+
+        return new WorkflowBuilder(requestPort)
+            .AddEdge(requestPort, processor)
+            .Build();
+    }
+
+    private static Workflow CreateCheckpointedSubworkflowRequestWorkflow()
+    {
+        ExecutorBinding subworkflow = CreateSimpleRequestWorkflow(
+                requestPortId: "InnerTestPort",
+                processorId: "InnerProcessor")
+            .BindAsExecutor("Subworkflow");
+
+        return new WorkflowBuilder(subworkflow)
+            .AddExternalRequest<string, string>(subworkflow, id: "ForwardedSubworkflowRequest")
+            .Build();
+    }
+
+    private static async ValueTask<(ExternalRequest PendingRequest, CheckpointInfo Checkpoint)> CapturePendingRequestAndCheckpointAsync(StreamingRun run)
+    {
+        ExternalRequest? pendingRequest = null;
+        CheckpointInfo? checkpoint = null;
+
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false))
+        {
+            if (evt is RequestInfoEvent requestInfo)
+            {
+                pendingRequest ??= requestInfo.Request;
+            }
+
+            if (evt is SuperStepCompletedEvent step && step.CompletionInfo?.Checkpoint is { } cp)
+            {
+                checkpoint = cp;
+            }
+        }
+
+        pendingRequest.Should().NotBeNull("the workflow should have emitted a pending request");
+        checkpoint.Should().NotBeNull("the workflow should have produced a checkpoint");
+        return (pendingRequest!, checkpoint!);
+    }
+
+    private static async ValueTask<List<WorkflowEvent>> ReadToHaltAsync(StreamingRun run)
+    {
+        List<WorkflowEvent> events = [];
+        using CancellationTokenSource cts = new(TimeSpan.FromSeconds(10));
+
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false, cts.Token))
+        {
+            events.Add(evt);
+        }
+
+        return events;
+    }
+}
@@ -132,6 +132,53 @@ public class InProcessExecutionTests
            "both versions should produce the same number of agent events");
    }

+    /// <summary>
+    /// This test checks that the logic around waiting for input and halting appropriately works right when the
+    /// workflow runs to halting before the EventStream is watched by the user.
+    /// </summary>
+    [Fact]
+    public async Task RunStreamingAsyncWaitToTakeStreamAsync()
+    {
+        // Arrange: Create a simple agent that responds to messages
+        var agent = new SimpleTestAgent("test-agent");
+        var workflow = AgentWorkflowBuilder.BuildSequential(agent);
+        var inputMessage = new ChatMessage(ChatRole.User, "Hello");
+
+        // Act: Execute using streaming version with TurnToken
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new List<ChatMessage> { inputMessage });
+
+        // Send TurnToken to actually trigger execution (this is the key step)
+        bool messageSent = await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+        messageSent.Should().BeTrue("TurnToken should be accepted");
+
+        while (await run.GetStatusAsync() != RunStatus.Idle)
+        {
+            await Task.Delay(200);
+        }
+
+        // Collect events
+        List<WorkflowEvent> events = [];
+
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            events.Add(evt);
+        }
+
+        // Assert: The workflow should have executed and produced events
+        RunStatus status = await run.GetStatusAsync();
+        status.Should().Be(RunStatus.Idle, "workflow should complete execution");
+
+        events.Should().NotBeEmpty("workflow should produce events during execution");
+
+        // Check that we have agent execution events
+        var agentEvents = events.OfType<AgentResponseUpdateEvent>().ToList();
+        agentEvents.Should().NotBeEmpty("agent should have executed and produced update events");
+
+        // Check that we have output events
+        var outputEvents = events.OfType<WorkflowOutputEvent>().ToList();
+        outputEvents.Should().NotBeEmpty("workflow should produce output events");
+    }
+
    /// <summary>
    /// Simple test agent that echoes back the input message.
    /// </summary>
@@ -1,257 +0,0 @@
-# Source Generator for Workflow Executors: Rationale and Impact
-
-## Overview
-
-The Microsoft Agents AI Workflows framework has introduced a Roslyn source generator (`Microsoft.Agents.AI.Workflows.Generators`) that replaces the previous reflection-based approach for discovering and registering message handlers. This document explains why this change was made, what benefits it provides, and how it impacts framework users.
-
-## Why Move from Reflection to Code Generation?
-
-### The Previous Approach: `ReflectingExecutor<T>`
-
-Previously, executors that needed automatic handler discovery inherited from `ReflectingExecutor<T>` and implemented marker interfaces like `IMessageHandler<TMessage>`:
-
-```csharp
-// Old approach - reflection-based
-public class MyExecutor : ReflectingExecutor<MyExecutor>,
-    IMessageHandler<QueryMessage>,
-    IMessageHandler<CommandMessage, CommandResult>
-{
-    public ValueTask HandleAsync(QueryMessage msg, IWorkflowContext ctx, CancellationToken ct)
-    {
-        // Handle query
-    }
-
-    public ValueTask<CommandResult> HandleAsync(CommandMessage msg, IWorkflowContext ctx, CancellationToken ct)
-    {
-        // Handle command and return result
-    }
-}
-```
-
-This approach had several limitations:
-
-1. **Runtime overhead**: Handler discovery happened at runtime via reflection, adding latency to executor initialization
-2. **No AOT compatibility**: Reflection-based discovery doesn't work with Native AOT compilation
-3. **Redundant declarations**: The interface list duplicated information already present in method signatures
-4. **Limited metadata**: No clean way to declare yield/send types for protocol validation
-5. **Hidden errors**: Invalid handler signatures weren't caught until runtime
-
-### The New Approach: `[MessageHandler]` Attribute
-
-The source generator enables a cleaner, attribute-based pattern:
-
-```csharp
-// New approach - source generated
-[SendsMessage(typeof(PollToken))]
-public partial class MyExecutor : Executor
-{
-    [MessageHandler]
-    private ValueTask HandleQueryAsync(QueryMessage msg, IWorkflowContext ctx, CancellationToken ct)
-    {
-        // Handle query
-    }
-
-    [MessageHandler(Yield = [typeof(StreamChunk)], Send = [typeof(InternalMessage)])]
-    private ValueTask<CommandResult> HandleCommandAsync(CommandMessage msg, IWorkflowContext ctx, CancellationToken ct)
-    {
-        // Handle command and return result
-    }
-}
-```
-
-The generator produces a partial class with `ConfigureRoutes()`, `ConfigureSentTypes()`, and `ConfigureYieldTypes()` implementations at compile time.
-
-## What's Better About Code Generation?
-
-### 1. Compile-Time Validation
-
-Invalid handler signatures are caught during compilation, not at runtime:
-
-```csharp
-[MessageHandler]
-private void InvalidHandler(string msg)  // Error WFGEN005: Missing IWorkflowContext parameter
-{
-}
-```
-
-Diagnostic errors include:
- `WFGEN001`: Handler missing `IWorkflowContext` parameter
- `WFGEN002`: Invalid return type (must be `void`, `ValueTask`, or `ValueTask<T>`)
- `WFGEN003`: Executor class must be `partial`
- `WFGEN004`: `[MessageHandler]` on non-Executor class
- `WFGEN005`: Insufficient parameters
- `WFGEN006`: `ConfigureRoutes` already manually defined
-
-### 2. Zero Runtime Reflection
-
-All handler registration happens at compile time. The generated code is simple, direct method calls:
-
-```csharp
-// Generated code
-protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
-{
-    return routeBuilder
-        .AddHandler<QueryMessage>(this.HandleQueryAsync)
-        .AddHandler<CommandMessage, CommandResult>(this.HandleCommandAsync);
-}
-```
-
-This eliminates:
- Reflection overhead during initialization
- Assembly scanning
- Dynamic delegate creation
-
-### 3. Native AOT Compatibility
-
-Because there's no runtime reflection, executors work seamlessly with .NET Native AOT compilation. This enables:
- Faster startup times
- Smaller deployment sizes
- Deployment to environments that don't support JIT compilation
-
-### 4. Explicit Protocol Metadata
-
-The `Yield` and `Send` properties on `[MessageHandler]` plus class-level `[SendsMessage]` and `[YieldsMessage]` attributes provide explicit protocol documentation:
-
-```csharp
-[SendsMessage(typeof(PollToken))]        // This executor sends PollToken messages
-[YieldsMessage(typeof(FinalResult))]     // This executor yields FinalResult to workflow output
-public partial class MyExecutor : Executor
-{
-    [MessageHandler(
-        Yield = [typeof(StreamChunk)],    // This handler yields StreamChunk
-        Send = [typeof(InternalQuery)])]  // This handler sends InternalQuery
-    private ValueTask HandleAsync(Request req, IWorkflowContext ctx) { ... }
-}
-```
-
-This metadata enables:
- Static protocol validation
- Better IDE tooling and documentation
- Clearer code intent
-
-### 5. Handler Accessibility Freedom
-
-Handlers can be `private`, `protected`, `internal`, or `public`. The old interface-based approach required public methods. Now you can encapsulate handler implementations:
-
-```csharp
-public partial class MyExecutor : Executor
-{
-    [MessageHandler]
-    private ValueTask HandleInternalAsync(InternalMessage msg, IWorkflowContext ctx)
-    {
-        // Private handler - implementation detail
-    }
-}
-```
-
-### 6. Cleaner Inheritance
-
-The generator properly handles inheritance chains, calling `base.ConfigureRoutes()` when appropriate:
-
-```csharp
-public partial class DerivedExecutor : BaseExecutor
-{
-    [MessageHandler]
-    private ValueTask HandleDerivedAsync(DerivedMessage msg, IWorkflowContext ctx) { ... }
-}
-
-// Generated:
-protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
-{
-    routeBuilder = base.ConfigureRoutes(routeBuilder);  // Preserves base handlers
-    return routeBuilder
-        .AddHandler<DerivedMessage>(this.HandleDerivedAsync);
-}
-```
-
-## New Capabilities Enabled
-
-### 1. Static Workflow Analysis
-
-With explicit yield/send metadata, tools can analyze workflow graphs at compile time:
- Validate that all message types have handlers
- Detect unreachable executors
- Generate workflow documentation
-
-### 2. Trimming-Safe Deployments
-
-The generated code contains no reflection, making it fully compatible with IL trimming. This reduces deployment size significantly for serverless and edge scenarios.
-
-### 3. Better IDE Experience
-
-Because the generator runs in the IDE, you get:
- Immediate feedback on handler signature errors
- IntelliSense for generated methods
- Go-to-definition on generated code
-
-### 4. Protocol Documentation Generation
-
-The explicit type metadata can be used to generate:
- API documentation
- OpenAPI/Swagger specs for workflow endpoints
- Visual workflow diagrams
-
-## Impact on Framework Users
-
-### Migration Path
-
-Existing code using `ReflectingExecutor<T>` continues to work but is marked `[Obsolete]`. To migrate:
-
-1. Change base class from `ReflectingExecutor<T>` to `Executor`
-2. Add `partial` modifier to the class
-3. Replace `IMessageHandler<T>` interfaces with `[MessageHandler]` attributes
-4. Optionally add `Yield`/`Send` metadata for protocol validation
-
-**Before:**
-```csharp
-public class MyExecutor : ReflectingExecutor<MyExecutor>, IMessageHandler<Query, Result>
-{
-    public ValueTask<Result> HandleAsync(Query q, IWorkflowContext ctx, CancellationToken ct) { ... }
-}
-```
-
-**After:**
-```csharp
-public partial class MyExecutor : Executor
-{
-    [MessageHandler]
-    private ValueTask<Result> HandleQueryAsync(Query q, IWorkflowContext ctx, CancellationToken ct) { ... }
-}
-```
-
-### Breaking Changes
-
- Classes using `[MessageHandler]` **must** be `partial`
- Handler methods must have at least 2 parameters: `(TMessage, IWorkflowContext)`
- Return type must be `void`, `ValueTask`, or `ValueTask<T>`
-
-### Performance Improvements
-
-Users can expect:
- **Faster executor initialization**: No reflection overhead
- **Reduced memory allocation**: No dynamic delegate creation
- **AOT deployment support**: Full Native AOT compatibility
- **Smaller trimmed deployments**: No reflection metadata preserved
-
-### NuGet Package
-
-The generator is distributed as a separate NuGet package (`Microsoft.Agents.AI.Workflows.Generators`) that's automatically referenced by the main Workflows package. It's packaged as an analyzer, so it:
- Runs automatically during build
- Requires no additional configuration
- Works in all IDEs that support Roslyn analyzers
-
-## Summary
-
-The move from reflection to source generation represents a significant improvement in the Workflows framework:
-
-| Aspect | Reflection (Old) | Source Generator (New) |
-|--------|------------------|------------------------|
-| Handler discovery | Runtime | Compile-time |
-| Error detection | Runtime exceptions | Compiler errors |
-| AOT support | No | Yes |
-| Trimming support | Limited | Full |
-| Protocol metadata | Implicit | Explicit |
-| Handler visibility | Public only | Any |
-| Initialization speed | Slower | Faster |
-
-The source generator approach aligns with modern .NET best practices and positions the framework for future scenarios including edge computing, serverless, and mobile deployments where AOT compilation and minimal footprint are essential.
@@ -1,439 +0,0 @@
-# Source Generator Best Practices Review
-
-This document reviews the Workflow Executor Route Source Generator implementation against the official Roslyn Source Generator Cookbook best practices from the dotnet/roslyn repository.
-
-## Reference Documentation
-
- [Source Generators Cookbook](https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.cookbook.md)
- [Incremental Generators Cookbook](https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.cookbook.md)
-
---
-
-## Executive Summary
-
-| Category | Status | Priority |
-|----------|--------|----------|
-| Generator Type | PASS | - |
-| Attribute-Based Detection | FAIL | HIGH |
-| Model Value Equality | FAIL | HIGH |
-| Collection Equality | FAIL | HIGH |
-| Symbol/SyntaxNode Storage | PASS | - |
-| Code Generation Approach | PASS | - |
-| Diagnostics | PASS | - |
-| Pipeline Efficiency | FAIL | MEDIUM |
-| CancellationToken Handling | PARTIAL | LOW |
-
-**Overall Assessment**: The generator follows several best practices but has critical performance issues that should be addressed before production use. The most significant issue is not using `ForAttributeWithMetadataName`, which the Roslyn team states is "at least 99x more efficient" than `CreateSyntaxProvider`.
-
---
-
-## Detailed Analysis
-
-### 1. Generator Interface Selection
-
-**Best Practice**: Use `IIncrementalGenerator` instead of the deprecated `ISourceGenerator`.
-
-**Our Implementation**: PASS
-
-```csharp
-// ExecutorRouteGenerator.cs:19
-public sealed class ExecutorRouteGenerator : IIncrementalGenerator
-```
-
-The generator correctly implements `IIncrementalGenerator`, the recommended interface for new generators.
-
---
-
-### 2. Attribute-Based Detection with ForAttributeWithMetadataName
-
-**Best Practice**: Use `ForAttributeWithMetadataName()` for attribute-based discovery.
-
-> "This utility method is at least 99x more efficient than `SyntaxProvider.CreateSyntaxProvider`, and in many cases even more efficient."
-> — Roslyn Incremental Generators Cookbook
-
-**Our Implementation**: FAIL (HIGH PRIORITY)
-
-```csharp
-// ExecutorRouteGenerator.cs:25-30
-var executorCandidates = context.SyntaxProvider
-    .CreateSyntaxProvider(
-        predicate: static (node, _) => SyntaxDetector.IsExecutorCandidate(node),
-        transform: static (ctx, ct) => SemanticAnalyzer.Analyze(ctx, ct, out _))
-```
-
-**Problem**: We use `CreateSyntaxProvider` with manual attribute detection in `SyntaxDetector`. This requires the generator to examine every syntax node in the compilation, whereas `ForAttributeWithMetadataName` uses the compiler's built-in attribute index for O(1) lookup.
-
-**Recommended Fix**:
-
-```csharp
-var executorCandidates = context.SyntaxProvider
-    .ForAttributeWithMetadataName(
-        fullyQualifiedMetadataName: "Microsoft.Agents.AI.Workflows.MessageHandlerAttribute",
-        predicate: static (node, _) => node is MethodDeclarationSyntax,
-        transform: static (ctx, ct) => AnalyzeMethodWithAttribute(ctx, ct))
-    .Collect()
-    .SelectMany((methods, _) => GroupByContainingClass(methods));
-```
-
-**Impact**: Current approach causes IDE lag on every keystroke in large projects.
-
---
-
-### 3. Model Value Equality (Records vs Classes)
-
-**Best Practice**: Use `record` types for pipeline models to get automatic value equality.
-
-> "Use `record`s, rather than `class`es, so that value equality is generated for you."
-> — Roslyn Incremental Generators Cookbook
-
-**Our Implementation**: FAIL (HIGH PRIORITY)
-
-```csharp
-// HandlerInfo.cs:28
-internal sealed class HandlerInfo { ... }
-
-// ExecutorInfo.cs:10
-internal sealed class ExecutorInfo { ... }
-```
-
-**Problem**: Both `HandlerInfo` and `ExecutorInfo` are `sealed class` types, which use reference equality by default. The incremental generator caches results based on equality comparison—when the model equals the previous run's model, regeneration is skipped. With reference equality, every analysis produces a "new" object, defeating caching entirely.
-
-**Recommended Fix**:
-
-```csharp
-// HandlerInfo.cs
-internal sealed record HandlerInfo(
-    string MethodName,
-    string InputTypeName,
-    string? OutputTypeName,
-    HandlerSignatureKind SignatureKind,
-    bool HasCancellationToken,
-    EquatableArray<string>? YieldTypes,
-    EquatableArray<string>? SendTypes);
-
-// ExecutorInfo.cs
-internal sealed record ExecutorInfo(
-    string? Namespace,
-    string ClassName,
-    string? GenericParameters,
-    bool IsNested,
-    string ContainingTypeChain,
-    bool BaseHasConfigureRoutes,
-    EquatableArray<HandlerInfo> Handlers,
-    EquatableArray<string> ClassSendTypes,
-    EquatableArray<string> ClassYieldTypes);
-```
-
-**Impact**: Without value equality, the generator regenerates code on every compilation even when nothing changed.
-
---
-
-### 4. Collection Equality
-
-**Best Practice**: Use custom equatable wrappers for collections since `ImmutableArray<T>` uses reference equality.
-
-> "Arrays, `ImmutableArray<T>`, and `List<T>` use reference equality by default. Wrap collections with custom types implementing value-based equality."
-> — Roslyn Incremental Generators Cookbook
-
-**Our Implementation**: FAIL (HIGH PRIORITY)
-
-```csharp
-// ExecutorInfo.cs:46
-public ImmutableArray<HandlerInfo> Handlers { get; }
-
-// HandlerInfo.cs:58-63
-public ImmutableArray<string>? YieldTypes { get; }
-public ImmutableArray<string>? SendTypes { get; }
-```
-
-**Problem**: `ImmutableArray<T>` compares by reference, not by contents. Two arrays with identical elements are considered unequal, breaking incremental caching.
-
-**Recommended Fix**: Create an `EquatableArray<T>` wrapper:
-
-```csharp
-internal readonly struct EquatableArray<T> : IEquatable<EquatableArray<T>>, IEnumerable<T>
-    where T : IEquatable<T>
-{
-    private readonly ImmutableArray<T> _array;
-
-    public EquatableArray(ImmutableArray<T> array) => _array = array;
-
-    public bool Equals(EquatableArray<T> other)
-    {
-        if (_array.Length != other._array.Length) return false;
-        for (int i = 0; i < _array.Length; i++)
-        {
-            if (!_array[i].Equals(other._array[i])) return false;
-        }
-        return true;
-    }
-
-    public override int GetHashCode()
-    {
-        var hash = new HashCode();
-        foreach (var item in _array) hash.Add(item);
-        return hash.ToHashCode();
-    }
-
-    // ... IEnumerable implementation
-}
-```
-
-**Impact**: Same as model equality—caching is completely broken for handlers and type arrays.
-
---
-
-### 5. Symbol and SyntaxNode Storage
-
-**Best Practice**: Never store `ISymbol` or `SyntaxNode` in pipeline models.
-
-> "Storing `ISymbol` references blocks garbage collection and roots old compilations unnecessarily. Extract only the information you need—typically string representations work well—into your equatable models."
-> — Roslyn Incremental Generators Cookbook
-
-**Our Implementation**: PASS
-
-The models correctly store only primitive types and strings:
-
-```csharp
-// HandlerInfo.cs - stores strings, not symbols
-public string MethodName { get; }
-public string InputTypeName { get; }
-public string? OutputTypeName { get; }
-
-// ExecutorInfo.cs - stores strings, not symbols
-public string? Namespace { get; }
-public string ClassName { get; }
-```
-
-The `SemanticAnalyzer` correctly extracts string representations from symbols:
-
-```csharp
-// SemanticAnalyzer.cs:300-301
-var inputType = methodSymbol.Parameters[0].Type;
-var inputTypeName = inputType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
-```
-
---
-
-### 6. Code Generation Approach
-
-**Best Practice**: Use `StringBuilder` for code generation, not `SyntaxNode` construction.
-
-> "Avoid constructing `SyntaxNode`s for output; they're complex to format correctly and `NormalizeWhitespace()` is expensive. Instead, use a `StringBuilder` wrapper that tracks indentation levels."
-> — Roslyn Incremental Generators Cookbook
-
-**Our Implementation**: PASS
-
-```csharp
-// SourceBuilder.cs:17-19
-public static string Generate(ExecutorInfo info)
-{
-    var sb = new StringBuilder();
-```
-
-The `SourceBuilder` correctly uses `StringBuilder` with manual indentation tracking.
-
---
-
-### 7. Diagnostic Reporting
-
-**Best Practice**: Use `ReportDiagnostic` for surfacing issues to users.
-
-**Our Implementation**: PASS
-
-```csharp
-// ExecutorRouteGenerator.cs:44-50
-context.RegisterSourceOutput(diagnosticsProvider, static (ctx, diagnostics) =>
-{
-    foreach (var diagnostic in diagnostics)
-    {
-        ctx.ReportDiagnostic(diagnostic);
-    }
-});
-```
-
-Diagnostics are well-defined with appropriate severities:
-
-| ID | Severity | Description |
-|----|----------|-------------|
-| WFGEN001 | Error | Missing IWorkflowContext parameter |
-| WFGEN002 | Error | Invalid return type |
-| WFGEN003 | Error | Class must be partial |
-| WFGEN004 | Warning | Not an Executor |
-| WFGEN005 | Error | Insufficient parameters |
-| WFGEN006 | Info | ConfigureRoutes already defined |
-| WFGEN007 | Error | Handler cannot be static |
-
---
-
-### 8. Pipeline Efficiency
-
-**Best Practice**: Avoid duplicate work in the pipeline.
-
-**Our Implementation**: FAIL (MEDIUM PRIORITY)
-
-```csharp
-// ExecutorRouteGenerator.cs:25-41
-// Pipeline 1: Get executor candidates
-var executorCandidates = context.SyntaxProvider
-    .CreateSyntaxProvider(
-        predicate: static (node, _) => SyntaxDetector.IsExecutorCandidate(node),
-        transform: static (ctx, ct) => SemanticAnalyzer.Analyze(ctx, ct, out _))
-    ...
-
-// Pipeline 2: Get diagnostics (duplicates the same work!)
-var diagnosticsProvider = context.SyntaxProvider
-    .CreateSyntaxProvider(
-        predicate: static (node, _) => SyntaxDetector.IsExecutorCandidate(node),
-        transform: static (ctx, ct) =>
-        {
-            SemanticAnalyzer.Analyze(ctx, ct, out var diagnostics);
-            return diagnostics;
-        })
-```
-
-**Problem**: The same syntax detection and semantic analysis runs twice—once for extracting `ExecutorInfo` and once for extracting diagnostics.
-
-**Recommended Fix**: Return both in a single pipeline:
-
-```csharp
-var analysisResults = context.SyntaxProvider
-    .ForAttributeWithMetadataName(...)
-    .Select((ctx, ct) => {
-        var info = SemanticAnalyzer.Analyze(ctx, ct, out var diagnostics);
-        return (Info: info, Diagnostics: diagnostics);
-    });
-
-// Split for different outputs
-context.RegisterSourceOutput(
-    analysisResults.Where(r => r.Info != null).Select((r, _) => r.Info!),
-    GenerateSource);
-
-context.RegisterSourceOutput(
-    analysisResults.Where(r => r.Diagnostics.Length > 0).Select((r, _) => r.Diagnostics),
-    ReportDiagnostics);
-```
-
---
-
-### 9. Base Type Chain Scanning
-
-**Best Practice**: Avoid scanning indirect type relationships when possible.
-
-> "Never scan for types that indirectly implement interfaces, inherit from base types, or acquire attributes through inheritance hierarchies. This pattern forces the generator to inspect every type's `AllInterfaces` or base-type chain on every keystroke."
-> — Roslyn Incremental Generators Cookbook
-
-**Our Implementation**: PARTIAL CONCERN
-
-```csharp
-// SemanticAnalyzer.cs:126-141
-private static bool DerivesFromExecutor(INamedTypeSymbol classSymbol)
-{
-    var current = classSymbol.BaseType;
-    while (current != null)
-    {
-        var fullName = current.OriginalDefinition.ToDisplayString();
-        if (fullName == ExecutorTypeName || fullName.StartsWith(ExecutorTypeName + "<", ...))
-        {
-            return true;
-        }
-        current = current.BaseType;
-    }
-    return false;
-}
-```
-
-**Analysis**: We do walk the base type chain, but this only happens after attribute filtering (classes must have `[MessageHandler]` methods). Since this is targeted to specific candidates rather than scanning all types, the performance impact is acceptable. However, if we switch to `ForAttributeWithMetadataName`, the attribute is on methods, so we'd need to check the containing class's base types—which is still targeted.
-
---
-
-### 10. CancellationToken Handling
-
-**Best Practice**: Respect `CancellationToken` in long-running operations.
-
-**Our Implementation**: PARTIAL (LOW PRIORITY)
-
-The `CancellationToken` is passed through to semantic model calls:
-
-```csharp
-// SemanticAnalyzer.cs:46
-var classSymbol = semanticModel.GetDeclaredSymbol(classDecl, cancellationToken);
-```
-
-However, there are no explicit `cancellationToken.ThrowIfCancellationRequested()` calls in loops like `AnalyzeHandlers`. For most compilations this is fine, but very large classes with many handlers might benefit from periodic checks.
-
---
-
-### 11. File Naming Convention
-
-**Best Practice**: Use descriptive generated file names with `.g.cs` suffix.
-
-**Our Implementation**: PASS
-
-```csharp
-// ExecutorRouteGenerator.cs:62-91
-private static string GetHintName(ExecutorInfo info)
-{
-    // Produces: "Namespace.ClassName.g.cs" or "Namespace.Outer.Inner.ClassName.g.cs"
-    ...
-    sb.Append(".g.cs");
-    return sb.ToString();
-}
-```
-
---
-
-## Recommended Action Plan
-
-### High Priority (Performance Critical)
-
-1. **Switch to `ForAttributeWithMetadataName`**
-   - Estimated impact: 99x+ performance improvement for attribute detection
-   - Requires restructuring the pipeline to collect methods then group by class
-
-2. **Convert models to records**
-   - Change `HandlerInfo` and `ExecutorInfo` from `sealed class` to `sealed record`
-   - Enables automatic value equality for incremental caching
-
-3. **Implement `EquatableArray<T>`**
-   - Create wrapper struct with value-based equality
-   - Replace all `ImmutableArray<T>` usages in models
-
-### Medium Priority (Efficiency)
-
-4. **Eliminate duplicate pipeline execution**
-   - Combine info extraction and diagnostic collection into single pipeline
-   - Split outputs using `Where` and `Select`
-
-### Low Priority (Polish)
-
-5. **Add periodic cancellation checks**
-   - Add `ThrowIfCancellationRequested()` in handler analysis loop
-   - Only needed for extremely large classes
-
---
-
-## Compliance Matrix
-
-| Best Practice | Cookbook Reference | Status | Fix Required |
-|--------------|-------------------|--------|--------------|
-| Use IIncrementalGenerator | Main cookbook | PASS | No |
-| Use ForAttributeWithMetadataName | Incremental cookbook | FAIL | Yes (High) |
-| Use records for models | Incremental cookbook | FAIL | Yes (High) |
-| Implement collection equality | Incremental cookbook | FAIL | Yes (High) |
-| Don't store ISymbol/SyntaxNode | Incremental cookbook | PASS | No |
-| Use StringBuilder for codegen | Incremental cookbook | PASS | No |
-| Report diagnostics properly | Main cookbook | PASS | No |
-| Avoid duplicate pipeline work | Incremental cookbook | FAIL | Yes (Medium) |
-| Respect CancellationToken | Main cookbook | PARTIAL | Optional |
-| Use .g.cs file suffix | Main cookbook | PASS | No |
-| Additive-only generation | Main cookbook | PASS | No |
-| No language feature emulation | Main cookbook | PASS | No |
-
---
-
-## Conclusion
-
-The source generator implementation demonstrates solid understanding of Roslyn generator fundamentals—correct interface usage, proper diagnostic reporting, and appropriate code generation patterns. However, critical performance optimizations are missing that could cause significant IDE lag in production environments.
-
-The three high-priority fixes (ForAttributeWithMetadataName, record models, and EquatableArray) should be implemented before the generator is used in large codebases. These changes will enable proper incremental caching, reducing regeneration from "every keystroke" to "only when relevant code changes."
@@ -1,258 +0,0 @@
-# Workflow Executor Route Source Generator - Implementation Summary
-
-This document summarizes all changes made to implement a Roslyn source generator that replaces the reflection-based `ReflectingExecutor<T>` pattern with compile-time code generation using `[MessageHandler]` attributes.
-
-## Overview
-
-The source generator automatically discovers methods marked with `[MessageHandler]` and generates `ConfigureRoutes`, `ConfigureSentTypes`, and `ConfigureYieldTypes` method implementations at compile time. This improves AOT compatibility and eliminates the need for the CRTP (Curiously Recurring Template Pattern) used by `ReflectingExecutor<T>`.
-
-## New Files Created
-
-### Attributes (3 files)
-
-| File | Purpose |
-|------|---------|
-| `src/Microsoft.Agents.AI.Workflows/Attributes/MessageHandlerAttribute.cs` | Marks methods as message handlers with optional `Yield` and `Send` type arrays |
-| `src/Microsoft.Agents.AI.Workflows/Attributes/SendsMessageAttribute.cs` | Class-level attribute declaring message types an executor may send |
-| `src/Microsoft.Agents.AI.Workflows/Attributes/YieldsMessageAttribute.cs` | Class-level attribute declaring output types an executor may yield |
-
-### Source Generator Project (8 files)
-
-| File | Purpose |
-|------|---------|
-| `src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj` | Project file targeting netstandard2.0 with Roslyn component settings |
-| `src/Microsoft.Agents.AI.Workflows.Generators/ExecutorRouteGenerator.cs` | Main incremental generator implementing `IIncrementalGenerator` |
-| `src/Microsoft.Agents.AI.Workflows.Generators/Models/HandlerInfo.cs` | Data model for handler method information |
-| `src/Microsoft.Agents.AI.Workflows.Generators/Models/ExecutorInfo.cs` | Data model for executor class information |
-| `src/Microsoft.Agents.AI.Workflows.Generators/Analysis/SyntaxDetector.cs` | Fast syntax-level candidate detection |
-| `src/Microsoft.Agents.AI.Workflows.Generators/Analysis/SemanticAnalyzer.cs` | Semantic validation and type extraction |
-| `src/Microsoft.Agents.AI.Workflows.Generators/Generation/SourceBuilder.cs` | Code generation logic |
-| `src/Microsoft.Agents.AI.Workflows.Generators/Diagnostics/DiagnosticDescriptors.cs` | Analyzer diagnostic definitions |
-
-## Files Modified
-
-### Project Files
-
-| File | Changes |
-|------|---------|
-| `src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj` | Added generator project reference and `InternalsVisibleTo` for generator tests |
-| `Directory.Packages.props` | Added `Microsoft.CodeAnalysis.Analyzers` version 3.11.0 |
-| `agent-framework-dotnet.slnx` | Added generator project to solution |
-
-### Obsolete Annotations
-
-| File | Changes |
-|------|---------|
-| `src/Microsoft.Agents.AI.Workflows/Reflection/ReflectingExecutor.cs` | Added `[Obsolete]` attribute with migration guidance |
-| `src/Microsoft.Agents.AI.Workflows/Reflection/IMessageHandler.cs` | Added `[Obsolete]` to both `IMessageHandler<T>` and `IMessageHandler<T,TResult>` interfaces |
-
-### Pragma Suppressions for Internal Obsolete Usage
-
-| File | Changes |
-|------|---------|
-| `src/Microsoft.Agents.AI.Workflows/Executor.cs` | Added `#pragma warning disable CS0618` |
-| `src/Microsoft.Agents.AI.Workflows/StatefulExecutor.cs` | Added `#pragma warning disable CS0618` |
-| `src/Microsoft.Agents.AI.Workflows/Reflection/RouteBuilderExtensions.cs` | Added `#pragma warning disable CS0618` |
-| `src/Microsoft.Agents.AI.Workflows/Reflection/MessageHandlerInfo.cs` | Added `#pragma warning disable CS0618` |
-
-### Test File Pragma Suppressions
-
-| File | Changes |
-|------|---------|
-| `tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/01_Simple_Workflow_Sequential.cs` | Added `#pragma warning disable CS0618` for legacy pattern testing |
-| `tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/02_Simple_Workflow_Condition.cs` | Added `#pragma warning disable CS0618` for legacy pattern testing |
-| `tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/03_Simple_Workflow_Loop.cs` | Added `#pragma warning disable CS0618` for legacy pattern testing |
-| `tests/Microsoft.Agents.AI.Workflows.UnitTests/ReflectionSmokeTest.cs` | Added `#pragma warning disable CS0618` for legacy pattern testing |
-
-## Attribute Definitions
-
-### MessageHandlerAttribute
-
-```csharp
-[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false)]
-public sealed class MessageHandlerAttribute : Attribute
-{
-    public Type[]? Yield { get; set; }  // Types yielded as workflow outputs
-    public Type[]? Send { get; set; }   // Types sent to other executors
-}
-```
-
-### SendsMessageAttribute
-
-```csharp
-[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
-public sealed class SendsMessageAttribute : Attribute
-{
-    public Type Type { get; }
-    public SendsMessageAttribute(Type type) => this.Type = Throw.IfNull(type);
-}
-```
-
-### YieldsMessageAttribute
-
-```csharp
-[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
-public sealed class YieldsMessageAttribute : Attribute
-{
-    public Type Type { get; }
-    public YieldsMessageAttribute(Type type) => this.Type = Throw.IfNull(type);
-}
-```
-
-## Diagnostic Rules
-
-| ID | Severity | Description |
-|----|----------|-------------|
-| `WFGEN001` | Error | Handler method must have at least 2 parameters (message and IWorkflowContext) |
-| `WFGEN002` | Error | Handler method's second parameter must be IWorkflowContext |
-| `WFGEN003` | Error | Handler method must return void, ValueTask, or ValueTask<T> |
-| `WFGEN004` | Error | Executor class with [MessageHandler] methods must be declared as partial |
-| `WFGEN005` | Warning | [MessageHandler] attribute on method in non-Executor class (ignored) |
-| `WFGEN006` | Info | ConfigureRoutes already defined manually, [MessageHandler] methods ignored |
-| `WFGEN007` | Error | Handler method's third parameter (if present) must be CancellationToken |
-
-## Handler Signature Support
-
-The generator supports the following method signatures:
-
-| Return Type | Parameters | Generated Call |
-|-------------|------------|----------------|
-| `void` | `(TMessage, IWorkflowContext)` | `AddHandler<TMessage>(this.Method)` |
-| `void` | `(TMessage, IWorkflowContext, CancellationToken)` | `AddHandler<TMessage>(this.Method)` |
-| `ValueTask` | `(TMessage, IWorkflowContext)` | `AddHandler<TMessage>(this.Method)` |
-| `ValueTask` | `(TMessage, IWorkflowContext, CancellationToken)` | `AddHandler<TMessage>(this.Method)` |
-| `TResult` | `(TMessage, IWorkflowContext)` | `AddHandler<TMessage, TResult>(this.Method)` |
-| `TResult` | `(TMessage, IWorkflowContext, CancellationToken)` | `AddHandler<TMessage, TResult>(this.Method)` |
-| `ValueTask<TResult>` | `(TMessage, IWorkflowContext)` | `AddHandler<TMessage, TResult>(this.Method)` |
-| `ValueTask<TResult>` | `(TMessage, IWorkflowContext, CancellationToken)` | `AddHandler<TMessage, TResult>(this.Method)` |
-
-## Generated Code Example
-
-### Input (User Code)
-
-```csharp
-[SendsMessage(typeof(PollToken))]
-public partial class MyChatExecutor : Executor
-{
-    [MessageHandler]
-    private async ValueTask<ChatResponse> HandleQueryAsync(
-        ChatQuery query, IWorkflowContext ctx, CancellationToken ct)
-    {
-        return new ChatResponse(...);
-    }
-
-    [MessageHandler(Yield = new[] { typeof(StreamChunk) }, Send = new[] { typeof(InternalMessage) })]
-    private void HandleStream(StreamRequest req, IWorkflowContext ctx)
-    {
-        // Handler implementation
-    }
-}
-```
-
-### Output (Generated Code)
-
-```csharp
-// <auto-generated/>
-#nullable enable
-
-namespace MyNamespace;
-
-partial class MyChatExecutor
-{
-    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
-    {
-        return routeBuilder
-            .AddHandler<ChatQuery, ChatResponse>(this.HandleQueryAsync)
-            .AddHandler<StreamRequest>(this.HandleStream);
-    }
-
-    protected override ISet<Type> ConfigureSentTypes()
-    {
-        var types = base.ConfigureSentTypes();
-        types.Add(typeof(PollToken));
-        types.Add(typeof(InternalMessage));
-        return types;
-    }
-
-    protected override ISet<Type> ConfigureYieldTypes()
-    {
-        var types = base.ConfigureYieldTypes();
-        types.Add(typeof(ChatResponse));
-        types.Add(typeof(StreamChunk));
-        return types;
-    }
-}
-```
-
-## Build Issues Resolved
-
-### 1. NU1008 - Central Package Management
-Package references in the generator project had inline versions, which conflicts with central package management. Fixed by removing `Version` attributes from `PackageReference` items.
-
-### 2. RS2008 - Analyzer Release Tracking
-Roslyn requires analyzer release tracking documentation. Fixed by adding `<NoWarn>$(NoWarn);RS2008</NoWarn>` to the generator project.
-
-### 3. CA1068 - CancellationToken Parameter Order
-Method parameters were in wrong order. Fixed by reordering `CancellationToken` to be last.
-
-### 4. RCS1146 - Conditional Access
-Used null check with `&&` instead of `?.` operator. Fixed by using conditional access.
-
-### 5. CA1310 - StringComparison
-`StartsWith(string)` calls without `StringComparison`. Fixed by adding `StringComparison.Ordinal`.
-
-### 6. CS0103 - Missing Using Directive
-Missing `using System;` in SemanticAnalyzer.cs. Fixed by adding the using directive.
-
-### 7. CS0618 - Obsolete Warnings as Errors
-Internal uses of obsolete types caused build failures (TreatWarningsAsErrors). Fixed by adding `#pragma warning disable CS0618` to affected internal files and test files.
-
-### 8. NU1109 - Package Version Conflict
-`Microsoft.CodeAnalysis.Analyzers` 3.3.4 conflicts with `Microsoft.CodeAnalysis.CSharp` 4.14.0 which requires >= 3.11.0. Fixed by updating version to 3.11.0 in `Directory.Packages.props`.
-
-### 9. RS1041 - Wrong Target Framework for Analyzer
-The generator was being multi-targeted due to inherited `TargetFrameworks` from `Directory.Build.props`. Fixed by clearing `TargetFrameworks` and only setting `TargetFramework` to `netstandard2.0`.
-
-## Migration Guide
-
-### Before (Reflection-based)
-
-```csharp
-public class MyExecutor : ReflectingExecutor<MyExecutor>, IMessageHandler<MyMessage, MyResult>
-{
-    public MyExecutor() : base("MyExecutor") { }
-
-    public ValueTask<MyResult> HandleAsync(MyMessage message, IWorkflowContext context, CancellationToken ct)
-    {
-        // Handler implementation
-    }
-}
-```
-
-### After (Source Generator)
-
-```csharp
-public partial class MyExecutor : Executor
-{
-    public MyExecutor() : base("MyExecutor") { }
-
-    [MessageHandler]
-    private ValueTask<MyResult> HandleAsync(MyMessage message, IWorkflowContext context, CancellationToken ct)
-    {
-        // Handler implementation
-    }
-}
-```
-
-Key migration steps:
-1. Change base class from `ReflectingExecutor<T>` to `Executor`
-2. Add `partial` modifier to the class
-3. Remove `IMessageHandler<T>` interface implementations
-4. Add `[MessageHandler]` attribute to handler methods
-5. Handler methods can now be any accessibility (private, protected, internal, public)
-
-## Future Work
-
- Create comprehensive unit tests for the source generator
- Add integration tests verifying generated routes match reflection-discovered routes
- Consider adding IDE quick-fix for migrating from `ReflectingExecutor<T>` pattern
@@ -76,7 +76,7 @@ from agent_framework.observability import enable_instrumentation

 # Connectors (lazy-loaded)
 from agent_framework.openai import OpenAIChatClient
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.foundry import FoundryChatClient
 ```

 ## Public API and Exports
@@ -0,0 +1,238 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+---
+name: python-feature-lifecycle
+description: >
+  Guidance for package and feature lifecycle in the Agent Framework Python
+  codebase, including stage meanings, feature-stage decorators, feature enums,
+  and how to move APIs from one stage to the next.
+---
+
+# Python Feature Lifecycle
+
+## Two lifecycle levels
+
+Agent Framework uses lifecycle at two different levels:
+
+1. **Package lifecycle** — the maturity of the package as a whole
+2. **Feature lifecycle** — the maturity of a specific API or feature inside that package
+
+These are related, but they are **not the same thing**.
+
+- The **package stage is the default** for everything in the package.
+- **Feature-stage decorators are only for exceptions** when a feature is behind the package's default stage.
+- Do **not** decorate every class or function just because the package is experimental or release candidate.
+
+### Important default
+
+If a package is still in **beta / experimental preview**, all public APIs in that package are experimental by default.
+
+- Do **not** add `@experimental(...)` everywhere in that package.
+- The package stage already communicates that default.
+
+Once a package moves forward, you can keep individual features behind:
+
+- If a package moves to **release candidate**, a feature may remain **experimental**
+- If a package moves to **released / GA**, a feature may remain **experimental** or **release candidate**
+
+That is the main use case for feature-stage decorators.
+
+## The four stages
+
+### 1. Experimental
+
+Use for features that are still unstable and may change or be removed without notice.
+
+Feature-level code pattern:
+
+```python
+from ._feature_stage import ExperimentalFeature, experimental
+
+
+@experimental(feature_id=ExperimentalFeature.MY_FEATURE)
+class MyFeature:
+    ...
+```
+
+Behavior:
+
+- Adds an experimental warning block to the docstring
+- Records feature metadata on the decorated object
+- Emits a runtime warning the first time the feature is used (once per feature by default)
+
+Enum setup:
+
+- Add an all-caps member to `ExperimentalFeature`
+- Reuse the same feature ID across all APIs that belong to the same conceptual feature
+
+### 2. Release candidate
+
+Use for features that are nearly stable but may still receive small refinements before GA.
+
+Feature-level code pattern:
+
+```python
+from ._feature_stage import ReleaseCandidateFeature, release_candidate
+
+
+@release_candidate(feature_id=ReleaseCandidateFeature.MY_FEATURE)
+class MyFeature:
+    ...
+```
+
+Behavior:
+
+- Adds a release-candidate note to the docstring
+- Records feature metadata on the decorated object
+- Does **not** emit the experimental warning
+
+Enum setup:
+
+- Add an all-caps member to `ReleaseCandidateFeature`
+
+### 3. Released
+
+Use for stable GA APIs.
+
+Code pattern:
+
+- **No feature-stage decorator**
+- **No entry** in `ExperimentalFeature`
+- **No entry** in `ReleaseCandidateFeature`
+
+If a feature is fully released, remove any stage-specific feature annotation.
+
+### 4. Deprecated
+
+Use for APIs that still exist but should not be used for new code.
+
+Code pattern:
+
+```python
+import sys
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import deprecated  # type: ignore # pragma: no cover
+
+
+@deprecated("MyOldFeature is deprecated. Use MyNewFeature instead.")
+class MyOldFeature:
+    ...
+```
+
+Behavior:
+
+- Uses the repository's version-conditional deprecation import pattern
+- Should describe what to use instead
+
+Deprecated APIs should not also carry feature-stage decorators.
+
+## Expected decorators by stage
+
+| Feature stage | Expected annotation |
+| --- | --- |
+| Experimental | `@experimental(feature_id=ExperimentalFeature.X)` |
+| Release candidate | `@release_candidate(feature_id=ReleaseCandidateFeature.X)` |
+| Released | No feature-stage decorator |
+| Deprecated | `@deprecated("...")` |
+
+## Feature enums
+
+The feature enums are the inventory of currently staged features:
+
+- `ExperimentalFeature`
+- `ReleaseCandidateFeature`
+
+Guidance:
+
+- Use one enum member per conceptual feature, not per class
+- Ideally, an ADR already defines the overall feature boundary and therefore the feature ID that staged APIs for that feature should reuse
+- Keep feature IDs all caps
+- Reuse the same member across related APIs for the same feature
+- Remove enum members when the feature no longer belongs to that stage
+- Treat these enums as **current-stage inventories**, not as a stable consumer introspection API
+
+Minimal consumer guidance:
+
+- Treat `__feature_stage__` and `__feature_id__` as optional staged metadata, not as stable contracts
+- Use `getattr(obj, "__feature_stage__", None)` and `getattr(obj, "__feature_id__", None)` rather than direct attribute access
+- Treat missing metadata as "no explicit feature-stage annotation"
+- For warning filters while a feature is staged, match the literal feature ID string
+- Do **not** rely on `ExperimentalFeature.X`, `ReleaseCandidateFeature.X`, or the continued presence of `__feature_id__` after a feature moves stages or is released
+
+For consumers, the enums are also re-exported from `agent_framework`.
+
+For internal implementation code inside `agent_framework`, continue to import the enums and decorators from `._feature_stage`.
+
+## Package stage vs feature stage
+
+Use the following rules:
+
+### Package is experimental / beta
+
+- All public APIs are experimental by default
+- Do **not** add feature-stage decorators just to restate that
+- Only introduce feature-level annotations later if the package advances first
+
+### Package is release candidate
+
+- All public APIs are RC by default
+- Do **not** decorate everything
+- Add `@experimental(...)` only for features that are intentionally still behind the package
+
+### Package is released / GA
+
+- All public APIs are released by default
+- Add `@experimental(...)` or `@release_candidate(...)` only for features still being held back
+
+## Moving a feature from one stage to the next
+
+### Experimental -> Release candidate
+
+1. Move the feature ID from `ExperimentalFeature` to `ReleaseCandidateFeature`
+2. Replace `@experimental(...)` with `@release_candidate(...)`
+3. Update any tests or docs that mention the old stage
+
+### Experimental -> Released
+
+1. Remove `@experimental(...)`
+2. Remove the feature from `ExperimentalFeature`
+3. Do not add a replacement feature-stage decorator
+
+### Release candidate -> Released
+
+1. Remove `@release_candidate(...)`
+2. Remove the feature from `ReleaseCandidateFeature`
+3. Leave the API undecorated
+
+### Any stage -> Deprecated
+
+1. Remove any feature-stage decorator
+2. Remove the feature from the stage enum
+3. Add `@deprecated("...")`
+4. Update docs/tests to reflect the replacement path
+
+## Promotion guidance
+
+Features do **not** have to pass through every stage.
+
+- It is usually a good idea to move features in order when that reflects reality
+- But it is completely acceptable to go **experimental -> released**
+- Do **not** force a feature through release candidate if there is no real RC period
+
+Likewise, when a package advances, do not automatically move every feature with it.
+
+- Promote features based on actual readiness
+- Keep lagging features explicitly marked only when they are behind the package default
+
+## Practical rules of thumb
+
+- **Package default first, feature exceptions second**
+- **Do not decorate everything in preview packages**
+- **Do not double-annotate members of an already-staged class**
+- **Use enums only for currently staged features**
+- **Do not treat stage enums as a compatibility contract**
+- **Treat `__feature_stage__` and `__feature_id__` as optional metadata; use `getattr`**
+- **Remove stage annotations once a feature is released or deprecated**
@@ -134,7 +134,7 @@ Recommended dependency workflow during connector implementation:
 pip install agent-framework-core          # Core only
 pip install agent-framework-core[all]     # Core + all connectors
 pip install agent-framework               # Same as core[all]
-pip install agent-framework-azure-ai      # Specific connector (pulls in core)
+pip install agent-framework-foundry       # Specific connector (pulls in core)
 ```

 ## Maintaining Documentation
@@ -143,3 +143,11 @@ When changing a package, check if its `AGENTS.md` needs updates:
 - Adding/removing/renaming public classes or functions
 - Changing the package's purpose or architecture
 - Modifying import paths or usage patterns
+
+When a package adds, removes, or renames environment variables, update the related documentation in the same
+change:
+- The package's `README.md` for package-level configuration/env var guidance
+- `samples/README.md` if the package is included in `packages/core/pyproject.toml` `[all]` and the env var is
+  part of the consolidated package env-var inventory
+- Any affected sample/package-local `.env.example`, `.env.template`, or sample README files when sample setup
+  changes alongside the package
--- a/Show More
+++ b/Show More