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
488 changed files with 21486 additions and 22212 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
@@ -74,6 +74,37 @@ Contributions must maintain API signature and behavioral compatibility. Contribu
 that include breaking changes will be rejected. Please file an issue to discuss
 your idea or change if you believe that a breaking change is warranted.

+#### Automated API Compatibility Validation
+
+The .NET projects use [Package Validation](https://learn.microsoft.com/dotnet/fundamentals/package-validation/overview)
+to automatically detect API breaking changes. This validation runs during `dotnet build`
+(Release configuration) and `dotnet pack`, comparing the current API surface against the
+latest published NuGet baseline version.
+
+**What gets validated:** By default, packable RC packages (`IsReleaseCandidate=true`) and
+GA packages (`IsGenerallyAvailable=true`) that have a published NuGet baseline and do not
+override validation settings are automatically validated. The shared baseline version and
+default validation settings are defined in `dotnet/nuget/nuget-package.props`, but
+individual projects may opt out (for example by setting `EnablePackageValidation=false`).
+
+**If the build fails with CP errors (e.g., CP0001, CP0002):**
+
+1. **Unintentional breaking change** — Refactor your code to maintain backward compatibility.
+2. **Intentional breaking change** (approved by maintainers) — Generate a suppression file:
+   ```bash
+   dotnet build <project>.csproj -c Release /p:ApiCompatGenerateSuppressionFile=true
+   ```
+   This creates or updates a `CompatibilitySuppressions.xml` in the project directory.
+   Include this file in your PR with justification for the breaking change.
+
+**After each release:**
+
+1. Delete all `CompatibilitySuppressions.xml` files from validated projects.
+2. Update `PackageValidationBaselineVersion` in `dotnet/nuget/nuget-package.props` to the
+   newly published version.
+
+For more details, see the [Package Validation diagnostic IDs](https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids).
+
 ### Suggested Workflow

 We use and recommend the following workflow:
@@ -92,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

@@ -31,8 +31,6 @@ The persistence timing and `FunctionResultContent` trimming behaviors are interr

 - **Per-run persistence**: When messages are batched and persisted at the end of the full run, trailing `FunctionResultContent` trimming becomes necessary to match the service's behavior. Without trimming, the stored history contains `FunctionResultContent` that the service would never have stored.

-This means the trimming feature (introduced in [PR #4792](https://github.com/microsoft/agent-framework/pull/4792)) is primarily needed as a complement to per-run persistence. The `PersistChatHistoryAtEndOfRun` setting (introduced in [PR #4762](https://github.com/microsoft/agent-framework/pull/4762)) inverts the default so that per-service-call persistence is the standard behavior, and per-run persistence is opt-in.
-
 ## Decision Drivers

 - **A. Consistency**: The default behavior of `ChatHistoryProvider` should produce stored history that closely matches what the underlying AI service would store, minimizing surprise when switching between framework-managed and service-managed chat history.
@@ -43,33 +41,30 @@ This means the trimming feature (introduced in [PR #4792](https://github.com/mic

 ## Considered Options

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

 ## Pros and Cons of the Options

-### Option 1: Default to per-run persistence with `FunctionResultContent` trimming
+### Option 1: Per-run persistence with opt-in FRC trimming

-Keep the current default behavior of persisting chat history only at the end of the full agent run. Add `FunctionResultContent` trimming as the default to improve consistency with service storage. Provide an opt-in setting for users who want per-service-call persistence.
-
-Settings:
- `PersistChatHistoryAtEndOfRun` = `true`
+Keep the current default behavior of persisting chat history only at the end of the full agent run. Add `FunctionResultContent` trimming as an opt-in behavior to improve consistency with service storage.

 - Good, because runs are atomic — chat history is only updated when the full run succeeds, satisfying driver B.
 - Good, because the mental model is simple: one run = one history update, satisfying driver D.
 - Good, because trimming trailing `FunctionResultContent` improves consistency with service storage, partially satisfying driver A.
- Good, because users can opt in to per-service-call persistence for checkpointing/recovery scenarios, satisfying drivers C and E.
 - Bad, because the default persistence timing still differs from the service's behavior (per-run vs. per-service-call), only partially satisfying driver A.
- Bad, because if the process crashes mid-loop, all intermediate progress from the current run is lost, not satisfying driver C by default.
+- 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: Default to per-service-call persistence
+### Option 2: Opt-in per-service-call persistence (via `RequirePerServiceCallChatHistoryPersistence`)

-Change the default 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). Provide an opt-in setting for users who want per-run atomicity with trimming.
+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:
- `PersistChatHistoryAtEndOfRun` = `false` (default)
+- `RequirePerServiceCallChatHistoryPersistence` = `true`

- Good, because the stored history matches the service's behavior by default for both timing and content, fully satisfying driver A.
+- 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.
 - Good, because no separate `FunctionResultContent` trimming logic is needed, reducing complexity.
 - Bad, because chat history may be left in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), not satisfying driver B. A subsequent run cannot proceed without manually providing the missing `FunctionResultContent`.
@@ -78,39 +73,49 @@ Settings:

 ## Decision Outcome

-Chosen option: **Option 2 — Default to per-service-call persistence**, because it fully satisfies the consistency driver (A), naturally handles `FunctionResultContent` trimming without additional logic, and provides better recoverability for long-running tool-calling loops. Per-run persistence remains available via the `PersistChatHistoryAtEndOfRun` setting for users who prefer atomic run semantics.
+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 `PersistChatHistoryAtEndOfRun`:
+The behavior depends on the combination of `UseProvidedChatClientAsIs` and `RequirePerServiceCallChatHistoryPersistence`:

-| `UseProvidedChatClientAsIs` | `PersistChatHistoryAtEndOfRun` | Behavior |
+| `UseProvidedChatClientAsIs` | `RequirePerServiceCallChatHistoryPersistence` | Behavior |
 |---|---|---|
-| `false` (default) | `false` (default) | **Per-service-call persistence.** A `ChatHistoryPersistingChatClient` middleware is automatically injected into the chat client pipeline between `FunctionInvokingChatClient` and the leaf `IChatClient`. Messages are persisted after each service call. |
-| `true` | `false` | **User responsibility.** No middleware is injected because the user has provided a custom chat client stack. The user is responsible for ensuring correct persistence behavior (e.g., by including their own persisting middleware). |
-| `false` | `true` | **Per-run persistence with marking.** A `ChatHistoryPersistingChatClient` middleware is injected, but configured to *mark* messages with metadata rather than store them immediately. At the end of the run, marked messages are stored. Trailing `FunctionResultContent` is trimmed. |
-| `true` | `true` | **Per-run persistence with warning.** The system checks whether the custom chat client stack includes a `ChatHistoryPersistingChatClient`. If not, a warning is emitted (particularly relevant for workflow handoff scenarios where trimming cannot be guaranteed). If no `ChatHistoryPersistingChatClient` is preset, all messages are stored at the end of the run, otherwise marked messages are stored. |
+| `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 `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 `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 the stored history matches the service's behavior by default for both timing and content, fully satisfying consistency (driver A).
- Good, because intermediate progress is preserved if the process is interrupted, satisfying recoverability (driver C).
- Good, because no separate `FunctionResultContent` trimming logic is needed in the default path, reducing complexity.
- Good, because marking persisted messages with metadata enables deduplication and aids debugging.
- Good, because warnings for custom chat client configurations without the persisting middleware help prevent silent failures in workflow handoff scenarios.
- Bad, because chat history may be left in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), requiring manual recovery in rare cases.
- Bad, because the mental model is more complex for the default path: a single run may produce multiple history updates.
- Neutral, because users who prefer atomic run semantics can opt in to per-run persistence via `PersistChatHistoryAtEndOfRun = true`.
+- 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 `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 `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

-The `ChatHistoryPersistingChatClient` middleware must also update the session's `ConversationId` consistently for both response-based and conversation-based service interactions, ensuring the session always reflects the latest service-provided identifier.
+When `RequirePerServiceCallChatHistoryPersistence` is enabled, the `PerServiceCallChatHistoryPersistingChatClient`
+decorator also updates `session.ConversationId` after each service call. This handles two scenarios:

-## More Information
+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.

- [PR #4762: Persist messages during function call loop](https://github.com/microsoft/agent-framework/pull/4762) — introduces `PersistChatHistoryAfterEachServiceCall` option and `ChatHistoryPersistingChatClient` decorator
- [PR #4792: Trim final FRC to match service storage](https://github.com/microsoft/agent-framework/pull/4792) — introduces `StoreFinalFunctionResultContent` option and `FilterFinalFunctionResultContent` logic
- [Issue #2889](https://github.com/microsoft/agent-framework/issues/2889) — original issue tracking chat history persistence during function call loops
@@ -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.",
+},
+```
@@ -17,6 +17,7 @@

  <PropertyGroup>
    <IsReleaseCandidate>false</IsReleaseCandidate>
+    <IsGenerallyAvailable>false</IsGenerallyAvailable>
  </PropertyGroup>
  
  <PropertyGroup>
@@ -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" />
@@ -105,6 +106,7 @@
  <Folder Name="/Samples/02-agents/AgentSkills/">
    <File Path="samples/02-agents/AgentSkills/README.md" />
    <Project Path="samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Agent_Step01_FileBasedSkills.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step02_CodeDefinedSkills/Agent_Step02_CodeDefinedSkills.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
@@ -170,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,17 +2,19 @@
  <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>

    <!-- Package validation. Baseline Version should be the latest version available on NuGet. -->
-    <PackageValidationBaselineVersion>0.0.1</PackageValidationBaselineVersion>
+    <PackageValidationBaselineVersion>1.0.0-rc4</PackageValidationBaselineVersion>
+    <!-- Enable validation for RC packages and GA packages -->
+    <EnablePackageValidation Condition="'$(IsReleaseCandidate)' == 'true' OR '$(IsGenerallyAvailable)' == 'true'">true</EnablePackageValidation>
    <!-- Validate assembly attributes only for Publish builds -->
    <NoWarn Condition="'$(Configuration)' != 'Publish'">$(NoWarn);CP0003</NoWarn>
    <!-- Do not validate reference assemblies -->
@@ -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|
@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to define Agent Skills entirely in code using AgentInlineSkill.
+// No SKILL.md files are needed — skills, resources, and scripts are all defined programmatically.
+//
+// Three approaches are shown using a unit-converter skill:
+// 1. Static resources — inline content provided via AddResource
+// 2. Dynamic resources — computed at runtime via a factory delegate
+// 3. Code scripts — executable delegates the agent can invoke directly
+
+using System.Text.Json;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+// --- Configuration ---
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+// --- Build the code-defined skill ---
+var unitConverterSkill = new AgentInlineSkill(
+    name: "unit-converter",
+    description: "Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.",
+    instructions: """
+        Use this skill when the user asks to convert between units.
+
+        1. Review the conversion-table resource to find the factor for the requested conversion.
+        2. Check the conversion-policy resource for rounding and formatting rules.
+        3. Use the convert script, passing the value and factor from the table.
+        """)
+    // 1. Static Resource: conversion tables
+    .AddResource(
+        "conversion-table",
+        """
+        # Conversion Tables
+
+        Formula: **result = value × factor**
+
+        | From        | To          | Factor   |
+        |-------------|-------------|----------|
+        | miles       | kilometers  | 1.60934  |
+        | kilometers  | miles       | 0.621371 |
+        | pounds      | kilograms   | 0.453592 |
+        | kilograms   | pounds      | 2.20462  |
+        """)
+    // 2. Dynamic Resource: conversion policy (computed at runtime)
+    .AddResource("conversion-policy", () =>
+    {
+        const int Precision = 4;
+        return $"""
+            # Conversion Policy
+
+            **Decimal places:** {Precision}
+            **Format:** Always show both the original and converted values with units
+            **Generated at:** {DateTime.UtcNow:O}
+            """;
+    })
+    // 3. Code Script: convert
+    .AddScript("convert", (double value, double factor) =>
+    {
+        double result = Math.Round(value * factor, 4);
+        return JsonSerializer.Serialize(new { value, factor, result });
+    });
+
+// --- Skills Provider ---
+var skillsProvider = new AgentSkillsProvider(unitConverterSkill);
+
+// --- Agent Setup ---
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetResponsesClient()
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "UnitConverterAgent",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant that can convert units.",
+        },
+        AIContextProviders = [skillsProvider],
+    },
+    model: deploymentName);
+
+// --- Example: Unit conversion ---
+Console.WriteLine("Converting units with code-defined skills");
+Console.WriteLine(new string('-', 60));
+
+AgentResponse response = await agent.RunAsync(
+    "How many kilometers is a marathon (26.2 miles)? And how many pounds is 75 kilograms?");
+
+Console.WriteLine($"Agent: {response.Text}");
@@ -0,0 +1,52 @@
+# Code-Defined Agent Skills Sample
+
+This sample demonstrates how to define **Agent Skills entirely in code** using `AgentInlineSkill`.
+
+## What it demonstrates
+
+- Creating skills programmatically with `AgentInlineSkill` — no SKILL.md files needed
+- **Static resources** via `AddResource` with inline content
+- **Dynamic resources** via `AddResource` with a factory delegate (computed at runtime)
+- **Code scripts** via `AddScript` with a delegate handler
+- Using the `AgentSkillsProvider` constructor with inline skills
+
+## Skills Included
+
+### unit-converter (code-defined)
+
+Converts between common units using multiplication factors. Defined entirely in C# code:
+
+- `conversion-table` — Static resource with factor table
+- `conversion-policy` — Dynamic resource with formatting rules (generated at runtime)
+- `convert` — Script that performs `value × factor` conversion
+
+## Running the Sample
+
+### Prerequisites
+
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model
+
+### Setup
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+### Run
+
+```bash
+dotnet run
+```
+
+### Expected Output
+
+```
+Converting units with code-defined skills
+------------------------------------------------------------
+Agent: Here are your conversions:
+
+1. **26.2 miles → 42.16 km** (a marathon distance)
+2. **75 kg → 165.35 lbs**
+```
@@ -1,7 +1,24 @@
 # AgentSkills Samples

-Samples demonstrating Agent Skills capabilities.
+Samples demonstrating Agent Skills capabilities. Each sample shows a different way to define and use skills.

 | Sample | Description |
 |--------|-------------|
 | [Agent_Step01_FileBasedSkills](Agent_Step01_FileBasedSkills/) | Define skills as `SKILL.md` files on disk with reference documents. Uses a unit-converter skill. |
+| [Agent_Step02_CodeDefinedSkills](Agent_Step02_CodeDefinedSkills/) | Define skills entirely in C# code using `AgentInlineSkill`, with static/dynamic resources and scripts. |
+
+## Key Concepts
+
+### File-Based vs Code-Defined Skills
+
+| Aspect | File-Based | Code-Defined |
+|--------|-----------|--------------|
+| Definition | `SKILL.md` files on disk | `AgentInlineSkill` instances in C# |
+| Resources | All files in skill directory (filtered by extension) | `AddResource` (static value or delegate-backed) |
+| Scripts | Supported via script executor delegate | `AddScript` delegates |
+| Discovery | Automatic from directory path | Explicit via constructor |
+| Dynamic content | No (static files only) | Yes (factory delegates) |
+| Reusability | Copy skill directory | Inline or shared instances |
+
+For single-source scenarios, use the `AgentSkillsProvider` constructors directly. To combine multiple skill types, use the `AgentSkillsProviderBuilder`.
+
@@ -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.
@@ -16,7 +16,7 @@ using Qdrant.Client;
 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 embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-3-large";
-var afOverviewUrl = "https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/agent-framework/overview/agent-framework-overview.md";
+var afOverviewUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/overview/index.md";
 var afMigrationUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/migration-guide/from-semantic-kernel/index.md";

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
@@ -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,15 +1,16 @@
 // Copyright (c) Microsoft. All rights reserved.

 // This sample demonstrates how the ChatClientAgent persists chat history after each individual
-// call to the AI service.
+// 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
 // even if the process is interrupted mid-loop, but may also result in chat history that is not
 // yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
 //
-// To opt into end-of-run persistence instead (atomic run semantics), set
-// PersistChatHistoryAtEndOfRun = true on ChatClientAgentOptions.
+// To use end-of-run persistence instead (atomic run semantics), remove the
+// 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
 // using streaming (RunStreamingAsync), to demonstrate correct behavior in both modes.
@@ -53,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 the default behavior.
+// 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) ?
@@ -63,6 +64,7 @@ AIAgent agent = chatClient.AsAIAgent(
    new ChatClientAgentOptions
    {
        Name = "WeatherAssistant",
+        RequirePerServiceCallChatHistoryPersistence = true,
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
@@ -1,16 +1,19 @@
 # In-Function-Loop Checkpointing

-This sample demonstrates how `ChatClientAgent` persists chat history after each individual call to the AI service by default. 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 default, chat history is persisted after each service call via the `ChatHistoryPersistingChatClient` 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 `ChatHistoryPersistingChatClient` decorator is automatically 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

-To opt into end-of-run persistence instead (atomic run semantics), set `PersistChatHistoryAtEndOfRun = true` on `ChatClientAgentOptions`. In that mode, the decorator marks messages with metadata rather than persisting them immediately, and `ChatClientAgent` persists only the marked messages at the end of the run.
+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 `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
@@ -26,7 +29,7 @@ The sample asks the agent about the weather and time in three cities. The model
 ```
 ChatClientAgent
  └─ FunctionInvokingChatClient    (handles tool call loop)
-       └─ ChatHistoryPersistingChatClient  (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
@@ -0,0 +1,284 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
+<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentRecord,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentReference,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentVersion,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Azure.AI.Projects.AgentVersionCreationOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentRecord,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentReference,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentVersion,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Azure.AI.Projects.AgentVersionCreationOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentRecord,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentReference,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentVersion,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Azure.AI.Projects.AgentVersionCreationOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentRecord,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentReference,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentVersion,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Azure.AI.Projects.AgentVersionCreationOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentRecord,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentReference,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.AsAIAgent(Azure.AI.Projects.AIProjectClient,Azure.AI.Projects.OpenAI.AgentVersion,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Azure.AI.Projects.AgentVersionCreationOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.CreateAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Azure.AI.Projects.AzureAIProjectChatClientExtensions.GetAIAgentAsync(Azure.AI.Projects.AIProjectClient,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+</Suppressions>
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
+<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsIChatClientWithStoredOutputDisabled(OpenAI.Responses.ResponsesClient)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsIChatClientWithStoredOutputDisabled(OpenAI.Responses.ResponsesClient)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsIChatClientWithStoredOutputDisabled(OpenAI.Responses.ResponsesClient)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsIChatClientWithStoredOutputDisabled(OpenAI.Responses.ResponsesClient)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,Microsoft.Agents.AI.ChatClientAgentOptions,System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsAIAgent(OpenAI.Responses.ResponsesClient,System.String,System.String,System.String,System.Collections.Generic.IList{Microsoft.Extensions.AI.AITool},System.Func{Microsoft.Extensions.AI.IChatClient,Microsoft.Extensions.AI.IChatClient},Microsoft.Extensions.Logging.ILoggerFactory,System.IServiceProvider)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:OpenAI.Responses.OpenAIResponseClientExtensions.AsIChatClientWithStoredOutputDisabled(OpenAI.Responses.ResponsesClient)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.OpenAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.OpenAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+</Suppressions>
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
+<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.Declarative.AzureAgentProvider.get_OpenAIClientOptions</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.Declarative.AzureAgentProvider.get_OpenAIClientOptions</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.Declarative.AzureAgentProvider.get_OpenAIClientOptions</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.Declarative.AzureAgentProvider.get_OpenAIClientOptions</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.Declarative.AzureAgentProvider.get_OpenAIClientOptions</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+</Suppressions>
@@ -13,6 +13,11 @@

  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />

+  <!-- Package not yet published to NuGet — disable baseline validation until first release -->
+  <PropertyGroup>
+    <EnablePackageValidation>false</EnablePackageValidation>
+  </PropertyGroup>
+
  <PropertyGroup>
    <!-- NuGet Package Settings -->
    <Title>Microsoft Agent Framework Declarative Workflows MCP</Title>
@@ -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>
@@ -0,0 +1,319 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
+<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config`1</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.ConfigurationExtensions</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`1</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`2</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config`1</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.ConfigurationExtensions</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`1</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`2</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config`1</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.ConfigurationExtensions</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`1</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`2</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config`1</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.ConfigurationExtensions</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`1</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`2</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Config`1</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.ConfigurationExtensions</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`1</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.Workflows.Configured`2</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.AgentWorkflowBuilder.CreateHandoffBuilderWith(Microsoft.Agents.AI.AIAgent)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.BindExecutor``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.ConfigureFactory``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.AgentWorkflowBuilder.CreateHandoffBuilderWith(Microsoft.Agents.AI.AIAgent)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.BindExecutor``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.ConfigureFactory``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.AgentWorkflowBuilder.CreateHandoffBuilderWith(Microsoft.Agents.AI.AIAgent)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.BindExecutor``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.ConfigureFactory``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.AgentWorkflowBuilder.CreateHandoffBuilderWith(Microsoft.Agents.AI.AIAgent)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.BindExecutor``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.ConfigureFactory``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.AgentWorkflowBuilder.CreateHandoffBuilderWith(Microsoft.Agents.AI.AIAgent)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.BindExecutor``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.Workflows.ExecutorBindingExtensions.ConfigureFactory``2(System.Func{Microsoft.Agents.AI.Workflows.Config{``1},System.String,System.Threading.Tasks.ValueTask{``0}},System.String,``1)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.Workflows.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+</Suppressions>
@@ -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 end-of-run persistence but no ChatHistoryPersistingChatClient.
-        this.WarnOnMissingPersistingClient();
+        // 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="ChatHistoryPersistingChatClient"/> 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,
@@ -463,7 +463,7 @@ public sealed partial class ChatClientAgent : AIAgent
        ChatOptions? chatOptions,
        CancellationToken cancellationToken)
    {
-        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, session);
+        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions);

        if (chatHistoryProvider is not null)
        {
@@ -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="ChatHistoryPersistingChatClient"/> 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,
@@ -495,7 +495,7 @@ public sealed partial class ChatClientAgent : AIAgent
        ChatOptions? chatOptions,
        CancellationToken cancellationToken)
    {
-        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, session);
+        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions);

        if (chatHistoryProvider is not null)
        {
@@ -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.PersistsChatHistoryPerServiceCall && 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);
@@ -719,57 +719,6 @@ public sealed partial class ChatClientAgent : AIAgent
            throw new InvalidOperationException("Input messages are not allowed when continuing a background response using a continuation token.");
        }

-        IEnumerable<ChatMessage> inputMessagesForChatClient = inputMessages;
-
-        // Populate the session messages only if we are not continuing an existing response as it's not allowed
-        if (chatOptions?.ContinuationToken is null)
-        {
-            ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, typedSession);
-
-            // 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).
-            if (chatHistoryProvider is not null)
-            {
-                var invokingContext = new ChatHistoryProvider.InvokingContext(this, typedSession, inputMessagesForChatClient);
-                inputMessagesForChatClient = await chatHistoryProvider.InvokingAsync(invokingContext, cancellationToken).ConfigureAwait(false);
-            }
-
-            // If we have an AIContextProvider, we should get context from it, and update our
-            // messages and options with the additional context.
-            // The AIContextProvider returns the accumulated AIContext (original + new contributions).
-            if (this.AIContextProviders is { Count: > 0 } aiContextProviders)
-            {
-                var aiContext = new AIContext
-                {
-                    Instructions = chatOptions?.Instructions,
-                    Messages = inputMessagesForChatClient,
-                    Tools = chatOptions?.Tools
-                };
-
-                foreach (var aiContextProvider in aiContextProviders)
-                {
-                    var invokingContext = new AIContextProvider.InvokingContext(this, typedSession, aiContext);
-                    aiContext = await aiContextProvider.InvokingAsync(invokingContext, cancellationToken).ConfigureAwait(false);
-                }
-
-                // Materialize the accumulated messages and tools once at the end of the provider pipeline.
-                inputMessagesForChatClient = aiContext.Messages ?? [];
-
-                var tools = aiContext.Tools as IList<AITool> ?? aiContext.Tools?.ToList();
-                if (chatOptions?.Tools is { Count: > 0 } || tools is { Count: > 0 })
-                {
-                    chatOptions ??= new();
-                    chatOptions.Tools = tools;
-                }
-
-                if (chatOptions?.Instructions is not null || aiContext.Instructions is not null)
-                {
-                    chatOptions ??= new();
-                    chatOptions.Instructions = aiContext.Instructions;
-                }
-            }
-        }
-
        // If a user provided two different session ids, via the session object and options, we should throw
        // since we don't know which one to use.
        if (!string.IsNullOrWhiteSpace(typedSession.ConversationId) && !string.IsNullOrWhiteSpace(chatOptions?.ConversationId) && typedSession.ConversationId != chatOptions!.ConversationId)
@@ -788,12 +737,53 @@ public sealed partial class ChatClientAgent : AIAgent
            chatOptions.ConversationId = typedSession.ConversationId;
        }

-        // When per-service-call persistence is active, set a sentinel conversation ID so that
-        // FunctionInvokingChatClient treats locally-persisted history the same as service-managed
-        // history. This prevents it from adding duplicate FunctionCallContent messages into the
-        // request when processing approval responses — the loaded history already contains them.
-        // ChatHistoryPersistingChatClient strips the sentinel before forwarding to the inner client.
-        chatOptions = this.SetLocalHistoryConversationIdIfNeeded(chatOptions);
+        IEnumerable<ChatMessage> inputMessagesForChatClient = inputMessages;
+
+        // Populate the session messages only if we are not continuing an existing response as it's not allowed.
+        // 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.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).
+            inputMessagesForChatClient = await this.LoadChatHistoryAsync(typedSession, inputMessagesForChatClient, chatOptions, cancellationToken).ConfigureAwait(false);
+        }
+
+        // AIContextProviders should always be invoked (unless continuing an existing response)
+        // to contribute additional messages, tools, and instructions — even when the decorator
+        // handles history loading.
+        if (chatOptions?.ContinuationToken is null && this.AIContextProviders is { Count: > 0 } aiContextProviders)
+        {
+            var aiContext = new AIContext
+            {
+                Instructions = chatOptions?.Instructions,
+                Messages = inputMessagesForChatClient,
+                Tools = chatOptions?.Tools
+            };
+
+            foreach (var aiContextProvider in aiContextProviders)
+            {
+                var invokingContext = new AIContextProvider.InvokingContext(this, typedSession, aiContext);
+                aiContext = await aiContextProvider.InvokingAsync(invokingContext, cancellationToken).ConfigureAwait(false);
+            }
+
+            // Materialize the accumulated messages and tools once at the end of the provider pipeline.
+            inputMessagesForChatClient = aiContext.Messages ?? [];
+
+            var tools = aiContext.Tools as IList<AITool> ?? aiContext.Tools?.ToList();
+            if (chatOptions?.Tools is { Count: > 0 } || tools is { Count: > 0 })
+            {
+                chatOptions ??= new();
+                chatOptions.Tools = tools;
+            }
+
+            if (chatOptions?.Instructions is not null || aiContext.Instructions is not null)
+            {
+                chatOptions ??= new();
+                chatOptions.Instructions = aiContext.Instructions;
+            }
+        }

        // Materialize the accumulated messages once at the end of the provider pipeline, reusing the existing list if possible.
        List<ChatMessage> messagesList = inputMessagesForChatClient as List<ChatMessage> ?? inputMessagesForChatClient.ToList();
@@ -839,8 +829,6 @@ public sealed partial class ChatClientAgent : AIAgent
                }
            }

-            // If we got a conversation id back from the chat client, it means that the service supports server side session storage
-            // so we should update the session with the new id.
            session.ConversationId = responseConversationId;
        }
    }
@@ -849,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="ChatHistoryPersistingChatClient"/> in persist mode handles per-service-call
-    /// conversation ID updates, this end-of-run update is skipped. When the decorator is in mark-only
-    /// mode or absent, the update is performed here. When <paramref name="forceUpdate"/> is <see langword="true"/>
+    /// 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.PersistsChatHistoryPerServiceCall)
+        if (!forceUpdate && this.RequiresPerServiceCallChatHistoryPersistence)
        {
            return;
        }
@@ -868,10 +856,9 @@ 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="ChatHistoryPersistingChatClient"/> in persist mode handles per-service-call
-    /// notification, this end-of-run notification is skipped. When the decorator is in mark-only mode,
-    /// only the marked messages are persisted. When no decorator is present (custom stack with
-    /// <see cref="ChatClientAgentOptions.PersistChatHistoryAtEndOfRun"/>), all messages are persisted.
+    /// 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
    /// background response scenarios), notification is always performed with all messages because
    /// per-service-call persistence is unreliable in these scenarios.
@@ -884,19 +871,11 @@ public sealed partial class ChatClientAgent : AIAgent
        CancellationToken cancellationToken,
        bool forceNotify = false)
    {
-        if (!forceNotify && this.PersistsChatHistoryPerServiceCall)
+        if (!forceNotify && this.RequiresPerServiceCallChatHistoryPersistence)
        {
            return Task.CompletedTask;
        }

-        if (!forceNotify && this.HasMarkOnlyChatHistoryPersistingClient)
-        {
-            // In mark-only mode, persist only messages that were marked by the decorator.
-            var markedRequestMessages = GetMarkedMessages(requestMessages);
-            var markedResponseMessages = GetMarkedMessages(responseMessages);
-            return this.NotifyProvidersOfNewMessagesAsync(session, markedRequestMessages, markedResponseMessages, chatOptions, cancellationToken);
-        }
-
        return this.NotifyProvidersOfNewMessagesAsync(session, requestMessages, responseMessages, chatOptions, cancellationToken);
    }

@@ -904,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="ChatHistoryPersistingChatClient"/> in persist mode 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>
@@ -915,7 +894,7 @@ public sealed partial class ChatClientAgent : AIAgent
        ChatOptions? chatOptions,
        CancellationToken cancellationToken)
    {
-        if (this.PersistsChatHistoryPerServiceCall)
+        if (this.RequiresPerServiceCallChatHistoryPersistence)
        {
            return Task.CompletedTask;
        }
@@ -924,60 +903,19 @@ public sealed partial class ChatClientAgent : AIAgent
    }

    /// <summary>
-    /// Gets a value indicating whether the agent has a <see cref="ChatHistoryPersistingChatClient"/>
-    /// decorator in persist mode (not mark-only), which handles per-service-call persistence.
+    /// 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="PerServiceCallChatHistoryPersistingChatClient"/> or a
+    /// user-supplied equivalent) is expected to handle the history lifecycle.
    /// </summary>
-    private bool PersistsChatHistoryPerServiceCall
+    private bool RequiresPerServiceCallChatHistoryPersistence
    {
        get
        {
-            var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
-            return persistingClient?.MarkOnly == false;
+            return this._agentOptions?.RequirePerServiceCallChatHistoryPersistence is true;
        }
    }

-    /// <summary>
-    /// Sets the <see cref="ChatHistoryPersistingChatClient.LocalHistoryConversationId"/> sentinel on
-    /// <paramref name="chatOptions"/> when per-service-call persistence is active and no real
-    /// conversation ID is present.
-    /// </summary>
-    /// <returns>
-    /// The (possibly new) <see cref="ChatOptions"/> with the sentinel set, or the original
-    /// <paramref name="chatOptions"/> if no sentinel is needed.
-    /// </returns>
-    private ChatOptions? SetLocalHistoryConversationIdIfNeeded(ChatOptions? chatOptions)
-    {
-        if (this.PersistsChatHistoryPerServiceCall && string.IsNullOrWhiteSpace(chatOptions?.ConversationId))
-        {
-            chatOptions ??= new ChatOptions();
-            chatOptions.ConversationId = ChatHistoryPersistingChatClient.LocalHistoryConversationId;
-        }
-
-        return chatOptions;
-    }
-
-    /// <summary>
-    /// Gets a value indicating whether the agent has a <see cref="ChatHistoryPersistingChatClient"/>
-    /// decorator in mark-only mode, which marks messages for later persistence at the end of the run.
-    /// </summary>
-    private bool HasMarkOnlyChatHistoryPersistingClient
-    {
-        get
-        {
-            var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
-            return persistingClient?.MarkOnly == true;
-        }
-    }
-
-    /// <summary>
-    /// Returns only the messages that have been marked as persisted by a <see cref="ChatHistoryPersistingChatClient"/> in mark-only mode.
-    /// </summary>
-    private static List<ChatMessage> GetMarkedMessages(IEnumerable<ChatMessage> messages)
-    {
-        return messages.Where(m =>
-            m.AdditionalProperties?.TryGetValue(ChatHistoryPersistingChatClient.PersistedMarkerKey, out var value) == true && value is true).ToList();
-    }
-
    /// <summary>
    /// Ensures that <see cref="AIAgent.CurrentRunContext"/> contains the resolved session.
    /// </summary>
@@ -985,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="ChatHistoryPersistingChatClient"/> 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>
@@ -1001,36 +939,36 @@ public sealed partial class ChatClientAgent : AIAgent
    /// <summary>
    /// Checks for potential misconfiguration when using a custom chat client stack and logs warnings.
    /// </summary>
-    private void WarnOnMissingPersistingClient()
+    private void WarnOnMissingPerServiceCallChatHistoryPersistingChatClient()
    {
        if (this._agentOptions?.UseProvidedChatClientAsIs is not true)
        {
            return;
        }

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

-        var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
+        var persistingClient = this.ChatClient.GetService<PerServiceCallChatHistoryPersistingChatClient>();
        if (persistingClient is null && this._logger.IsEnabled(LogLevel.Warning))
        {
            var loggingAgentName = this.GetLoggingAgentName();
            this._logger.LogAgentChatClientMissingPersistingClient(
                this.Id,
-                loggingAgentName);
+                loggingAgentName); // CodeQL [CWE-359] False positive: Agent name is not personal information, but rather just the name of a code component (agent in this case).
        }
    }

-    private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions, ChatClientAgentSession session)
+    private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions)
    {
-        ChatHistoryProvider? provider = session.ConversationId is null ? this.ChatHistoryProvider : null;
+        ChatHistoryProvider? provider = chatOptions?.ConversationId is null ? this.ChatHistoryProvider : null;

        // If someone provided an override ChatHistoryProvider via AdditionalProperties, we should use that instead.
        if (chatOptions?.AdditionalProperties?.TryGetValue(out ChatHistoryProvider? overrideProvider) is true)
        {
-            if (session.ConversationId is not null && overrideProvider is not null)
+            if (this._agentOptions?.ThrowOnChatHistoryProviderConflict is true && string.IsNullOrWhiteSpace(chatOptions?.ConversationId) is false)
            {
                throw new InvalidOperationException(
                    $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. The current {nameof(ChatClientAgentSession)} has a {nameof(ChatClientAgentSession.ConversationId)} indicating server-side chat history management, but an override {nameof(this.ChatHistoryProvider)} was provided via {nameof(AgentRunOptions.AdditionalProperties)}.");
@@ -1055,6 +993,29 @@ public sealed partial class ChatClientAgent : AIAgent
        return provider;
    }

+    /// <summary>
+    /// Loads chat history from the resolved <see cref="ChatHistoryProvider"/> and prepends it to the given messages.
+    /// </summary>
+    /// <remarks>
+    /// This method is used by both the agent (during <see cref="PrepareSessionAndMessagesAsync"/>) and by
+    /// <see cref="PerServiceCallChatHistoryPersistingChatClient"/> to load history before each service call.
+    /// </remarks>
+    internal async Task<IEnumerable<ChatMessage>> LoadChatHistoryAsync(
+        ChatClientAgentSession session,
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? chatOptions,
+        CancellationToken cancellationToken)
+    {
+        var chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions);
+        if (chatHistoryProvider is null)
+        {
+            return messages;
+        }
+
+        var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
+        return await chatHistoryProvider.InvokingAsync(invokingContext, cancellationToken).ConfigureAwait(false);
+    }
+
    private static ChatClientAgentContinuationToken? WrapContinuationToken(ResponseContinuationToken? continuationToken, IEnumerable<ChatMessage>? inputMessages = null, List<ChatResponseUpdate>? responseUpdates = null)
    {
        if (continuationToken is null)
@@ -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.PersistChatHistoryAtEndOfRun"/> is <see langword="true"/>,
-    /// but no <see cref="ChatHistoryPersistingChatClient"/> 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}: PersistChatHistoryAtEndOfRun is enabled with a custom chat client stack (UseProvidedChatClientAsIs), but no ChatHistoryPersistingChatClient was found in the pipeline. All messages will be persisted at the end of the run without marking. This setup is not supported with some other features, e.g. handoffs. Consider adding a ChatHistoryPersistingChatClient to the pipeline using the UseChatHistoryPersisting extension method.")]
+        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}: Per-service-call persistence is falling back to end-of-run persistence because the run involves background responses. Messages will be marked during the run and persisted at the end.")]
+        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,54 +92,64 @@ public sealed class ChatClientAgentOptions
    public bool ThrowOnChatHistoryProviderConflict { get; set; } = true;

    /// <summary>
-    /// Gets or sets a value indicating whether to persist chat history only at the end of the full agent run
-    /// rather than after each individual service call.
+    /// 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>
-    /// By default, <see cref="ChatClientAgent"/> persists request and response messages either via
-    /// a <see cref="ChatHistoryProvider"/>, or the underlying AI service's chat history storage.
-    /// Persistence is done immediately after each call to the AI service within the function invocation loop.
-    /// When storing in the underlying AI service, the session's <see cref="ChatClientAgentSession.ConversationId"/>
-    /// is also updated after each service call, keeping it in sync with the service-side conversation state.
+    /// 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"/> 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>
-    /// Setting this property to <see langword="true"/> causes messages to be marked during the function
-    /// invocation loop but persisted only at the end of the full agent run, providing atomic run semantics.
-    /// Updating the <see cref="ChatClientAgentSession.ConversationId"/> is likewise deferred and
-    /// updated only at the end of the run, consistent with atomic run semantics.
-    /// A <see cref="ChatHistoryPersistingChatClient"/> decorator is inserted into the chat client pipeline
-    /// in mark-only mode, and the <see cref="ChatClientAgent"/> persists only the marked messages at the
-    /// end of the run.
-    /// </para>
-    /// <para>
-    /// When this option is <see langword="false"/> (the default), the <see cref="ChatHistoryPersistingChatClient"/>
-    /// decorator persists messages and updates the <see cref="ChatClientAgentSession.ConversationId"/>
-    /// immediately after each service call. This may leave chat history in a state where
-    /// <see cref="FunctionResultContent"/> is required to start a new run if the last successful service
-    /// call returned <see cref="FunctionCallContent"/>.
-    /// </para>
-    /// <para>
-    /// This option has no effect when <see cref="UseProvidedChatClientAsIs"/> is <see langword="true"/>.
-    /// When using a custom chat client stack, you can add a <see cref="ChatHistoryPersistingChatClient"/>
-    /// manually via the <see cref="ChatClientBuilderExtensions.UseChatHistoryPersisting"/>
+    /// When setting the <see cref="UseProvidedChatClientAsIs"/> setting to <see langword="true"/> and
+    /// <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="PerServiceCallChatHistoryPersistingChatClient"/>
+    /// manually via the <see cref="ChatClientBuilderExtensions.UsePerServiceCallChatHistoryPersistence"/>
    /// extension method.
    /// </para>
-    /// <para>
-    /// Note that when using single threaded service stored chat history, like OpenAI Conversations,
-    /// there is only one id, so even if the conversation id is not updated after each service call,
-    /// the chat history will still contain intermediate messages. Setting this property to <see langword="true"/>
-    /// in this case will therefore have no real effect. Setting this property to <see langword="true"/> when using
-    /// OpenAI Responses with response ids on the other hand, allows atomic run semantics, since
-    /// each service request produces a new response id, and if the run fails mid-loop, the session will
-    /// still contain the pre-run respnose id, allowing the next run to start with a clean slate.
-    /// </para>
    /// </remarks>
    /// <value>
    /// Default is <see langword="false"/>.
    /// </value>
    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-    public bool PersistChatHistoryAtEndOfRun { get; set; }
+    public bool RequirePerServiceCallChatHistoryPersistence { get; set; }

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

    /// <summary>
-    /// Adds a <see cref="ChatHistoryPersistingChatClient"/> 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 intercepts service calls to either persist messages
-    /// immediately or mark them for later persistence, depending on the <paramref name="markOnly"/> parameter.
-    /// </para>
-    /// <para>
-    /// If <paramref name="markOnly"/> is set to <see langword="true"/>, the <see cref="ChatClientAgent"/>
-    /// should be configured with <see cref="ChatClientAgentOptions.PersistChatHistoryAtEndOfRun"/> set to <see langword="true"/>
-    /// as without this combination, messages will never be persisted when using a <see cref="ChatHistoryProvider"/> for
-    /// chat history persistence.
+    /// <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.
+    /// 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
@@ -112,18 +108,10 @@ public static class ChatClientBuilderExtensions
    /// </para>
    /// </remarks>
    /// <param name="builder">The <see cref="ChatClientBuilder"/> to add the decorator to.</param>
-    /// <param name="markOnly">
-    /// When <see langword="true"/>, messages are marked with metadata but not persisted immediately,
-    /// and the session's <see cref="ChatClientAgentSession.ConversationId"/> is not updated.
-    /// The <see cref="ChatClientAgent"/> will persist only the marked messages and update the
-    /// conversation ID at the end of the run.
-    /// When <see langword="false"/> (the default), messages are persisted and the conversation ID
-    /// is updated immediately after each service call.
-    /// </param>
    /// <returns>The <paramref name="builder"/> for chaining.</returns>
    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-    public static ChatClientBuilder UseChatHistoryPersisting(this ChatClientBuilder builder, bool markOnly = false)
+    public static ChatClientBuilder UsePerServiceCallChatHistoryPersistence(this ChatClientBuilder builder)
    {
-        return builder.Use(innerClient => new ChatHistoryPersistingChatClient(innerClient, markOnly));
+        return builder.Use(innerClient => new PerServiceCallChatHistoryPersistingChatClient(innerClient));
    }
 }
@@ -63,14 +63,17 @@ public static class ChatClientExtensions
            });
        }

-        // ChatHistoryPersistingChatClient 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 → ChatHistoryPersistingChatClient → leaf IChatClient
-        // This allows the decorator to persist messages after each individual service call within
-        // FIC's function invocation loop, or to mark them for later persistence at the end of the run.
-        bool markOnly = options?.PersistChatHistoryAtEndOfRun is true;
-        chatBuilder.Use(innerClient => new ChatHistoryPersistingChatClient(innerClient, markOnly));
+        // 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 → 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?.RequirePerServiceCallChatHistoryPersistence is true)
+        {
+            chatBuilder.Use(innerClient => new PerServiceCallChatHistoryPersistingChatClient(innerClient));
+        }

        var agentChatClient = chatBuilder.Build(services);

@@ -1,351 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Runtime.CompilerServices;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
-
-namespace Microsoft.Agents.AI;
-
-/// <summary>
-/// A delegating chat client that notifies <see cref="ChatHistoryProvider"/> and <see cref="AIContextProvider"/>
-/// instances of request and response messages after each individual call to the inner chat client,
-/// or marks messages for later persistence depending on the configured mode.
-/// </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.
-/// </para>
-/// <para>
-/// In persist mode (the default), it ensures that providers are notified and the session's
-/// <see cref="ChatClientAgentSession.ConversationId"/> is updated after each service call, so that
-/// intermediate messages (e.g., tool calls and results) are saved even if the process is interrupted
-/// mid-loop.
-/// </para>
-/// <para>
-/// In mark-only mode (<see cref="MarkOnly"/> is <see langword="true"/>), it marks messages with metadata
-/// but does not notify providers or update the <see cref="ChatClientAgentSession.ConversationId"/>.
-/// Both are deferred to the <see cref="ChatClientAgent"/> at the end of the run, providing atomic
-/// run semantics.
-/// </para>
-/// <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
-/// <see cref="AIAgent.RunAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/> or
-/// <see cref="AIAgent.RunStreamingAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/>
-/// method is called. The <see cref="ChatClientAgent"/> ensures the run context always contains a resolved session,
-/// even when the caller passes null. An <see cref="InvalidOperationException"/> is thrown if no run context is
-/// available or if the agent is not a <see cref="ChatClientAgent"/>.
-/// </para>
-/// </remarks>
-internal sealed class ChatHistoryPersistingChatClient : DelegatingChatClient
-{
-    /// <summary>
-    /// The key used in <see cref="ChatMessage.AdditionalProperties"/> and <see cref="AIContent.AdditionalProperties"/>
-    /// to mark messages and their content as already persisted to chat history.
-    /// </summary>
-    internal const string PersistedMarkerKey = "_chatHistoryPersisted";
-
-    /// <summary>
-    /// A sentinel value set on <see cref="ChatOptions.ConversationId"/> by <see cref="ChatClientAgent"/>
-    /// when per-service-call persistence is active and no real conversation ID exists.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// This signals to <see cref="FunctionInvokingChatClient"/> that the chat history is being managed
-    /// externally (by this decorator), which prevents it from adding duplicate <see cref="FunctionCallContent"/>
-    /// messages into the request during approval-response processing. Without this sentinel,
-    /// <see cref="FunctionInvokingChatClient"/> would reconstruct function-call messages from approval
-    /// responses and append them to the original messages — but the loaded history already contains
-    /// those same function calls, causing duplicate tool-call entries that the model rejects.
-    /// </para>
-    /// <para>
-    /// This decorator strips the sentinel before forwarding requests to the inner client, so the
-    /// underlying model never sees it.
-    /// </para>
-    /// </remarks>
-    internal const string LocalHistoryConversationId = "_agent_local_history";
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="ChatHistoryPersistingChatClient"/> class.
-    /// </summary>
-    /// <param name="innerClient">The underlying chat client that will handle the core operations.</param>
-    /// <param name="markOnly">
-    /// When <see langword="true"/>, messages are marked with metadata but not persisted immediately,
-    /// and the session's <see cref="ChatClientAgentSession.ConversationId"/> is not updated.
-    /// The <see cref="ChatClientAgent"/> will persist only the marked messages and update the
-    /// conversation ID at the end of the run.
-    /// When <see langword="false"/> (the default), messages are persisted and the conversation ID
-    /// is updated immediately after each service call.
-    /// </param>
-    public ChatHistoryPersistingChatClient(IChatClient innerClient, bool markOnly = false)
-        : base(innerClient)
-    {
-        this.MarkOnly = markOnly;
-    }
-
-    /// <summary>
-    /// Gets a value indicating whether this decorator is in mark-only mode.
-    /// </summary>
-    /// <remarks>
-    /// When <see langword="true"/>, messages are marked with metadata but not persisted immediately,
-    /// and the session's <see cref="ChatClientAgentSession.ConversationId"/> is not updated.
-    /// Both are deferred to the <see cref="ChatClientAgent"/> at the end of the run.
-    /// When <see langword="false"/>, messages are persisted and the conversation ID is updated
-    /// after each service call.
-    /// </remarks>
-    public bool MarkOnly { get; }
-
-    /// <inheritdoc/>
-    public override async Task<ChatResponse> GetResponseAsync(
-        IEnumerable<ChatMessage> messages,
-        ChatOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        var (agent, session) = GetRequiredAgentAndSession();
-        options = StripLocalHistoryConversationId(options);
-
-        ChatResponse response;
-        try
-        {
-            response = await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
-        }
-        catch (Exception ex)
-        {
-            var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
-            await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
-            throw;
-        }
-
-        var newRequestMessages = GetNewRequestMessages(messages);
-
-        if (this.ShouldDeferPersistence(options))
-        {
-            // In mark-only mode or when resuming from a continuation token, just mark messages
-            // for later persistence by ChatClientAgent. Conversation ID and provider notification
-            // are deferred to end-of-run. For continuation tokens, the end-of-run handler needs
-            // to send the combined data from both the previous and current runs.
-            MarkAsPersisted(newRequestMessages);
-            MarkAsPersisted(response.Messages);
-        }
-        else
-        {
-            // In persist mode, persist immediately and update conversation ID.
-            agent.UpdateSessionConversationId(session, response.ConversationId, cancellationToken);
-            await agent.NotifyProvidersOfNewMessagesAsync(session, newRequestMessages, response.Messages, options, cancellationToken).ConfigureAwait(false);
-            MarkAsPersisted(newRequestMessages);
-            MarkAsPersisted(response.Messages);
-        }
-
-        return response;
-    }
-
-    /// <inheritdoc/>
-    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
-        IEnumerable<ChatMessage> messages,
-        ChatOptions? options = null,
-        [EnumeratorCancellation] CancellationToken cancellationToken = default)
-    {
-        var (agent, session) = GetRequiredAgentAndSession();
-        options = StripLocalHistoryConversationId(options);
-
-        List<ChatResponseUpdate> responseUpdates = [];
-
-        IAsyncEnumerator<ChatResponseUpdate> enumerator;
-        try
-        {
-            enumerator = base.GetStreamingResponseAsync(messages, options, cancellationToken).GetAsyncEnumerator(cancellationToken);
-        }
-        catch (Exception ex)
-        {
-            var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
-            await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
-            throw;
-        }
-
-        bool hasUpdates;
-        try
-        {
-            hasUpdates = await enumerator.MoveNextAsync().ConfigureAwait(false);
-        }
-        catch (Exception ex)
-        {
-            var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
-            await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
-            throw;
-        }
-
-        while (hasUpdates)
-        {
-            var update = enumerator.Current;
-            responseUpdates.Add(update);
-            yield return update;
-
-            try
-            {
-                hasUpdates = await enumerator.MoveNextAsync().ConfigureAwait(false);
-            }
-            catch (Exception ex)
-            {
-                var newRequestMessagesOnFailure = GetNewRequestMessages(messages);
-                await agent.NotifyProvidersOfFailureAsync(session, ex, newRequestMessagesOnFailure, options, cancellationToken).ConfigureAwait(false);
-                throw;
-            }
-        }
-
-        var chatResponse = responseUpdates.ToChatResponse();
-        var newRequestMessages = GetNewRequestMessages(messages);
-
-        if (this.ShouldDeferPersistence(options))
-        {
-            // In mark-only mode or when resuming from a continuation token, just mark messages
-            // for later persistence by ChatClientAgent. Conversation ID and provider notification
-            // are deferred to end-of-run. For continuation tokens, the end-of-run handler needs
-            // to send the combined data from both the previous and current runs.
-            MarkAsPersisted(newRequestMessages);
-            MarkAsPersisted(chatResponse.Messages);
-        }
-        else
-        {
-            // In persist mode, persist immediately and update conversation ID.
-            agent.UpdateSessionConversationId(session, chatResponse.ConversationId, cancellationToken);
-            await agent.NotifyProvidersOfNewMessagesAsync(session, newRequestMessages, chatResponse.Messages, options, cancellationToken).ConfigureAwait(false);
-            MarkAsPersisted(newRequestMessages);
-            MarkAsPersisted(chatResponse.Messages);
-        }
-    }
-
-    /// <summary>
-    /// Gets the current <see cref="ChatClientAgent"/> and <see cref="ChatClientAgentSession"/> from the run context.
-    /// </summary>
-    private static (ChatClientAgent Agent, ChatClientAgentSession Session) GetRequiredAgentAndSession()
-    {
-        var runContext = AIAgent.CurrentRunContext
-            ?? throw new InvalidOperationException(
-                $"{nameof(ChatHistoryPersistingChatClient)} 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(ChatHistoryPersistingChatClient)} 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(ChatHistoryPersistingChatClient)} requires a {nameof(ChatClientAgentSession)}. " +
-                $"The current session is of type '{runContext.Session?.GetType().Name ?? "null"}'.");
-        }
-
-        return (chatClientAgent, chatClientAgentSession);
-    }
-
-    /// <summary>
-    /// Determines whether persistence should be deferred to end-of-run instead of happening immediately.
-    /// </summary>
-    /// <returns>
-    /// <see langword="true"/> when in <see cref="MarkOnly"/> mode, when the call is resuming from
-    /// a continuation token (since the end-of-run handler needs to combine data from the previous
-    /// and current runs), or when background responses are allowed (since the caller may stop
-    /// consuming the stream mid-run, preventing the post-stream persistence code from executing).
-    /// </returns>
-    private bool ShouldDeferPersistence(ChatOptions? options)
-    {
-        return this.MarkOnly || options?.ContinuationToken is not null || options?.AllowBackgroundResponses is true;
-    }
-
-    /// <summary>
-    /// Returns only the request messages that have not yet been persisted to chat history.
-    /// </summary>
-    /// <remarks>
-    /// A message is considered already persisted if any of the following is true:
-    /// <list type="bullet">
-    /// <item>It has the <see cref="PersistedMarkerKey"/> in its <see cref="ChatMessage.AdditionalProperties"/>.</item>
-    /// <item>It has an <see cref="AgentRequestMessageSourceType"/> of <see cref="AgentRequestMessageSourceType.ChatHistory"/>
-    /// (indicating it was loaded from chat history and does not need to be re-persisted).</item>
-    /// <item>It has <see cref="ChatMessage.Contents"/> and all of its <see cref="AIContent"/> items have the
-    /// <see cref="PersistedMarkerKey"/> in their <see cref="AIContent.AdditionalProperties"/>. This handles the
-    /// streaming case where <see cref="FunctionInvokingChatClient"/> reconstructs <see cref="ChatMessage"/> objects
-    /// independently via <c>ToChatResponse()</c>, producing different object references that share the same
-    /// underlying <see cref="AIContent"/> instances.</item>
-    /// </list>
-    /// </remarks>
-    /// <returns>A list of request messages that have not yet been persisted.</returns>
-    /// <param name="messages">The full set of request messages to filter.</param>
-    private static List<ChatMessage> GetNewRequestMessages(IEnumerable<ChatMessage> messages)
-    {
-        return messages.Where(m => !IsAlreadyPersisted(m)).ToList();
-    }
-
-    /// <summary>
-    /// Determines whether a message has already been persisted to chat history by this decorator.
-    /// </summary>
-    private static bool IsAlreadyPersisted(ChatMessage message)
-    {
-        if (message.AdditionalProperties?.TryGetValue(PersistedMarkerKey, out var value) == true && value is true)
-        {
-            return true;
-        }
-
-        if (message.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.ChatHistory)
-        {
-            return true;
-        }
-
-        // In streaming mode, FunctionInvokingChatClient reconstructs ChatMessage objects via ToChatResponse()
-        // independently, producing different ChatMessage instances. However, the underlying AIContent objects
-        // (e.g., FunctionCallContent, FunctionResultContent) are shared references. Checking for markers on
-        // AIContent handles dedup in this case.
-        if (message.Contents.Count > 0 && message.Contents.All(c => c.AdditionalProperties?.TryGetValue(PersistedMarkerKey, out var value) == true && value is true))
-        {
-            return true;
-        }
-
-        return false;
-    }
-
-    /// <summary>
-    /// Marks the given messages as persisted by setting a marker on both the <see cref="ChatMessage"/>
-    /// and each of its <see cref="AIContent"/> items.
-    /// </summary>
-    /// <remarks>
-    /// Both levels are marked because <see cref="FunctionInvokingChatClient"/> may reconstruct
-    /// <see cref="ChatMessage"/> objects in streaming mode (losing the message-level marker),
-    /// but the <see cref="AIContent"/> references are shared and retain their markers.
-    /// </remarks>
-    /// <param name="messages">The messages to mark as persisted.</param>
-    private static void MarkAsPersisted(IEnumerable<ChatMessage> messages)
-    {
-        foreach (var message in messages)
-        {
-            message.AdditionalProperties ??= new();
-            message.AdditionalProperties[PersistedMarkerKey] = true;
-
-            foreach (var content in message.Contents)
-            {
-                content.AdditionalProperties ??= new();
-                content.AdditionalProperties[PersistedMarkerKey] = true;
-            }
-        }
-    }
-
-    /// <summary>
-    /// If the <paramref name="options"/> carry the <see cref="LocalHistoryConversationId"/> sentinel,
-    /// returns a clone with the conversation ID cleared so the inner client never sees it.
-    /// Otherwise returns the original <paramref name="options"/> unchanged.
-    /// </summary>
-    private static ChatOptions? StripLocalHistoryConversationId(ChatOptions? options)
-    {
-        if (options?.ConversationId == LocalHistoryConversationId)
-        {
-            options = options.Clone();
-            options.ConversationId = null;
-        }
-
-        return options;
-    }
-}
@@ -0,0 +1,289 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// 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. It is activated when
+/// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> is <see langword="true"/>.
+/// </para>
+/// <para>
+/// 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
+/// <see cref="AIAgent.RunAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/> or
+/// <see cref="AIAgent.RunStreamingAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/>
+/// method is called. The <see cref="ChatClientAgent"/> ensures the run context always contains a resolved session,
+/// even when the caller passes null. An <see cref="InvalidOperationException"/> is thrown if no run context is
+/// available or if the agent is not a <see cref="ChatClientAgent"/>.
+/// </para>
+/// </remarks>
+internal sealed class PerServiceCallChatHistoryPersistingChatClient : DelegatingChatClient
+{
+    /// <summary>
+    /// A sentinel value returned on <see cref="ChatResponse.ConversationId"/> to signal
+    /// <see cref="FunctionInvokingChatClient"/> that chat history is being managed downstream.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When <see cref="FunctionInvokingChatClient"/> sees a non-null <see cref="ChatResponse.ConversationId"/>,
+    /// it treats the conversation as service-managed: it clears accumulated history between
+    /// iterations (via <c>FixupHistories</c>) and does not inject <see cref="FunctionCallContent"/>
+    /// into the request during approval-response processing (via <c>ProcessFunctionApprovalResponses</c>).
+    /// </para>
+    /// <para>
+    /// This decorator strips the sentinel from <see cref="ChatOptions.ConversationId"/> on incoming
+    /// requests before forwarding to the inner client, so the underlying model never sees it.
+    /// </para>
+    /// </remarks>
+    internal const string LocalHistoryConversationId = "_agent_local_chat_history";
+
+    /// <summary>
+    /// 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 PerServiceCallChatHistoryPersistingChatClient(IChatClient innerClient)
+        : base(innerClient)
+    {
+    }
+
+    /// <inheritdoc/>
+    public override async Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var (agent, session) = GetRequiredAgentAndSession();
+        options = StripLocalHistoryConversationId(options);
+
+        bool isServiceManaged = !string.IsNullOrEmpty(options?.ConversationId);
+        bool isContinuationOrBackground = options?.ContinuationToken is not null
+            || options?.AllowBackgroundResponses is true;
+        bool skipSimulation = isServiceManaged || isContinuationOrBackground;
+
+        var newMessages = messages as IList<ChatMessage> ?? messages.ToList();
+
+        // When simulating, load history and prepend it. When the service manages
+        // history (real ConversationId) or this is a continuation/background run,
+        // just forward the input messages as-is.
+        var messagesForService = skipSimulation
+            ? newMessages
+            : await agent.LoadChatHistoryAsync(session, newMessages, options, cancellationToken).ConfigureAwait(false);
+
+        ChatResponse response;
+        try
+        {
+            response = await base.GetResponseAsync(messagesForService, options, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await agent.NotifyProvidersOfFailureAsync(session, ex, newMessages, options, cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+
+        await agent.NotifyProvidersOfNewMessagesAsync(session, newMessages, response.Messages, options, cancellationToken).ConfigureAwait(false);
+
+        if (isContinuationOrBackground)
+        {
+            // Continuation/background run — the agent's forced end-of-run handles
+            // session ConversationId and persistence; the decorator is a no-op.
+        }
+        else if (isServiceManaged || !string.IsNullOrEmpty(response.ConversationId))
+        {
+            // Service manages history — update session with the real ConversationId.
+            agent.UpdateSessionConversationId(session, response.ConversationId, cancellationToken);
+        }
+        else
+        {
+            // Normal simulated path — set sentinel so FICC treats this as service-managed.
+            SetSentinelConversationId(response, session);
+        }
+
+        return response;
+    }
+
+    /// <inheritdoc/>
+    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var (agent, session) = GetRequiredAgentAndSession();
+        options = StripLocalHistoryConversationId(options);
+
+        bool isServiceManaged = !string.IsNullOrEmpty(options?.ConversationId);
+        bool isContinuationOrBackground = options?.ContinuationToken is not null
+            || options?.AllowBackgroundResponses is true;
+        bool skipSimulation = isServiceManaged || isContinuationOrBackground;
+
+        var newMessages = messages as IList<ChatMessage> ?? messages.ToList();
+
+        // When simulating, load history and prepend it. When the service manages
+        // history (real ConversationId) or this is a continuation/background run,
+        // just forward the input messages as-is.
+        var messagesForService = skipSimulation
+            ? newMessages
+            : await agent.LoadChatHistoryAsync(session, newMessages, options, cancellationToken).ConfigureAwait(false);
+
+        List<ChatResponseUpdate> responseUpdates = [];
+
+        IAsyncEnumerator<ChatResponseUpdate> enumerator;
+        try
+        {
+            enumerator = base.GetStreamingResponseAsync(messagesForService, options, cancellationToken).GetAsyncEnumerator(cancellationToken);
+        }
+        catch (Exception ex)
+        {
+            await agent.NotifyProvidersOfFailureAsync(session, ex, newMessages, options, cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+
+        bool hasUpdates;
+        try
+        {
+            hasUpdates = await enumerator.MoveNextAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await agent.NotifyProvidersOfFailureAsync(session, ex, newMessages, options, cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+
+        while (hasUpdates)
+        {
+            var update = enumerator.Current;
+            responseUpdates.Add(update);
+
+            // If the service returned a real ConversationId on any update, remember that.
+            // Otherwise stamp our sentinel so FICC treats this as service-managed —
+            // unless this is a continuation/background run where the agent handles everything.
+            if (!string.IsNullOrEmpty(update.ConversationId))
+            {
+                isServiceManaged = true;
+            }
+            else if (!skipSimulation)
+            {
+                update.ConversationId = LocalHistoryConversationId;
+            }
+
+            yield return update;
+
+            try
+            {
+                hasUpdates = await enumerator.MoveNextAsync().ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                await agent.NotifyProvidersOfFailureAsync(session, ex, newMessages, options, cancellationToken).ConfigureAwait(false);
+                throw;
+            }
+        }
+
+        var chatResponse = responseUpdates.ToChatResponse();
+
+        await agent.NotifyProvidersOfNewMessagesAsync(session, newMessages, chatResponse.Messages, options, cancellationToken).ConfigureAwait(false);
+
+        if (isContinuationOrBackground)
+        {
+            // Continuation/background run — the agent's forced end-of-run handles
+            // session ConversationId and persistence; the decorator is a no-op.
+        }
+        else if (isServiceManaged)
+        {
+            // Service manages history — update session with the real ConversationId.
+            agent.UpdateSessionConversationId(session, chatResponse.ConversationId, cancellationToken);
+        }
+        else
+        {
+            // Normal simulated path — set sentinel on session.
+            session.ConversationId = LocalHistoryConversationId;
+        }
+    }
+
+    /// <summary>
+    /// Sets the sentinel <see cref="LocalHistoryConversationId"/> on the response and session
+    /// so that <see cref="FunctionInvokingChatClient"/> treats the conversation as service-managed.
+    /// </summary>
+    private static void SetSentinelConversationId(ChatResponse response, ChatClientAgentSession session)
+    {
+        response.ConversationId = LocalHistoryConversationId;
+        session.ConversationId = LocalHistoryConversationId;
+    }
+
+    /// <summary>
+    /// Gets the current <see cref="ChatClientAgent"/> and <see cref="ChatClientAgentSession"/> from the run context.
+    /// </summary>
+    private static (ChatClientAgent Agent, ChatClientAgentSession Session) GetRequiredAgentAndSession()
+    {
+        var runContext = AIAgent.CurrentRunContext
+            ?? throw new InvalidOperationException(
+                $"{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(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(PerServiceCallChatHistoryPersistingChatClient)} requires a {nameof(ChatClientAgentSession)}. " +
+                $"The current session is of type '{runContext.Session?.GetType().Name ?? "null"}'.");
+        }
+
+        return (chatClientAgent, chatClientAgentSession);
+    }
+
+    /// <summary>
+    /// If the <paramref name="options"/> carry the <see cref="LocalHistoryConversationId"/> sentinel,
+    /// returns a clone with the conversation ID cleared so the inner client never sees it.
+    /// Otherwise returns the original <paramref name="options"/> unchanged.
+    /// </summary>
+    private static ChatOptions? StripLocalHistoryConversationId(ChatOptions? options)
+    {
+        if (options?.ConversationId == LocalHistoryConversationId)
+        {
+            options = options.Clone();
+            options.ConversationId = null;
+        }
+
+        return options;
+    }
+}
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
+<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProvider</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProviderOptions</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProvider</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProviderOptions</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProvider</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProviderOptions</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProvider</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProviderOptions</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProvider</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Microsoft.Agents.AI.FileAgentSkillsProviderOptions</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+</Suppressions>
--- a/Show More
+++ b/Show More