Merge branch 'main' into taochen/python-update-sample-validation-scripts

.github/actions/setup-local-mcp-server/action.yml

@@ -1,166 +0,0 @@
-name: Setup Local MCP Server
-description: Start and validate a local streamable HTTP MCP server for integration tests
-
-inputs:
-  fallback_url:
-    description: Existing LOCAL_MCP_URL value to keep as a fallback if local startup fails
-    required: false
-    default: ''
-  host:
-    description: Host interface to bind the local MCP server
-    required: false
-    default: '127.0.0.1'
-  port:
-    description: Port to bind the local MCP server
-    required: false
-    default: '8011'
-  mount_path:
-    description: Mount path for the local streamable HTTP MCP endpoint
-    required: false
-    default: '/mcp'
-
-outputs:
-  effective_url:
-    description: Local MCP URL when startup succeeds, otherwise the provided fallback URL
-    value: ${{ steps.start.outputs.effective_url }}
-  local_url:
-    description: URL of the local MCP server
-    value: ${{ steps.start.outputs.local_url }}
-  started:
-    description: Whether the local MCP server started and passed validation
-    value: ${{ steps.start.outputs.started }}
-  pid:
-    description: PID of the local MCP server process when startup succeeded
-    value: ${{ steps.start.outputs.pid }}
-
-runs:
-  using: composite
-  steps:
-    - name: Start and validate local MCP server
-      id: start
-      shell: bash
-      run: |
-        set -euo pipefail
-
-        host="${{ inputs.host }}"
-        port="${{ inputs.port }}"
-        mount_path="${{ inputs.mount_path }}"
-        fallback_url="${{ inputs.fallback_url }}"
-
-        if [[ ! "$mount_path" =~ ^/ ]]; then
-          mount_path="/$mount_path"
-        fi
-
-        local_url="http://${host}:${port}${mount_path}"
-        health_url="http://${host}:${port}/healthz"
-        log_file="$RUNNER_TEMP/local-mcp-server.log"
-        pid_file="$RUNNER_TEMP/local-mcp-server.pid"
-        rm -f "$log_file" "$pid_file"
-
-        server_pid="$(
-          python3 - "$GITHUB_WORKSPACE/python" "$log_file" "$host" "$port" "$mount_path" <<'PY'
-        from __future__ import annotations
-
-        import subprocess
-        import sys
-
-        workspace, log_file, host, port, mount_path = sys.argv[1:]
-
-        with open(log_file, "w", encoding="utf-8") as log:
-            process = subprocess.Popen(
-                [
-                    "uv",
-                    "run",
-                    "python",
-                    "scripts/local_mcp_streamable_http_server.py",
-                    "--host",
-                    host,
-                    "--port",
-                    port,
-                    "--mount-path",
-                    mount_path,
-                ],
-                cwd=workspace,
-                stdout=log,
-                stderr=subprocess.STDOUT,
-                start_new_session=True,
-            )
-
-        print(process.pid)
-        PY
-        )"
-        echo "$server_pid" > "$pid_file"
-
-        started=false
-        for _ in $(seq 1 30); do
-          if curl --silent --fail "$health_url" >/dev/null; then
-            started=true
-            break
-          fi
-          if ! kill -0 "$server_pid" 2>/dev/null; then
-            break
-          fi
-          sleep 1
-        done
-
-        if [[ "$started" == "true" ]]; then
-          if ! (
-            cd "$GITHUB_WORKSPACE/python"
-            LOCAL_MCP_URL="$local_url" uv run python - <<'PY'
-        from __future__ import annotations
-
-        import asyncio
-        import os
-
-        from agent_framework import Content, MCPStreamableHTTPTool
-
-
-        def result_to_text(result: str | list[Content]) -> str:
-            if isinstance(result, str):
-                return result
-            return "\n".join(content.text for content in result if content.type == "text" and content.text)
-
-
-        async def main() -> None:
-            tool = MCPStreamableHTTPTool(
-                name="local_ci_mcp",
-                url=os.environ["LOCAL_MCP_URL"],
-                approval_mode="never_require",
-            )
-
-            async with tool:
-                assert tool.functions, "Local MCP server did not expose any tools."
-                result = result_to_text(await tool.functions[0].invoke(query="What is Agent Framework?"))
-                assert result, "Local MCP server returned an empty response."
-
-
-        asyncio.run(main())
-        PY
-          ); then
-            started=false
-          fi
-        fi
-
-        effective_url="$local_url"
-        pid="$server_pid"
-
-        if [[ "$started" != "true" ]]; then
-          effective_url="$fallback_url"
-          pid=""
-          if kill -0 "$server_pid" 2>/dev/null; then
-            kill -TERM -- "-$server_pid" 2>/dev/null || kill -TERM "$server_pid" || true
-            sleep 1
-            kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" || true
-          fi
-          echo "Local MCP server was unavailable; continuing with fallback LOCAL_MCP_URL."
-          if [[ -f "$log_file" ]]; then
-            tail -n 100 "$log_file" || true
-          fi
-        else
-          echo "Using local MCP server at $local_url"
-        fi
-
-        echo "started=$started" >> "$GITHUB_OUTPUT"
-        echo "local_url=$local_url" >> "$GITHUB_OUTPUT"
-        echo "effective_url=$effective_url" >> "$GITHUB_OUTPUT"
-        echo "pid=$pid" >> "$GITHUB_OUTPUT"

.github/workflows/python-check-coverage.py

@@ -41,7 +41,8 @@ ENFORCED_TARGETS: set[str] = {
     "packages.purview.agent_framework_purview",
     "packages.anthropic.agent_framework_anthropic",
     "packages.azure-ai-search.agent_framework_azure_ai_search",
-    "packages.openai.agent_framework_openai",
+    "packages.core.agent_framework.azure",
+    "packages.core.agent_framework.openai",
     # Individual files (if you want to enforce specific files instead of whole packages)
     "packages/core/agent_framework/observability.py",
     # Add more targets here as coverage improves

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

@@ -60,10 +60,9 @@ jobs:
     environment: integration
     timeout-minutes: 60
     env:
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
     defaults:
       run:
@@ -82,8 +81,8 @@ jobs:
       - name: Test with pytest (OpenAI integration)
         run: >
           uv run pytest --import-mode=importlib
-          packages/openai/tests
-          -m "integration and not azure"
+          packages/core/tests/openai
+          -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
@@ -97,8 +96,7 @@ jobs:
     env:
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
       AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
+      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
       AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
     defaults:
       run:
@@ -123,11 +121,7 @@ jobs:
       - name: Test with pytest (Azure OpenAI integration)
         run: >
           uv run pytest --import-mode=importlib
-          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
+          packages/core/tests/azure
           -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
@@ -157,13 +151,6 @@ jobs:
         with:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
-      - name: Start local MCP server
-        id: local-mcp
-        uses: ./.github/actions/setup-local-mcp-server
-        with:
-          fallback_url: ${{ env.LOCAL_MCP_URL }}
-      - name: Prefer local MCP URL when available
-        run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
       - name: Test with pytest (Anthropic, Ollama, MCP integration)
         run: >
           uv run pytest --import-mode=importlib
@@ -174,26 +161,6 @@ jobs:
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
-      - name: Stop local MCP server
-        if: always()
-        shell: bash
-        run: |
-          set -euo pipefail
-          server_pid="${{ steps.local-mcp.outputs.pid }}"
-          if [[ -z "$server_pid" ]]; then
-            exit 0
-          fi
-          if ! kill -0 "$server_pid" 2>/dev/null; then
-            exit 0
-          fi
-          kill -TERM -- "-$server_pid" 2>/dev/null || kill -TERM "$server_pid" 2>/dev/null || true
-          for _ in $(seq 1 10); do
-            if ! kill -0 "$server_pid" 2>/dev/null; then
-              exit 0
-            fi
-            sleep 1
-          done
-          kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" 2>/dev/null || true
 
   # Azure Functions + Durable Task integration tests
   python-tests-functions:
@@ -203,16 +170,12 @@ jobs:
     timeout-minutes: 60
     env:
       UV_PYTHON: "3.11"
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
       FUNCTIONS_WORKER_RUNTIME: "python"
       DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
       AzureWebJobsStorage: "UseDevelopmentStorage=true"
@@ -246,23 +209,18 @@ jobs:
           packages/durabletask/tests/integration_tests
           -m integration
           -n logical --dist worksteal
-          -x
-          --timeout=360 --session-timeout=900 --timeout_method thread
+          --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
 
-  # Foundry integration tests
-  python-tests-foundry:
-    name: Python Integration Tests - Foundry
+  # Azure AI integration tests
+  python-tests-azure-ai:
+    name: Python Integration Tests - Azure AI
     runs-on: ubuntu-latest
     environment: integration
     timeout-minutes: 60
     env:
       AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
       AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
-      FOUNDRY_AGENT_NAME: ${{ vars.FOUNDRY_AGENT_NAME }}
-      FOUNDRY_AGENT_VERSION: ${{ vars.FOUNDRY_AGENT_VERSION }}
       LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
     defaults:
       run:
@@ -286,14 +244,7 @@ jobs:
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
         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
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
 
   # Azure Cosmos integration tests
   python-tests-cosmos:
@@ -350,7 +301,7 @@ jobs:
         python-tests-azure-openai,
         python-tests-misc-integration,
         python-tests-functions,
-        python-tests-foundry,
+        python-tests-azure-ai,
         python-tests-cosmos
       ]
     steps:

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

@@ -47,9 +47,6 @@ jobs:
           filters: |
             python:
               - 'python/**'
-              - '.github/actions/setup-local-mcp-server/**'
-              - '.github/workflows/python-merge-tests.yml'
-              - '.github/workflows/python-integration-tests.yml'
             core:
               - 'python/packages/core/agent_framework/_*.py'
               - 'python/packages/core/agent_framework/_workflows/**'
@@ -57,30 +54,20 @@ jobs:
               - 'python/packages/core/agent_framework/observability.py'
             openai:
               - 'python/packages/core/agent_framework/openai/**'
-              - 'python/packages/openai/**'
-              - 'python/samples/**/providers/openai/**'
+              - 'python/packages/core/tests/openai/**'
             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/packages/core/tests/azure/**'
             misc:
               - 'python/packages/anthropic/**'
               - 'python/packages/ollama/**'
               - 'python/packages/core/agent_framework/_mcp.py'
               - 'python/packages/core/tests/core/test_mcp.py'
-              - 'python/scripts/local_mcp_streamable_http_server.py'
-              - '.github/actions/setup-local-mcp-server/**'
-              - '.github/workflows/python-merge-tests.yml'
-              - '.github/workflows/python-integration-tests.yml'
             functions:
               - 'python/packages/azurefunctions/**'
               - 'python/packages/durabletask/**'
             azure-ai:
               - 'python/packages/azure-ai/**'
-              - 'python/packages/foundry/**'
-              - 'python/samples/**/providers/foundry/**'
             cosmos:
               - 'python/packages/azure-cosmos/**'
       # run only if 'python' files were changed
@@ -141,10 +128,9 @@ jobs:
     runs-on: ubuntu-latest
     environment: integration
     env:
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
     defaults:
       run:
@@ -160,8 +146,8 @@ jobs:
       - name: Test with pytest (OpenAI integration)
         run: >
           uv run pytest --import-mode=importlib
-          packages/openai/tests
-          -m "integration and not azure"
+          packages/core/tests/openai
+          -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
@@ -196,8 +182,7 @@ jobs:
     env:
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
       AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
+      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
       AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
     defaults:
       run:
@@ -220,11 +205,7 @@ jobs:
       - name: Test with pytest (Azure OpenAI integration)
         run: >
           uv run pytest --import-mode=importlib
-          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
+          packages/core/tests/azure
           -m integration
           -n logical --dist worksteal
           --timeout=120 --session-timeout=900 --timeout_method thread
@@ -272,13 +253,6 @@ jobs:
         with:
           python-version: ${{ env.UV_PYTHON }}
           os: ${{ runner.os }}
-      - name: Start local MCP server
-        id: local-mcp
-        uses: ./.github/actions/setup-local-mcp-server
-        with:
-          fallback_url: ${{ env.LOCAL_MCP_URL }}
-      - name: Prefer local MCP URL when available
-        run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
       - name: Test with pytest (Anthropic, Ollama, MCP integration)
         run: >
           uv run pytest --import-mode=importlib
@@ -290,26 +264,6 @@ jobs:
           --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
         working-directory: ./python
-      - name: Stop local MCP server
-        if: always()
-        shell: bash
-        run: |
-          set -euo pipefail
-          server_pid="${{ steps.local-mcp.outputs.pid }}"
-          if [[ -z "$server_pid" ]]; then
-            exit 0
-          fi
-          if ! kill -0 "$server_pid" 2>/dev/null; then
-            exit 0
-          fi
-          kill -TERM -- "-$server_pid" 2>/dev/null || kill -TERM "$server_pid" 2>/dev/null || true
-          for _ in $(seq 1 10); do
-            if ! kill -0 "$server_pid" 2>/dev/null; then
-              exit 0
-            fi
-            sleep 1
-          done
-          kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" 2>/dev/null || true
       - name: Surface failing tests
         if: always()
         uses: pmeier/pytest-results-action@v0.7.2
@@ -334,16 +288,12 @@ jobs:
     environment: integration
     env:
       UV_PYTHON: "3.11"
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
       FUNCTIONS_WORKER_RUNTIME: "python"
       DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
       AzureWebJobsStorage: "UseDevelopmentStorage=true"
@@ -375,8 +325,7 @@ jobs:
           packages/durabletask/tests/integration_tests
           -m integration
           -n logical --dist worksteal
-          -x
-          --timeout=360 --session-timeout=900 --timeout_method thread
+          --timeout=120 --session-timeout=900 --timeout_method thread
           --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Surface failing tests
@@ -389,8 +338,8 @@ jobs:
           fail-on-empty: false
           title: Functions integration test results
 
-  python-tests-foundry:
-    name: Python Integration Tests - Foundry
+  python-tests-azure-ai:
+    name: Python Tests - Azure AI
     needs: paths-filter
     if: >
       github.event_name != 'pull_request' &&
@@ -403,10 +352,6 @@ jobs:
     env:
       AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
       AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
-      FOUNDRY_AGENT_NAME: ${{ vars.FOUNDRY_AGENT_NAME }}
-      FOUNDRY_AGENT_VERSION: ${{ vars.FOUNDRY_AGENT_VERSION }}
       LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
     defaults:
       run:
@@ -428,14 +373,7 @@ jobs:
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
         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
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Test Azure AI samples
         timeout-minutes: 10
@@ -522,7 +460,7 @@ jobs:
         python-tests-azure-openai,
         python-tests-misc-integration,
         python-tests-functions,
-        python-tests-foundry,
+        python-tests-azure-ai,
         python-tests-cosmos,
       ]
     steps:

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

@@ -78,7 +78,6 @@ jobs:
       OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
       # GitHub MCP
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
       # Observability
       ENABLE_INSTRUMENTATION: "true"
     defaults:
@@ -347,7 +346,7 @@ jobs:
 
   validate-02-agents-amazon:
     name: Validate 02-agents/providers/amazon
-    if: false # Temporarily disabled - requires AWS credentials
+    if: false  # Temporarily disabled - requires AWS credentials
     runs-on: ubuntu-latest
     environment: integration
     env:
@@ -379,7 +378,7 @@ jobs:
 
   validate-02-agents-ollama:
     name: Validate 02-agents/providers/ollama
-    if: false # Temporarily disabled - requires local Ollama server
+    if: false  # Temporarily disabled - requires local Ollama server
     runs-on: ubuntu-latest
     environment: integration
     env:
@@ -411,7 +410,7 @@ jobs:
 
   validate-02-agents-foundry-local:
     name: Validate 02-agents/providers/foundry_local
-    if: false # Temporarily disabled - requires local Foundry setup
+    if: false  # Temporarily disabled - requires local Foundry setup
     runs-on: ubuntu-latest
     environment: integration
     defaults:
@@ -441,7 +440,7 @@ jobs:
 
   validate-02-agents-copilotstudio:
     name: Validate 02-agents/providers/copilotstudio
-    if: false # Temporarily disabled - requires Copilot Studio setup
+    if: false  # Temporarily disabled - requires Copilot Studio setup
     runs-on: ubuntu-latest
     environment: integration
     env:
@@ -557,7 +556,7 @@ jobs:
 
   validate-04-hosting:
     name: Validate 04-hosting
-    if: false # Temporarily disabled because of sample complexity
+    if: false  # Temporarily disabled because of sample complexity
     runs-on: ubuntu-latest
     environment: integration
     env:
@@ -596,7 +595,7 @@ jobs:
 
   validate-05-end-to-end:
     name: Validate 05-end-to-end
-    if: false # Temporarily disabled because of sample complexity
+    if: false  # Temporarily disabled because of sample complexity
     runs-on: ubuntu-latest
     environment: integration
     env:
@@ -653,7 +652,6 @@ jobs:
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
       OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
       OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
     defaults:
       run:
         working-directory: python
@@ -705,7 +703,6 @@ jobs:
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
       OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
       OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
       # Copilot Studio
       COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
       COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}

docs/decisions/0021-agent-skills-design.md

@@ -1,960 +0,0 @@
-status: proposed
-date: 2026-03-23
-contact: sergeymenshykh
-deciders: rbarreto, westey-m, eavanvalkenburg
----
-
-# Agent Skills: Multi-Source Architecture
-
-## Context and Problem Statement
-
-The Agent Framework needs a skills system that lets agents discover and use domain-specific knowledge, reference documents, and executable scripts. Skills can originate from different sources — filesystem directories (SKILL.md files), inline C# code, or reusable class libraries — and the framework must support all three uniformly while allowing extensibility, composition, and filtering.
-
-## Decision Drivers
-
-- Skills must be definable from multiple sources: filesystem, inline code, reusable classes, etc
-- Common abstractions are needed so the provider and builder work uniformly regardless of skill origin
-- File-based scripts must support user-defined executors, enabling custom runtimes and languages; code/class-based scripts execute in-process as C# delegates
-- Skills must be filterable so consumers can include or exclude specific skills based on defined criteria
-- Multiple skill sources must be composable into a single provider
-- It must be possible to add custom skill sources (e.g., databases, REST APIs, package registries) by implementing a common abstraction
-
-## Architecture
-
-### Model-Facing Tools
-
-Skills are presented to the model as up to three tools that progressively disclose skill content. The system prompt lists available skill names and descriptions; the model then calls these tools on demand:
-
-- **`load_skill(skillName)`** — returns the full skill body (instructions, listed resources, listed scripts)
-- **`read_skill_resource(skillName, resourceName)`** — reads a supplementary resource (file-based or code-defined) associated with a skill
-- **`run_skill_script(skillName, scriptName, arguments?)`** — executes a script associated with a skill; only registered when at least one skill contains scripts
-
-Each tool delegates to the corresponding method on the resolved `AgentSkill` — calling `Resource.ReadAsync()` or `Script.RunAsync()` respectively.
-
-If skills have no scripts defined, the `run_skill_script` tool is **not advertised** to the model and instructions related to script execution are **not included** in the default skills instructions.
-
-### Abstract Base Types
-
-The architecture defines four abstract base types that all skill variants implement:
-
-```csharp
-public abstract class AgentSkill
-{
-    public abstract AgentSkillFrontmatter Frontmatter { get; }
-    public abstract string Content { get; }
-    public abstract IReadOnlyList<AgentSkillResource>? Resources { get; }
-    public abstract IReadOnlyList<AgentSkillScript>? Scripts { get; }
-}
-
-public abstract class AgentSkillResource
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default);
-}
-
-public abstract class AgentSkillScript
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default);
-}
-
-public abstract class AgentSkillsSource
-{
-    public abstract Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default);
-}
-```
-
-Skill metadata is captured via `AgentSkillFrontmatter`:
-
-```csharp
-public sealed class AgentSkillFrontmatter
-{
-    public AgentSkillFrontmatter(string name, string description) { ... }
-
-    public string Name { get; }
-    public string Description { get; }
-    public string? License { get; set; }
-    public string? Compatibility { get; set; }
-    public string? AllowedTools { get; set; }
-    public AdditionalPropertiesDictionary? Metadata { get; set; }
-}
-```
-
-The type hierarchy at a glance:
-
-```
-AgentSkill (abstract)                   AgentSkillsSource (abstract)
-├── AgentFileSkill                      ├── AgentFileSkillsSource          (public)
-└── [Programmatic]                      ├── AgentInMemorySkillsSource      (public)
-    ├── AgentInlineSkill                ├── AggregatingAgentSkillsSource     (public)
-    └── AgentClassSkill (abstract)      └── DelegatingAgentSkillsSource    (abstract, public)
-                                            ├── FilteringAgentSkillsSource  (public)
-AgentSkillResource (abstract)               ├── CachingAgentSkillsSource    (public)
-├── AgentFileSkillResource                  └── DeduplicatingAgentSkillsSource (public)
-└── AgentInlineSkillResource
-                                        AgentSkillScript (abstract)
-                                        ├── AgentFileSkillScript
-                                        └── AgentInlineSkillScript
-```
-
-There are two top-level categories of skills:
-
-1. **File-Based Skills** — discovered from `SKILL.md` files on the filesystem. Resources and scripts are files in subdirectories.
-2. **Programmatic Skills** — defined in C# code. These are further divided into:
-   - **Inline Skills** — built at runtime via the `AgentInlineSkill` class and its fluent API. Ideal for quick, agent-specific skill definitions.
-   - **Class-Based Skills** — defined as reusable C# classes that subclass `AgentClassSkill`. Ideal for packaging skills as shared libraries or NuGet packages.
-
-Both programmatic skill types use `AgentInlineSkillResource` and `AgentInlineSkillScript` for their resources and scripts. They are typically served by `AgentInMemorySkillsSource`, which accepts any `AgentSkill` and is not limited to programmatic skills.
-
-### File-Based Skills
-
-File-based skills are authored as `SKILL.md` files on disk. Resources and scripts are discovered from corresponding subfolders within the skill directory.
-
-**`AgentFileSkill`** — A filesystem-based skill discovered from a directory containing a `SKILL.md` file. Parsed from YAML frontmatter; content is the raw markdown body. Resources and scripts are discovered from files in corresponding subfolders:
-
-```csharp
-public sealed class AgentFileSkill : AgentSkill
-{
-    internal AgentFileSkill(
-        AgentSkillFrontmatter frontmatter, string content, string path,
-        IReadOnlyList<AgentSkillResource>? resources = null,
-        IReadOnlyList<AgentSkillScript>? scripts = null) { ... }
-}
-```
-
-**`AgentFileSkillResource`** — A file-based skill resource. Reads content from a file on disk relative to the skill directory:
-
-```csharp
-internal sealed class AgentFileSkillResource : AgentSkillResource
-{
-    public AgentFileSkillResource(string name, string fullPath) { ... }
-
-    public string FullPath { get; }
-
-    public override Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
-    {
-        return File.ReadAllTextAsync(FullPath, Encoding.UTF8, cancellationToken);
-    }
-}
-```
-
-**`AgentFileSkillScript`** — A file-based skill script that represents a script file on disk. Delegates execution to an external `AgentFileSkillScriptRunner` callback (e.g., runs Python/shell via `Process.Start`). Throws `NotSupportedException` if no executor is configured:
-
-```csharp
-public delegate Task<object?> AgentFileSkillScriptRunner(
-    AgentFileSkill skill, AgentFileSkillScript script,
-    AIFunctionArguments arguments, CancellationToken cancellationToken);
-
-public sealed class AgentFileSkillScript : AgentSkillScript
-{
-    private readonly AgentFileSkillScriptRunner _executor;
-
-    internal AgentFileSkillScript(string name, string fullPath, AgentFileSkillScriptRunner executor)
-        : base(name) { ... }
-
-    public override async Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, ...)
-    {
-
-        return await _executor(fileSkill, this, arguments, cancellationToken);
-    }
-}
-```
-
-The executor can be provided at the **provider level** via `AgentSkillsProviderBuilder.UseFileScriptRunner(executor)` and optionally overridden for a **particular file skill** or for a **set of skills** at the file skill source level, giving fine-grained control over how different scripts are executed.
-
-**`AgentFileSkillsSource`** — A skill source that discovers skills from filesystem directories containing `SKILL.md` files. Recursively scans directories (max 2 levels), validates frontmatter, and enforces path traversal and symlink security checks:
-
-```csharp
-public sealed partial class AgentFileSkillsSource : AgentSkillsSource
-{
-    public AgentFileSkillsSource(
-        IEnumerable<string> skillPaths,
-        AgentFileSkillScriptRunner scriptRunner,
-        AgentFileSkillsSourceOptions? options = null,
-        ILoggerFactory? loggerFactory = null) { ... }
-}
-```
-
-**`AgentFileSkillsSourceOptions`** — Configuration options for `AgentFileSkillsSource`. Allows customizing the allowed file extensions for resources and scripts without adding constructor parameters:
-
-```csharp
-public sealed class AgentFileSkillsSourceOptions
-{
-    public IEnumerable<string>? AllowedResourceExtensions { get; set; }
-    public IEnumerable<string>? AllowedScriptExtensions { get; set; }
-}
-```
-
-**Example** — A file-based skill on disk and how it is added to a source:
-
-```
-skills/
-└── unit-converter/
-    ├── SKILL.md               # frontmatter + instructions
-    ├── resources/
-    │   └── conversion-table.csv   # discovered as a resource
-    └── scripts/
-        └── convert.py             # discovered as a script
-```
-
-```csharp
-var source = new AgentFileSkillsSource(skillPaths: ["./skills"], scriptRunner: SubprocessScriptRunner.RunAsync);
-
-var provider = new AgentSkillsProvider(source);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-### Programmatic Skills
-
-Programmatic skills are defined in C# code rather than discovered from the filesystem. There are two kinds: **inline** and **class-based**. Both use `AgentInlineSkillResource` and `AgentInlineSkillScript` for resources and scripts, and are held by a single `AgentInMemorySkillsSource`.
-
-**`AgentInMemorySkillsSource`** — A general-purpose skill source that holds any `AgentSkill` instances in memory. Although commonly used for programmatic skills (`AgentInlineSkill` and `AgentClassSkill`), it accepts any `AgentSkill` subclass and is not restricted to code-defined skills:
-
-```csharp
-public sealed class AgentInMemorySkillsSource : AgentSkillsSource
-{
-    public AgentInMemorySkillsSource(
-        IEnumerable<AgentSkill> skills,
-        ILoggerFactory? loggerFactory = null) { ... }
-}
-```
-
-#### Inline Skills
-
-Inline skills are built at runtime via the `AgentInlineSkill` class and its fluent API. They are ideal for quick, agent-specific skill definitions where a full class hierarchy would be overkill.
-
-**`AgentInlineSkill`** — A skill defined entirely in code. Resources can be static values or functions; scripts are always functions. Constructed with name, description, and instructions, then extended with resources and scripts:
-
-```csharp
-public sealed class AgentInlineSkill : AgentSkill
-{
-    public AgentInlineSkill(string name, string description, string instructions, string? license = null, string? compatibility = null, ...) { ... }
-    public AgentInlineSkill(AgentSkillFrontmatter frontmatter, string instructions) { ... }
-
-    public AgentInlineSkill AddResource(object value, string name, string? description = null);
-    public AgentInlineSkill AddResource(Delegate handler, string name, string? description = null);
-    public AgentInlineSkill AddScript(Delegate handler, string name, string? description = null);
-}
-```
-
-**`AgentInlineSkillResource`** — A skill resource that wraps a static value:
-
-```csharp
-public sealed class AgentInlineSkillResource : AgentSkillResource
-{
-    public AgentInlineSkillResource(object value, string name, string? description = null)
-        : base(name, description)
-    {
-        _value = value;
-    }
-
-    public override Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
-    {
-        return Task.FromResult<object?>(_value);
-    }
-}
-```
-
-**`AgentInlineSkillResource`** — A skill resource backed by a delegate. The delegate is invoked via an `AIFunction` each time `ReadAsync` is called, producing a dynamic (computed) value:
-
-```csharp
-public sealed class AgentInlineSkillResource : AgentSkillResource
-{
-    public AgentInlineSkillResource(Delegate handler, string name, string? description = null)
-        : base(name, description)
-    {
-        _function = AIFunctionFactory.Create(handler, name: name);
-    }
-
-    public override async Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
-    {
-        return await _function.InvokeAsync(new AIFunctionArguments() { Services = serviceProvider }, cancellationToken);
-    }
-}
-```
-
-**`AgentInlineSkillScript`** — A skill script backed by a delegate via an `AIFunction`:
-
-```csharp
-public sealed class AgentInlineSkillScript : AgentSkillScript
-{
-    private readonly AIFunction _function;
-
-    public AgentInlineSkillScript(Delegate handler, string name, string? description = null)
-        : base(name, description)
-    {
-        _function = AIFunctionFactory.Create(handler, name: name);
-    }
-
-    public JsonElement? ParametersSchema => _function.JsonSchema;
-
-    public override async Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, ...)
-    {
-        return await _function.InvokeAsync(arguments, cancellationToken);
-    }
-}
-```
-
-**Example** — Creating an inline skill with a resource and script, then adding it to a source:
-
-```csharp
-var skill = new AgentInlineSkill(
-        name: "unit-converter",
-        description: "Converts between measurement units.",
-        instructions: """
-            Use this skill to convert values between metric and imperial units.
-            Refer to the conversion-table resource for supported unit pairs.
-            Run the convert script to perform conversions.
-            """
-    )
-    .AddResource("kg=2.205lb, m=3.281ft, L=0.264gal", "conversion-table", "Supported unit pairs")
-    .AddScript(Convert, "convert", "Converts a value between units");
-
-var source = new AgentInMemorySkillsSource([skill]);
-
-var provider = new AgentSkillsProvider(source);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-
-static string Convert(double value, double factor)
-    => JsonSerializer.Serialize(new { result = Math.Round(value * factor, 4) });
-```
-
-#### Class-Based Skills
-
-Class-based skills are designed for packaging skills as reusable libraries. Users subclass `AgentClassSkill` and override properties. Unlike inline skills, class-based skills are self-contained, can live in shared libraries or NuGet packages, and are well-suited for dependency injection.
-
-**`AgentClassSkill`** — An abstract base class for defining skills as reusable C# classes that bundle all skill components (frontmatter, instructions, resources, scripts) together. Designed for packaging skills as distributable libraries:
-
-```csharp
-public abstract class AgentClassSkill : AgentSkill
-{
-    public abstract string Instructions { get; }
-
-    // Content is auto-synthesized from Frontmatter + Instructions + Resources + Scripts
-    public override string Content =>
-        SkillContentBuilder.BuildContent(Frontmatter.Name, Frontmatter.Description,
-            SkillContentBuilder.BuildBody(Instructions, Resources, Scripts));
-}
-```
-
-**Example** — Defining a class-based skill and adding it to a source:
-
-```csharp
-public class UnitConverterSkill : AgentClassSkill
-{
-    public override AgentSkillFrontmatter Frontmatter { get; } =
-        new("unit-converter", "Converts between measurement units.");
-
-    public override string Instructions => """
-        Use this skill to convert values between metric and imperial units.
-        Refer to the conversion-table resource for supported unit pairs.
-        Run the convert script to perform conversions.
-        """;
-
-    public override IReadOnlyList<AgentSkillResource>? Resources { get; } =
-    [
-        new AgentInlineSkillResource("kg=2.205lb, m=3.281ft", "conversion-table"),
-    ];
-
-    public override IReadOnlyList<AgentSkillScript>? Scripts { get; } =
-    [
-        new AgentInlineSkillScript(Convert, "convert"),
-    ];
-
-    private static string Convert(double value, double factor)
-        => JsonSerializer.Serialize(new { result = Math.Round(value * factor, 4) });
-}
-
-var source = new AgentInMemorySkillsSource([new UnitConverterSkill()]);
-
-var provider = new AgentSkillsProvider(source);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-## Filtering, Caching, and Deduplication
-
-The following subsections present alternative approaches for handling filtering, caching, and deduplication of skills across multiple sources.
-
-### Via Composition
-
-In this approach, the `AgentSkillsProvider` accepts a **single** `AgentSkillsSource`. Multiple sources are composed externally via an aggregate source, and cross-cutting concerns like filtering, caching, and deduplication are implemented as **source decorators** — subclasses of `DelegatingAgentSkillsSource` that intercept `GetSkillsAsync()`.
-
-**`FilteringAgentSkillsSource`** — A decorator that applies filter logic before returning results. The decorator pattern keeps filtering orthogonal to source implementations and allows composing multiple filters:
-
-```csharp
-public sealed class FilteringAgentSkillsSource : DelegatingAgentSkillsSource
-{
-    private readonly Func<AgentSkill, bool> _predicate;
-
-    public FilteringAgentSkillsSource(AgentSkillsSource innerSource, Func<AgentSkill, bool> predicate)
-        : base(innerSource)
-    {
-        _predicate = predicate;
-    }
-
-    public override async Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)
-    {
-        var skills = await this.InnerSource.GetSkillsAsync(cancellationToken);
-        return skills.Where(_predicate).ToList();
-    }
-}
-```
-
-**`CachingAgentSkillsSource`** — A decorator that caches skills after the first load, keeping the provider stateless and giving consumers control over caching granularity per source. For example, file-based skills (expensive to discover) can be cached while code-defined skills remain uncached:
-
-```csharp
-public sealed class CachingAgentSkillsSource : DelegatingAgentSkillsSource
-{
-    private IList<AgentSkill>? _cached;
-
-    public CachingAgentSkillsSource(AgentSkillsSource innerSource)
-        : base(innerSource)
-    {
-    }
-
-    public override async Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)
-    {
-        return _cached ??= await this.InnerSource.GetSkillsAsync(cancellationToken);
-    }
-}
-```
-
-**Deduplication** is similarly implemented as a decorator (`DeduplicatingAgentSkillsSource`) that deduplicates by name (case-insensitive, first-one-wins) and logs a warning for skipped duplicates.
-
-**Example** — Combining file-based and code-defined sources with filtering and caching:
-
-```csharp
-var fileSource = new CachingAgentSkillsSource(new AgentFileSkillsSource(["./skills"]));
-var codeSource = new AgentInMemorySkillsSource([myCodeSkill]);
-
-var compositeSource = new FilteringAgentSkillsSource(
-    new AggregatingAgentSkillsSource([fileSource, codeSource]),
-    filter: s => s.Frontmatter.Name != "internal");
-
-var provider = new AgentSkillsProvider(compositeSource);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-**Pros:**
-- Clean single-responsibility: the provider serves skills, sources provide them.
-- Caching, filtering, and deduplication are composable as source decorators — each concern is a separate, testable wrapper.
-
-**Cons:**
-- DI is less flexible: multiple `AgentSkillsSource` implementations registered in the container cannot be auto-injected into the provider. The consumer must manually compose them via an aggregate source.
-- Increased public API surface: requires additional public classes (aggregate source, caching decorators, filtering decorators) that consumers need to learn and use.
-
-### Via AgentSkillsProvider
-
-In this approach, the `AgentSkillsProvider` accepts **`IEnumerable<AgentSkillsSource>`** and handles aggregation, filtering, caching, and deduplication internally.
-
-The provider aggregates skills from all registered sources, deduplicates by name (case-insensitive, first-one-wins), caches the result after the first load, and optionally applies filtering via a predicate on `AgentSkillsProviderOptions`. Duplicate skill names are logged as warnings.
-
-**Example** — Registering multiple sources directly with the provider:
-
-```csharp
-// Conceptual example — in practice, use AgentSkillsProviderBuilder
-var fileSource = new AgentFileSkillsSource(["./skills"]);
-var codeSource = new AgentInMemorySkillsSource([myCodeSkill]);
-
-var provider = new AgentSkillsProvider(
-    sources: [fileSource, codeSource],
-    options: new AgentSkillsProviderOptions
-    {
-        Filter = s => s.Frontmatter.Name != "internal",
-    });
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-**Pros:**
-- DI-friendly: register multiple `AgentSkillsSource` implementations in the container, and they are all auto-injected into `AgentSkillsProvider` via `IEnumerable<AgentSkillsSource>`.
-- Smaller public API surface: no need for aggregate source, caching decorators, or filtering decorator classes — these concerns are handled internally by the provider.
-
-**Cons:**
-- The provider takes on multiple responsibilities — aggregation, caching, deduplication, and filtering.
-- Less granular caching control: caching is all-or-nothing across sources rather than per-source as with decorators.
-- Less extensible: new behaviors (e.g., ordering, TTL expiration) require modifying the provider rather than adding a decorator.
-
-### Builder Pattern
-
-**`AgentSkillsProviderBuilder`** provides a fluent API for composing skills from multiple sources. The builder centralizes configuration — script executors, approval callbacks, prompt templates, and filtering — so consumers don't need to know the underlying source types.
-
-The builder internally decides how to wire up the object graph: it creates the appropriate source instances, applies caching and filtering, and returns a fully configured `AgentSkillsProvider`. This keeps the setup code concise while still allowing fine-grained control when needed.
-
-**Example** — Using the builder to combine multiple source types with configuration:
-
-```csharp
-var provider = new AgentSkillsProviderBuilder()
-    .UseFileSkill("./skills")                           // file-based source
-    .UseInlineSkills(codeSkill)                            // code-defined source
-    .UseClassSkills(new ClassSkill())                    // class-based source
-    .UseFileScriptRunner(SubprocessScriptRunner.RunAsync) // script runner
-    .UseScriptApproval()                                // optional human-in-the-loop
-    .UsePromptTemplate(customTemplate)                  // optional prompt customization
-    .UseFilter(s => s.Frontmatter.Name != "internal")   // optional skill filtering
-    .Build();
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-## Adding a Custom Skill Type
-
-The skills framework is designed for extensibility. While file-based and inline skills cover common
-scenarios, you can introduce entirely new skill types by subclassing the four base classes:
-
-| Base class            | Purpose                                             |
-|-----------------------|-----------------------------------------------------|
-| `AgentSkillsSource`   | Discovers and loads skills from a particular origin  |
-| `AgentSkill`          | Holds metadata, content, resources, and scripts      |
-| `AgentSkillResource`  | Provides supplementary content to a skill            |
-| `AgentSkillScript`    | Represents an executable action within a skill       |
-
-The example below implements a **cloud-based skill type** where skills, resources, and scripts are
-all stored in and executed through a remote cloud service (e.g., Azure Blob Storage + Azure Functions).
-
-### Step 1 — Define a custom resource
-
-A `CloudSkillResource` reads resource content from a cloud storage endpoint instead of the local
-filesystem:
-
-```csharp
-/// <summary>
-/// A skill resource backed by a cloud storage endpoint.
-/// </summary>
-public sealed class CloudSkillResource : AgentSkillResource
-{
-    private readonly HttpClient _httpClient;
-
-    public CloudSkillResource(string name, Uri blobUri, HttpClient httpClient, string? description = null)
-        : base(name, description)
-    {
-        BlobUri = blobUri ?? throw new ArgumentNullException(nameof(blobUri));
-        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
-    }
-
-    /// <summary>
-    /// Gets the URI of the cloud blob that holds this resource's content.
-    /// </summary>
-    public Uri BlobUri { get; }
-
-    /// <inheritdoc/>
-    public override async Task<object?> ReadAsync(
-        IServiceProvider? serviceProvider = null,
-        CancellationToken cancellationToken = default)
-    {
-        return await _httpClient.GetStringAsync(BlobUri, cancellationToken).ConfigureAwait(false);
-    }
-}
-```
-
-### Step 2 — Define a custom script
-
-A `CloudSkillScript` executes a script by calling a cloud function endpoint, passing arguments as
-the request body:
-
-```csharp
-/// <summary>
-/// A skill script executed via a cloud function endpoint.
-/// </summary>
-public sealed class CloudSkillScript : AgentSkillScript
-{
-    private readonly HttpClient _httpClient;
-
-    public CloudSkillScript(string name, Uri functionUri, HttpClient httpClient, string? description = null)
-        : base(name, description)
-    {
-        FunctionUri = functionUri ?? throw new ArgumentNullException(nameof(functionUri));
-        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
-    }
-
-    /// <summary>
-    /// Gets the URI of the cloud function that runs this script.
-    /// </summary>
-    public Uri FunctionUri { get; }
-
-    /// <inheritdoc/>
-    public override async Task<object?> RunAsync(
-        AgentSkill skill,
-        AIFunctionArguments arguments,
-        CancellationToken cancellationToken = default)
-    {
-        var json = JsonSerializer.Serialize(arguments);
-        using var content = new StringContent(json, Encoding.UTF8, "application/json");
-        var response = await _httpClient.PostAsync(FunctionUri, content, cancellationToken)
-            .ConfigureAwait(false);
-        response.EnsureSuccessStatusCode();
-        return await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
-    }
-}
-```
-
-### Step 3 — Define a custom skill
-
-A `CloudSkill` bundles cloud-specific metadata (e.g., the base endpoint) with the standard skill
-shape:
-
-```csharp
-/// <summary>
-/// An <see cref="AgentSkill"/> whose content, resources, and scripts are stored in a cloud service.
-/// </summary>
-public sealed class CloudSkill : AgentSkill
-{
-    public CloudSkill(
-        AgentSkillFrontmatter frontmatter,
-        string content,
-        Uri endpoint,
-        IReadOnlyList<AgentSkillResource>? resources = null,
-        IReadOnlyList<AgentSkillScript>? scripts = null)
-    {
-        Frontmatter = frontmatter ?? throw new ArgumentNullException(nameof(frontmatter));
-        Content = content ?? throw new ArgumentNullException(nameof(content));
-        Endpoint = endpoint ?? throw new ArgumentNullException(nameof(endpoint));
-        Resources = resources;
-        Scripts = scripts;
-    }
-
-    /// <inheritdoc/>
-    public override AgentSkillFrontmatter Frontmatter { get; }
-
-    /// <inheritdoc/>
-    public override string Content { get; }
-
-    /// <summary>
-    /// Gets the base cloud endpoint for this skill.
-    /// </summary>
-    public Uri Endpoint { get; }
-
-    /// <inheritdoc/>
-    public override IReadOnlyList<AgentSkillResource>? Resources { get; }
-
-    /// <inheritdoc/>
-    public override IReadOnlyList<AgentSkillScript>? Scripts { get; }
-}
-```
-
-### Step 4 — Define a custom source
-
-A `CloudSkillsSource` discovers skills from a cloud catalog API and constructs `CloudSkill`
-instances with their associated resources and scripts:
-
-```csharp
-/// <summary>
-/// A skill source that discovers and loads skills from a cloud catalog API.
-/// </summary>
-public sealed class CloudSkillsSource : AgentSkillsSource
-{
-    private readonly Uri _catalogUri;
-    private readonly HttpClient _httpClient;
-
-    public CloudSkillsSource(Uri catalogUri, HttpClient httpClient)
-    {
-        _catalogUri = catalogUri ?? throw new ArgumentNullException(nameof(catalogUri));
-        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
-    }
-
-    /// <inheritdoc/>
-    public override async Task<IList<AgentSkill>> GetSkillsAsync(
-        CancellationToken cancellationToken = default)
-    {
-        // Fetch the skill catalog from the cloud service.
-        var json = await _httpClient.GetStringAsync(_catalogUri, cancellationToken)
-            .ConfigureAwait(false);
-        var catalog = JsonSerializer.Deserialize<CloudSkillCatalog>(json)!;
-
-        var skills = new List<AgentSkill>();
-
-        foreach (var entry in catalog.Skills)
-        {
-            var frontmatter = new AgentSkillFrontmatter(entry.Name, entry.Description);
-
-            // Build cloud-backed resources.
-            var resources = entry.Resources
-                .Select(r => new CloudSkillResource(r.Name, r.BlobUri, _httpClient, r.Description))
-                .ToList<AgentSkillResource>();
-
-            // Build cloud-backed scripts.
-            var scripts = entry.Scripts
-                .Select(s => new CloudSkillScript(s.Name, s.FunctionUri, _httpClient, s.Description))
-                .ToList<AgentSkillScript>();
-
-            skills.Add(new CloudSkill(frontmatter, entry.Content, entry.Endpoint, resources, scripts));
-        }
-
-        return skills;
-    }
-}
-```
-
-### Step 5 — Register with the builder
-
-Use `UseSource` to wire the custom source into the provider:
-
-```csharp
-var httpClient = new HttpClient();
-
-var provider = new AgentSkillsProviderBuilder()
-    .UseSource(new CloudSkillsSource(
-        new Uri("https://my-service.example.com/skills/catalog"),
-        httpClient))
-    // Mix with other source types if needed:
-    .UseFileSkill("/local/skills", scriptRunner)
-    .UseInlineSkills(someInlineSkill)
-    .Build();
-```
-
-The `AgentSkillsProvider` handles all skill types uniformly — any combination of file-based, inline,
-class-based, and custom skills can coexist in the same provider. Custom skills automatically
-participate in the model-facing tools (`load_skill`, `read_skill_resource`, `run_skill_script`),
-filtering, deduplication, and caching — no additional integration work is required.
-
-## Script Representation: `AgentSkillScript` vs `AIFunction`
-
-Two approaches were considered for representing executable scripts within skills:
-
-### Option A — Custom `AgentSkillScript` abstract base class (original design)
-
-Scripts are modeled as a custom `AgentSkillScript` abstract class with `Name`, `Description`, and
-`RunAsync(AgentSkill, AIFunctionArguments, CancellationToken)`. Concrete implementations:
-`AgentInlineSkillScript` (wraps a delegate/`AIFunction`) and `AgentFileSkillScript` (wraps a file path + executor delegate).
-
-```csharp
-// Base type
-public abstract class AgentSkillScript
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default);
-}
-
-// AgentSkill exposes scripts as:
-public abstract IReadOnlyList<AgentSkillScript>? Scripts { get; }
-
-// Inline script wraps an AIFunction internally
-var script = new AgentInlineSkillScript(ConvertUnits, "convert");
-
-// Pre-built AIFunction must be wrapped
-var script = new AgentInlineSkillScript(myAIFunction);
-
-// Class-based skill declares scripts as:
-public override IReadOnlyList<AgentSkillScript>? Scripts { get; } =
-[
-    new AgentInlineSkillScript(ConvertUnits, "convert"),
-];
-
-// Provider executes scripts by passing the owning skill:
-await script.RunAsync(skill, arguments, cancellationToken);
-```
-
-**Pros:**
-
-- **Explicit skill context at execution time.** `RunAsync` receives the owning `AgentSkill`, so any script can access skill metadata or resources during execution without requiring construction-time wiring.
-- **Self-contained abstraction.** A dedicated type communicates clearly that scripts are a skills-framework concept, separate from general-purpose AI functions.
-- **Easier extensibility for custom script types.** Third-party implementations can subclass `AgentSkillScript` and access the owning skill in `RunAsync` without special setup.
-
-**Cons:**
-
-- **Wrapper overhead.** `AgentInlineSkillScript` is a thin pass-through around `AIFunction` — it adds a class, a constructor, and an indirection layer for no behavioral difference.
-- **Parallel abstraction.** `AgentSkillScript` and `AIFunction` serve overlapping purposes (named callable with arguments), creating two parallel hierarchies for the same concept.
-- **Friction for consumers.** Users who already have `AIFunction` instances must wrap them in `AgentInlineSkillScript` to use them as scripts, adding ceremony.
-
-### Option B — Reuse `AIFunction` directly
-
-Scripts are represented as `AIFunction` (from `Microsoft.Extensions.AI`). `AgentSkill.Scripts` returns
-`IReadOnlyList<AIFunction>?`. `AgentInlineSkillScript` is eliminated entirely — callers use
-`AIFunctionFactory.Create(delegate, name: ...)` or pass `AIFunction` instances directly.
-`AgentFileSkillScript` becomes an `AIFunction` subclass that captures its owning `AgentFileSkill` via
-an internal back-reference set during construction.
-
-```csharp
-// AgentSkill exposes scripts as AIFunction directly:
-public abstract IReadOnlyList<AIFunction>? Scripts { get; }
-
-// Inline scripts use AIFunctionFactory — no wrapper class needed
-var skill = new AgentInlineSkill("my-skill", "desc", "instructions");
-skill.AddScript(ConvertUnits, "convert");           // delegate
-skill.AddScript(myAIFunction);                       // pre-built AIFunction — no wrapping
-
-// Class-based skill declares scripts as:
-public override IReadOnlyList<AIFunction>? Scripts { get; } =
-[
-    AIFunctionFactory.Create(ConvertUnits, name: "convert"),
-];
-
-// Provider executes scripts via standard AIFunction invocation:
-await script.InvokeAsync(arguments, cancellationToken);
-
-// File-based scripts extend AIFunction and capture the owning skill internally:
-public sealed class AgentFileSkillScript : AIFunction
-{
-    internal AgentFileSkill? Skill { get; set; }   // set by AgentFileSkill constructor
-
-    protected override async ValueTask<object?> InvokeCoreAsync(
-        AIFunctionArguments arguments, CancellationToken cancellationToken)
-    {
-        return await _executor(Skill!, this, arguments, cancellationToken);
-    }
-}
-```
-
-**Pros:**
-
-- **Fewer types.** Eliminates `AgentSkillScript` and `AgentInlineSkillScript`, reducing the public API surface by two classes.
-- **Seamless interop.** Any `AIFunction` — whether from `AIFunctionFactory`, a custom subclass, or an external library — can be used as a skill script with zero wrapping.
-- **Consistent with `Microsoft.Extensions.AI` ecosystem.** Scripts share the same type as tool functions used by `IChatClient` and `FunctionInvokingChatClient`, reducing conceptual overhead for developers already familiar with the ecosystem.
-
-**Cons:**
-
-- **No owning-skill context in invocation signature.** `AIFunction.InvokeAsync` does not accept an `AgentSkill` parameter, so `AgentFileSkillScript` must capture its owning skill via an internal setter during construction. This adds a construction-order dependency: the skill must set the back-reference on its scripts.
-- **Custom script types lose automatic skill access.** Third-party `AIFunction` subclasses that need the owning skill must implement their own mechanism (e.g., constructor injection, closure capture) instead of receiving it as a method parameter.
-- **Semantic overloading.** `AIFunction` now means both "a tool the model can call" and "a script within a skill", which could blur the distinction for framework users.
-
-## Resource Representation: `AgentSkillResource` vs `AIFunction`
-
-Two approaches were considered for representing skill resources (supplementary content such as references, assets, or dynamic data):
-
-### Option A — Custom `AgentSkillResource` abstract base class (original design)
-
-Resources are modeled as a custom `AgentSkillResource` abstract class with `Name`, `Description`, and
-`ReadAsync(IServiceProvider?, CancellationToken)`. Concrete implementations:
-`AgentInlineSkillResource` (static value, delegate, or `AIFunction` wrapper) and `AgentFileSkillResource` (reads file content from disk).
-
-```csharp
-// Base type
-public abstract class AgentSkillResource
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default);
-}
-
-// AgentSkill exposes resources as:
-public abstract IReadOnlyList<AgentSkillResource>? Resources { get; }
-
-// Static resource
-var resource = new AgentInlineSkillResource("static content", "my-resource");
-
-// Dynamic resource (delegate)
-var resource = new AgentInlineSkillResource((IServiceProvider sp) => GetData(sp), "my-resource");
-
-// Pre-built AIFunction must be wrapped
-var resource = new AgentInlineSkillResource(myAIFunction);
-
-// Class-based skill declares resources as:
-public override IReadOnlyList<AgentSkillResource>? Resources { get; } =
-[
-    new AgentInlineSkillResource("# Conversion Tables\n...", "conversion-table"),
-];
-
-// Provider reads resources via:
-await resource.ReadAsync(serviceProvider, cancellationToken);
-```
-
-**Pros:**
-
-- **Clear semantic distinction.** A dedicated `AgentSkillResource` type distinguishes resources (data providers) from scripts (executable actions), making the API self-documenting.
-- **Purpose-built API.** `ReadAsync` communicates intent better than `InvokeAsync` for a data-access operation.
-
-**Cons:**
-
-- **Wrapper overhead.** `AgentInlineSkillResource` wraps `AIFunction` internally for delegate/function cases — adding a class and indirection for no behavioral difference.
-- **Parallel abstraction.** `AgentSkillResource` and `AIFunction` serve overlapping purposes (named callable that returns data), creating two parallel hierarchies.
-- **Friction for consumers.** Users who already have `AIFunction` instances must wrap them in `AgentInlineSkillResource`, adding ceremony.
-
-### Option B — Reuse `AIFunction` directly
-
-Resources are represented as `AIFunction`. `AgentSkill.Resources` returns `IReadOnlyList<AIFunction>?`.
-`AgentInlineSkillResource` becomes an `AIFunction` subclass (retained as a convenience for the static-value
-pattern: `new AgentInlineSkillResource("data", "name")`). `AgentFileSkillResource` becomes an `AIFunction`
-subclass that reads file content.
-
-```csharp
-// AgentSkill exposes resources as AIFunction directly:
-public abstract IReadOnlyList<AIFunction>? Resources { get; }
-
-// Static resource — AgentInlineSkillResource is retained as a convenience AIFunction subclass
-var resource = new AgentInlineSkillResource("static content", "my-resource");
-
-// Dynamic resource — AgentInlineSkillResource wraps delegate as AIFunction
-var resource = new AgentInlineSkillResource((IServiceProvider sp) => GetData(sp), "my-resource");
-
-// Pre-built AIFunction can be used directly — no wrapping needed
-skill.AddResource(myAIFunction);
-
-// Class-based skill declares resources as:
-public override IReadOnlyList<AIFunction>? Resources { get; } =
-[
-    new AgentInlineSkillResource("# Conversion Tables\n...", "conversion-table"),
-];
-
-// Provider reads resources via standard AIFunction invocation:
-await resource.InvokeAsync(arguments, cancellationToken);
-
-// File-based resources extend AIFunction directly:
-internal sealed class AgentFileSkillResource : AIFunction
-{
-    public string FullPath { get; }
-
-    protected override async ValueTask<object?> InvokeCoreAsync(
-        AIFunctionArguments arguments, CancellationToken cancellationToken)
-    {
-        return await File.ReadAllTextAsync(FullPath, Encoding.UTF8, cancellationToken);
-    }
-}
-```
-
-**Pros:**
-
-- **Fewer base types.** Eliminates the `AgentSkillResource` abstract class, reducing the public API surface.
-- **Seamless interop.** Any `AIFunction` can be used as a skill resource with zero wrapping.
-
-**Cons:**
-
-- **Loss of semantic distinction.** Resources and scripts are now both `AIFunction`, which could make it less obvious which list a function belongs to when reading code.
-- **Static values require a wrapper.** Unlike the original `ReadAsync` which could return a stored value directly, `AIFunction.InvokeAsync` implies invocation. `AgentInlineSkillResource` is retained as a convenience subclass to handle the static-value case, so this is not eliminated — just moved to a different class.
-
-## Decision Outcome
-
-### 1. Keep `AgentSkillResource` and `AgentSkillScript` (Option A for both sections)
-
-We are staying with the custom `AgentSkillResource` and `AgentSkillScript` model classes instead of reusing `AIFunction`:
-
-- **Resources have no parameters.** If a consumer provides an `AIFunction` with parameters, those parameters will never be advertised to the LLM, and the resulting call will fail.
-- **Approval breaks for `AIFunction`-based representations.** When a resource or script represented by an `AIFunction` is configured with approval, the second approval invocation will not work correctly.
-- **Injecting the owning skill into an `AIFunction`-based script is problematic.** Constructor injection would introduce a circular reference between the skill and the script. An internal property setter is possible but adds coupling.
-
-### 2. Make all agent skill classes internal
-
-All agent-skill-related classes are made `internal` to minimize the public API surface while the feature matures. We can reconsider and promote types to `public` later based on community signal.
-
-This leaves two public entry points:
-
-- **`AgentSkillsProvider`** — use directly when all skills come from a single source and filtering is not needed.
-- **`AgentSkillsProviderBuilder`** — use when mixing skill types or when filtering support is required.
-
-### 3. Caching at provider level
-
-Caching of tools and instructions is implemented inside `AgentSkillsProvider` rather than as an external decorator. Recreating tools and instructions on every provider call is wasteful, and a caching decorator sitting outside the provider would not have the information needed to cache them effectively.

docs/decisions/0021-provider-leading-clients.md

@@ -1,72 +0,0 @@
----
-status: accepted
-contact: eavanvalkenburg
-date: 2026-03-20
-deciders: eavanvalkenburg, sphenry, chetantoshnival
-consulted: taochenosu, moonbox3, dmytrostruk, giles17, alliscode
----
-
-# Provider-Leading Client Design & OpenAI Package Extraction
-
-## Context and Problem Statement
-
-The `agent-framework-core` package currently bundles OpenAI and Azure OpenAI client implementations along with their dependencies (`openai`, `azure-identity`, `azure-ai-projects`, `packaging`). This makes core heavier than necessary for users who don't use OpenAI, and it conflates the core abstractions with a specific provider implementation. Additionally, the current class naming (`OpenAIResponsesClient`, `OpenAIChatClient`) is based on the underlying OpenAI API names rather than what users actually want to do, making discoverability harder for newcomers.
-
-## Decision Drivers
-
-- **Lightweight core**: Core should only contain abstractions, middleware infrastructure, and telemetry — no provider-specific code or dependencies.
-- **Discoverability-first**: Import namespaces should guide users to the right client. `from agent_framework.openai import ...` should surface all OpenAI-related clients; `from agent_framework.azure import ...` should surface Foundry, Azure AI, and other Azure-specific classes.
-- **Provider-leading naming**: The primary client name should reflect the provider, not the underlying API. The Responses API is now the recommended default for OpenAI, so its client should be called `OpenAIChatClient` (not `OpenAIResponsesClient`).
-- **Clean separation of concerns**: Azure-specific deprecated wrappers belong in the azure-ai package, not in the OpenAI package.
-
-## Considered Options
-
-- **Keep OpenAI in core**: Simpler but keeps core heavy; doesn't help discoverability.
-- **Extract OpenAI with Azure wrappers in the OpenAI package**: Keeps Azure OpenAI wrappers alongside OpenAI code, but pollutes the OpenAI package with Azure concerns.
-- **Extract OpenAI, place Azure wrappers in azure-ai**: Clean separation; the OpenAI package has zero Azure dependencies; deprecated Azure wrappers live in a single file in azure-ai for easy future deletion.
-
-## Decision Outcome
-
-Chosen option: "Extract OpenAI, place Azure wrappers in azure-ai", because it achieves the lightest core, cleanest OpenAI package, and the most maintainable deprecation path.
-
-Key changes:
-
-1. **New `agent-framework-openai` package** with dependencies on `agent-framework-core`, `openai`, and `packaging` only.
-2. **Class renames**: `OpenAIResponsesClient` → `OpenAIChatClient` (Responses API), `OpenAIChatClient` → `OpenAIChatCompletionClient` (Chat Completions API). Old names remain as deprecated aliases.
-3. **Deprecated classes**: `OpenAIAssistantsClient`, all `AzureOpenAI*Client` classes, `AzureAIClient`, `AzureAIAgentClient`, and `AzureAIProjectAgentProvider` are marked deprecated.
-4. **New `FoundryChatClient`** in azure-ai for Azure AI Foundry Responses API access, built on `RawFoundryChatClient(RawOpenAIChatClient)`.
-5. **All deprecated `AzureOpenAI*` classes** consolidated into a single file (`_deprecated_azure_openai.py`) in the azure-ai package for clean future deletion.
-6. **Core's `agent_framework.openai` and `agent_framework.azure` namespaces** become lazy-loading gateways, preserving backward-compatible import paths while removing hard dependencies.
-7. **Unified `model` parameter** replaces `model_id` (OpenAI), `deployment_name` (Azure OpenAI), and `model_deployment_name` (Azure AI) across all client constructors. The term `model` is intentionally generic: it naturally maps to an OpenAI model name *and* to an Azure OpenAI deployment name, making it straightforward to use `OpenAIChatClient` with either OpenAI or Azure OpenAI backends (via `AsyncAzureOpenAI`). Environment variables are similarly unified (e.g., `OPENAI_MODEL` instead of separate `OPENAI_RESPONSES_MODEL_ID` / `OPENAI_CHAT_MODEL_ID`).
-8. **`FoundryAgent`** replaces the pattern of `Agent(client=AzureAIClient(...))` for connecting to pre-configured agents in Azure AI Foundry (PromptAgents and HostedAgents). The underlying `RawFoundryAgentChatClient` is an implementation detail — most users interact only with `FoundryAgent`. `AzureAIAgentClient` is separately deprecated as it refers to the V1 Agents Service API. See below for design rationale.
-
-### Foundry Agent Design: `FoundryAgentClient` vs `FoundryAgent`
-
-The existing `AzureAIClient` combines two concerns: CRUD lifecycle management (creating/deleting agents on the service) and runtime communication (sending messages via the Responses API). The new design removes CRUD entirely — users connect to agents that already exist in Foundry.
-
-**Two approaches were considered:**
-
-**Option A — `FoundryAgentClient` only (public ChatClient):**
-Users compose `Agent(client=FoundryAgentClient(...), tools=[...])`. This follows the universal `Agent(client=X)` pattern used by every other provider. However, a "client" that wraps a named remote agent (with `agent_name` as a constructor param) is semantically odd — clients typically wrap a model endpoint, not a specific agent.
-
-**Option B — `FoundryAgent` (Agent subclass) + private `_FoundryAgentChatClient` and public `RawFoundryAgentChatClient`:**
-Users write `FoundryAgent(agent_name="my-agent", ...)` for the common case. Internally, `FoundryAgent` creates a `_FoundryAgentChatClient` and passes it to the standard `Agent` base class. For advanced customization, users pass `client_type=RawFoundryAgentChatClient` (or a custom subclass) to control the client middleware layers. The `Agent(client=RawFoundryAgentChatClient(...))` composition pattern still works for users who prefer it.
-
-**Chosen option: Option B**, because:
-- The common case (`FoundryAgent(...)`) is a single object with no boilerplate.
-- `client_type=` gives full control over client middleware without parameter duplication — the agent forwards connection params to the client internally.
-- `RawFoundryAgent(RawAgent)` and `FoundryAgent(Agent)` mirror the established `RawAgent`/`Agent` pattern.
-- Runtime validation (only `FunctionTool` allowed) lives in `RawFoundryAgentChatClient._prepare_options`, ensuring it applies regardless of how the client is used — through `FoundryAgent`, `Agent(client=...)`, or any custom composition.
-
-**Public classes:**
-- `RawFoundryAgentChatClient(RawOpenAIChatClient)` — Responses API client that injects agent reference and validates tools. Extension point for custom client middleware.
-- `RawFoundryAgent(RawAgent)` — Agent without agent-level middleware/telemetry.
-- `FoundryAgent(AgentTelemetryLayer, AgentMiddlewareLayer, RawFoundryAgent)` — Recommended production agent.
-
-**Internal (private):**
-- `_FoundryAgentChatClient` — Full client with function invocation, chat middleware, and telemetry layers. Created automatically by `FoundryAgent`; users customize via `client_type=RawFoundryAgentChatClient` or a custom subclass.
-
-**Deprecated:**
-- `AzureAIClient` — replaced by `FoundryAgent` (which uses `FoundryAgentClient` internally).
-- `AzureAIAgentClient` — refers to V1 Agents Service API, no direct replacement.
-- `AzureAIProjectAgentProvider` — replaced by `FoundryAgent`.

docs/decisions/0022-chat-history-persistence-consistency.md

@@ -1,116 +0,0 @@
----
-status: accepted
-contact: westey-m
-date: 2026-03-23
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
-consulted:
-informed:
----
-
-# Chat History Persistence Consistency
-
-## Context and Problem Statement
-
-When using `ChatClientAgent` with tools, the `FunctionInvokingChatClient` (FIC) loops multiple times — service call → tool execution → service call → … — before producing a final response. There are two points of discrepancy between how chat history is stored by the framework's `ChatHistoryProvider` and how the underlying AI service stores chat history (e.g., OpenAI Responses with `store=true`):
-
-1. **Persistence timing**: The AI service persists messages after *each* service call within the FIC loop. The `ChatHistoryProvider` currently persists messages only once, at the *end* of the full agent run (after all FIC loop iterations complete).
-
-2. **Trailing `FunctionResultContent` storage**: When tool calling is terminated mid-loop (e.g., via `FunctionInvokingChatClient` termination filters), the final response from the agent may contain `FunctionResultContent` that was never sent to a subsequent service call. The AI service never stores this trailing `FunctionResultContent`, but the `ChatHistoryProvider` currently stores all response content, including the trailing `FunctionResultContent`.
-
-These discrepancies mean that a `ChatHistoryProvider`-managed conversation and a service-managed conversation can diverge in content and structure, even when processing the same interactions.
-
-### Practical Impact: Resuming After Tool-Call Termination
-
-Today, users of `AIAgent` get different behaviors depending on whether chat history is stored service-side or in a `ChatHistoryProvider`. This creates concrete challenges — for example, when the function call loop is terminated and the user wants to resume the conversation in a subsequent run. With service-stored history, the trailing `FunctionResultContent` is never persisted, so the last stored message is the `FunctionCallContent` from the service. With `ChatHistoryProvider`-stored history, the trailing `FunctionResultContent` *is* persisted. The user cannot know whether the last `FunctionResultContent` is in the chat history or not without inspecting the storage mechanism, making it difficult to write resumption logic that works correctly regardless of the storage backend.
-
-### Relationship Between the Two Discrepancies
-
-The persistence timing and `FunctionResultContent` trimming behaviors are interrelated:
-
-- **Per-service-call persistence**: When messages are persisted after each individual service call, trailing `FunctionResultContent` trimming is unnecessary. If tool calling is terminated, the `FunctionResultContent` from the terminated call was never sent to a subsequent service call, so it is never persisted. The per-service-call approach naturally matches the service's behavior.
-
-- **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.
-- **B. Atomicity**: A run that fails mid-way through a multi-step tool-calling loop should not leave chat history in a partially-updated state, unless the user explicitly opts into that behavior.
-- **C. Recoverability**: For long-running tool-calling loops, it should be possible to recover intermediate progress if the process is interrupted, rather than losing all work from the current run.
-- **D. Simplicity**: The default behavior should be easy to understand and predict for most users, without requiring knowledge of the FIC loop internals.
-- **E. Flexibility**: Regardless of the chosen default, users should be able to opt into the alternative behavior.
-
-## 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)
-
-## Pros and Cons of the Options
-
-### Option 1: Default to per-run persistence with `FunctionResultContent` 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`
-
-- 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.
-
-### Option 2: Default to per-service-call persistence
-
-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.
-
-Settings:
-- `PersistChatHistoryAtEndOfRun` = `false` (default)
-
-- Good, because the stored history matches the service's behavior by default 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`.
-- Bad, because the mental model is more complex: a single run may produce multiple history updates, partially failing driver D.
-- Neutral, because users can opt out to per-run persistence if they prefer atomicity, satisfying driver E.
-
-## 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.
-
-### Configuration Matrix
-
-The behavior depends on the combination of `UseProvidedChatClientAsIs` and `PersistChatHistoryAtEndOfRun`:
-
-| `UseProvidedChatClientAsIs` | `PersistChatHistoryAtEndOfRun` | 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. |
-
-### 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`.
-- 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.
-
-## More Information
-
-- [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

dotnet/agent-framework-dotnet.slnx

@@ -57,7 +57,6 @@
     <Project Path="samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -77,8 +76,6 @@
     <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
     <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
     <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/03_WorkflowHITL/03_WorkflowHITL.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/04_WorkflowMcpTool.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/05_WorkflowAndAgents.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/">
     <File Path="samples/GettingStarted/README.md" />
@@ -104,7 +101,7 @@
   </Folder>
   <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_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
     <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />

dotnet/samples/02-agents/AgentOpenTelemetry/Program.cs

@@ -18,7 +18,6 @@ using OpenTelemetry.Trace;
 
 #region Setup Telemetry
 
-// Source name for this sample's custom ActivitySource and Meter; other instrumentation uses their own sources/categories.
 const string SourceName = "OpenTelemetryAspire.ConsoleApp";
 const string ServiceName = "AgentOpenTelemetry";
 
@@ -41,6 +40,7 @@ var resource = ResourceBuilder.CreateDefault()
 var tracerProviderBuilder = Sdk.CreateTracerProviderBuilder()
     .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(ServiceName, serviceVersion: "1.0.0"))
     .AddSource(SourceName) // Our custom activity source
+    .AddSource("*Microsoft.Agents.AI") // Agent Framework telemetry
     .AddHttpClientInstrumentation() // Capture HTTP calls to OpenAI
     .AddOtlpExporter(options => options.Endpoint = new Uri(otlpEndpoint));
 
@@ -54,7 +54,8 @@ using var tracerProvider = tracerProviderBuilder.Build();
 // Setup metrics with resource and instrument name filtering
 using var meterProvider = Sdk.CreateMeterProviderBuilder()
     .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(ServiceName, serviceVersion: "1.0.0"))
-    .AddMeter(SourceName) // Our custom meter source
+    .AddMeter(SourceName) // Our custom meter
+    .AddMeter("*Microsoft.Agents.AI") // Agent Framework metrics
     .AddHttpClientInstrumentation() // HTTP client metrics
     .AddRuntimeInstrumentation() // .NET runtime metrics
     .AddOtlpExporter(options => options.Endpoint = new Uri(otlpEndpoint))
@@ -127,7 +128,7 @@ var agent = new ChatClientAgent(instrumentedChatClient,
     instructions: "You are a helpful assistant that provides concise and informative responses.",
     tools: [AIFunctionFactory.Create(GetWeatherAsync)])
     .AsBuilder()
-    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // enable telemetry at the agent level
+    .UseOpenTelemetry(SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // enable telemetry at the agent level
     .Build();
 
 var session = await agent.CreateSessionAsync();

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj

@@ -14,10 +14,6 @@
     <PackageReference Include="Azure.Identity" />
   </ItemGroup>
 
-  <ItemGroup>
-    <Compile Include="..\SubprocessScriptRunner.cs" Link="SubprocessScriptRunner.cs" />
-  </ItemGroup>
-
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Agent Skills with a ChatClientAgent.
+// Agent Skills are modular packages of instructions and resources that extend an agent's capabilities.
+// Skills follow the progressive disclosure pattern: advertise -> load -> read resources.
+//
+// This sample includes the expense-report skill:
+//   - Policy-based expense filing with references and assets
+
+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";
+
+// --- Skills Provider ---
+// Discovers skills from the 'skills' directory and makes them available to the agent
+var skillsProvider = new FileAgentSkillsProvider(skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
+
+// --- Agent Setup ---
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetResponsesClient()
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "SkillsAgent",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant.",
+        },
+        AIContextProviders = [skillsProvider],
+    },
+    model: deploymentName);
+
+// --- Example 1: Expense policy question (loads FAQ resource) ---
+Console.WriteLine("Example 1: Checking expense policy FAQ");
+Console.WriteLine("---------------------------------------");
+AgentResponse response1 = await agent.RunAsync("Are tips reimbursable? I left a 25% tip on a taxi ride and want to know if that's covered.");
+Console.WriteLine($"Agent: {response1.Text}\n");
+
+// --- Example 2: Filing an expense report (multi-turn with template asset) ---
+Console.WriteLine("Example 2: Filing an expense report");
+Console.WriteLine("---------------------------------------");
+AgentSession session = await agent.CreateSessionAsync();
+AgentResponse response2 = await agent.RunAsync("I had 3 client dinners and a $1,200 flight last week. Return a draft expense report and ask about any missing details.",
+    session);
+Console.WriteLine($"Agent: {response2.Text}\n");

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/README.md

@@ -0,0 +1,63 @@
+# Agent Skills Sample
+
+This sample demonstrates how to use **Agent Skills** with a `ChatClientAgent` in the Microsoft Agent Framework.
+
+## What are Agent Skills?
+
+Agent Skills are modular packages of instructions and resources that enable AI agents to perform specialized tasks. They follow the [Agent Skills specification](https://agentskills.io/) and implement the progressive disclosure pattern:
+
+1. **Advertise**: Skills are advertised with name + description (~100 tokens per skill)
+2. **Load**: Full instructions are loaded on-demand via `load_skill` tool
+3. **Resources**: References and other files loaded via `read_skill_resource` tool
+
+## Skills Included
+
+### expense-report
+Policy-based expense filing with spending limits, receipt requirements, and approval workflows.
+- `references/POLICY_FAQ.md` — Detailed expense policy Q&A
+- `assets/expense-report-template.md` — Submission template
+
+## Project Structure
+
+```
+Agent_Step01_BasicSkills/
+├── Program.cs
+├── Agent_Step01_BasicSkills.csproj
+└── skills/
+    └── expense-report/
+        ├── SKILL.md
+        ├── references/
+        │   └── POLICY_FAQ.md
+        └── assets/
+            └── expense-report-template.md
+```
+
+## Running the Sample
+
+### Prerequisites
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model
+
+### Setup
+1. Set environment variables:
+   ```bash
+   export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+   export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+   ```
+
+2. Run the sample:
+   ```bash
+   dotnet run
+   ```
+
+### Examples
+
+The sample runs two examples:
+
+1. **Expense policy FAQ** — Asks about tip reimbursement; the agent loads the expense-report skill and reads the FAQ resource
+2. **Filing an expense report** — Multi-turn conversation to draft an expense report using the template asset
+
+## Learn More
+
+- [Agent Skills Specification](https://agentskills.io/)
+- [Microsoft Agent Framework Documentation](../../../../../docs/)

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: expense-report
+description: File and validate employee expense reports according to Contoso company policy. Use when asked about expense submissions, reimbursement rules, receipt requirements, spending limits, or expense categories.
+metadata:
+  author: contoso-finance
+  version: "2.1"
+---
+
+# Expense Report
+
+## Categories and Limits
+
+| Category | Limit | Receipt | Approval |
+|---|---|---|---|
+| Meals — solo | $50/day | >$25 | No |
+| Meals — team/client | $75/person | Always | Manager if >$200 total |
+| Lodging | $250/night | Always | Manager if >3 nights |
+| Ground transport | $100/day | >$15 | No |
+| Airfare | Economy | Always | Manager; VP if >$1,500 |
+| Conference/training | $2,000/event | Always | Manager + L&D |
+| Office supplies | $100 | Yes | No |
+| Software/subscriptions | $50/month | Yes | Manager if >$200/year |
+
+## Filing Process
+
+1. Collect receipts — must show vendor, date, amount, payment method.
+2. Categorize per table above.
+3. Use template: [assets/expense-report-template.md](assets/expense-report-template.md).
+4. For client/team meals: list attendee names and business purpose.
+5. Submit — auto-approved if <$500; manager if $500–$2,000; VP if >$2,000.
+6. Reimbursement: 10 business days via direct deposit.
+
+## Policy Rules
+
+- Submit within 30 days of transaction.
+- Alcohol is never reimbursable.
+- Foreign currency: convert to USD at transaction-date rate; note original currency and amount.
+- Mixed personal/business travel: only business portion reimbursable; provide comparison quotes.
+- Lost receipts (>$25): file Lost Receipt Affidavit from Finance. Max 2 per quarter.
+- For policy questions not covered above, consult the FAQ: [references/POLICY_FAQ.md](references/POLICY_FAQ.md). Answers should be based on what this document and the FAQ state.

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/assets/expense-report-template.md

@@ -0,0 +1,5 @@
+# Expense Report Template
+
+| Date | Category | Vendor | Description | Amount (USD) | Original Currency | Original Amount | Attendees | Business Purpose | Receipt Attached |
+|------|----------|--------|-------------|--------------|-------------------|-----------------|-----------|------------------|------------------|
+|      |          |        |             |              |                   |                 |           |                  | Yes or No        |

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/references/POLICY_FAQ.md

@@ -0,0 +1,55 @@
+# Expense Policy — Frequently Asked Questions
+
+## Meals
+
+**Q: Can I expense coffee or snacks during the workday?**
+A: Daily coffee/snacks under $10 are not reimbursable (considered personal). Coffee purchased during a client meeting or team working session is reimbursable as a team meal.
+
+**Q: What if a team dinner exceeds the per-person limit?**
+A: The $75/person limit applies as a guideline. Overages up to 20% are accepted with a written justification (e.g., "client dinner at venue chosen by client"). Overages beyond 20% require pre-approval from your VP.
+
+**Q: Do I need to list every attendee?**
+A: Yes. For client meals, list the client's name and company. For team meals, list all employee names. For groups over 10, you may attach a separate attendee list.
+
+## Travel
+
+**Q: Can I book a premium economy or business class flight?**
+A: Economy class is the standard. Premium economy is allowed for flights over 6 hours. Business class requires VP pre-approval and is generally reserved for flights over 10 hours or medical accommodation.
+
+**Q: What about ride-sharing (Uber/Lyft) vs. rental cars?**
+A: Use ride-sharing for trips under 30 miles round-trip. Rent a car for multi-day travel or when ride-sharing would exceed $100/day. Always choose the compact/standard category unless traveling with 3+ people.
+
+**Q: Are tips reimbursable?**
+A: Tips up to 20% are reimbursable for meals, taxi/ride-share, and hotel housekeeping. Tips above 20% require justification.
+
+## Lodging
+
+**Q: What if the $250/night limit isn't enough for the city I'm visiting?**
+A: For high-cost cities (New York, San Francisco, London, Tokyo, Sydney), the limit is automatically increased to $350/night. No additional approval is needed. For other locations where rates are unusually high (e.g., during a major conference), request a per-trip exception from your manager before booking.
+
+**Q: Can I stay with friends/family instead and get a per-diem?**
+A: No. Contoso reimburses actual lodging costs only, not per-diems.
+
+## Subscriptions and Software
+
+**Q: Can I expense a personal productivity tool?**
+A: Software must be directly related to your job function. Tools like IDE licenses, design software, or project management apps are reimbursable. General productivity apps (note-taking, personal calendar) are not, unless your manager confirms a business need in writing.
+
+**Q: What about annual subscriptions?**
+A: Annual subscriptions over $200 require manager approval before purchase. Submit the approval email with your expense report.
+
+## Receipts and Documentation
+
+**Q: My receipt is faded/damaged. What do I do?**
+A: Try to obtain a duplicate from the vendor. If not possible, submit a Lost Receipt Affidavit (available from the Finance SharePoint site). You're limited to 2 affidavits per quarter.
+
+**Q: Do I need a receipt for parking meters or tolls?**
+A: For amounts under $15, no receipt is required — just note the date, location, and amount. For $15 and above, a receipt or bank/credit card statement excerpt is required.
+
+## Approval and Reimbursement
+
+**Q: My manager is on leave. Who approves my report?**
+A: Expense reports can be approved by your skip-level manager or any manager designated as an alternate approver in the expense system.
+
+**Q: Can I submit expenses from a previous quarter?**
+A: The standard 30-day window applies. Expenses older than 30 days require a written explanation and VP approval. Expenses older than 90 days are not reimbursable except in extraordinary circumstances (extended leave, medical emergency) with CFO approval.

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Program.cs

@@ -1,48 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use file-based Agent Skills with a ChatClientAgent.
-// Skills are discovered from SKILL.md files on disk and follow the progressive disclosure pattern:
-// 1. Advertise — skill names and descriptions in the system prompt
-// 2. Load — full instructions loaded on demand via load_skill tool
-// 3. Read resources — reference files read via read_skill_resource tool
-// 4. Run scripts — scripts executed via run_skill_script tool with a subprocess executor
-//
-// This sample uses a unit-converter skill that converts between miles, kilometers, pounds, and kilograms.
-
-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";
-
-// --- Skills Provider ---
-// Discovers skills from the 'skills' directory containing SKILL.md files.
-// The script runner runs file-based scripts (e.g. Python) as local subprocesses.
-var skillsProvider = new AgentSkillsProvider(
-    Path.Combine(AppContext.BaseDirectory, "skills"),
-    SubprocessScriptRunner.RunAsync);
-// --- 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 file-based 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}");

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/README.md

@@ -1,51 +0,0 @@
-# File-Based Agent Skills Sample
-
-This sample demonstrates how to use **file-based Agent Skills** with a `ChatClientAgent`.
-
-## What it demonstrates
-
-- Discovering skills from `SKILL.md` files on disk via `AgentFileSkillsSource`
-- The progressive disclosure pattern: advertise → load → read resources → run scripts
-- Using the `AgentSkillsProvider` constructor with a skill directory path and script executor
-- Running file-based scripts (Python) via a subprocess-based executor
-
-## Skills Included
-
-### unit-converter
-
-Converts between common units (miles↔km, pounds↔kg) using a multiplication factor.
-
-- `references/conversion-table.md` — Conversion factor table
-- `scripts/convert.py` — Python script that performs the conversion
-
-## Running the Sample
-
-### Prerequisites
-
-- .NET 10.0 SDK
-- Azure OpenAI endpoint with a deployed model
-- Python 3 installed and available as `python3` on your PATH
-
-### 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 file-based skills
-------------------------------------------------------------
-Agent: Here are your conversions:
-
-1. **26.2 miles → 42.16 km** (a marathon distance)
-2. **75 kg → 165.35 lbs**
-```

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/SKILL.md

@@ -1,11 +0,0 @@
----
-name: unit-converter
-description: Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.
----
-
-## Usage
-
-When the user requests a unit conversion:
-1. First, review `references/conversion-table.md` to find the correct factor
-2. Run the `scripts/convert.py` script with `--value <number> --factor <factor>` (e.g. `--value 26.2 --factor 1.60934`)
-3. Present the converted value clearly with both units

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/references/conversion-table.md

@@ -1,10 +0,0 @@
-# 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  |

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/scripts/convert.py

@@ -1,29 +0,0 @@
-# Unit conversion script
-# Converts a value using a multiplication factor: result = value × factor
-#
-# Usage:
-#   python scripts/convert.py --value 26.2 --factor 1.60934
-#   python scripts/convert.py --value 75 --factor 2.20462
-
-import argparse
-import json
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Convert a value using a multiplication factor.",
-        epilog="Examples:\n"
-        "  python scripts/convert.py --value 26.2 --factor 1.60934\n"
-        "  python scripts/convert.py --value 75 --factor 2.20462",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument("--value", type=float, required=True, help="The numeric value to convert.")
-    parser.add_argument("--factor", type=float, required=True, help="The conversion factor from the table.")
-    args = parser.parse_args()
-
-    result = round(args.value * args.factor, 4)
-    print(json.dumps({"value": args.value, "factor": args.factor, "result": result}))
-
-
-if __name__ == "__main__":
-    main()

dotnet/samples/02-agents/AgentSkills/README.md

@@ -4,4 +4,4 @@ Samples demonstrating Agent Skills capabilities.
 
 | 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_Step01_BasicSkills](Agent_Step01_BasicSkills/) | Using Agent Skills with a ChatClientAgent, including progressive disclosure and skill resources |

dotnet/samples/02-agents/AgentSkills/SubprocessScriptRunner.cs

@@ -1,137 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// Sample subprocess-based skill script runner.
-// Executes file-based skill scripts as local subprocesses.
-// This is provided for demonstration purposes only.
-
-using System.Diagnostics;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-/// <summary>
-/// Executes file-based skill scripts as local subprocesses.
-/// </summary>
-/// <remarks>
-/// This runner uses the script's absolute path, converts the arguments
-/// to CLI flags, and returns captured output. It is intended for
-/// demonstration purposes only.
-/// </remarks>
-internal static class SubprocessScriptRunner
-{
-    /// <summary>
-    /// Runs a skill script as a local subprocess.
-    /// </summary>
-    public static async Task<object?> RunAsync(
-        AgentFileSkill skill,
-        AgentFileSkillScript script,
-        AIFunctionArguments arguments,
-        CancellationToken cancellationToken)
-    {
-        if (!File.Exists(script.FullPath))
-        {
-            return $"Error: Script file not found: {script.FullPath}";
-        }
-
-        string extension = Path.GetExtension(script.FullPath);
-        string? interpreter = extension switch
-        {
-            ".py" => "python3",
-            ".js" => "node",
-            ".sh" => "bash",
-            ".ps1" => "pwsh",
-            _ => null,
-        };
-
-        var startInfo = new ProcessStartInfo
-        {
-            RedirectStandardOutput = true,
-            RedirectStandardError = true,
-            UseShellExecute = false,
-            CreateNoWindow = true,
-            WorkingDirectory = Path.GetDirectoryName(script.FullPath) ?? ".",
-        };
-
-        if (interpreter is not null)
-        {
-            startInfo.FileName = interpreter;
-            startInfo.ArgumentList.Add(script.FullPath);
-        }
-        else
-        {
-            startInfo.FileName = script.FullPath;
-        }
-
-        if (arguments is not null)
-        {
-            foreach (var (key, value) in arguments)
-            {
-                if (value is bool boolValue)
-                {
-                    if (boolValue)
-                    {
-                        startInfo.ArgumentList.Add(NormalizeKey(key));
-                    }
-                }
-                else if (value is not null)
-                {
-                    startInfo.ArgumentList.Add(NormalizeKey(key));
-                    startInfo.ArgumentList.Add(value.ToString()!);
-                }
-            }
-        }
-
-        Process? process = null;
-        try
-        {
-            process = Process.Start(startInfo);
-            if (process is null)
-            {
-                return $"Error: Failed to start process for script '{script.Name}'.";
-            }
-
-            Task<string> outputTask = process.StandardOutput.ReadToEndAsync(cancellationToken);
-            Task<string> errorTask = process.StandardError.ReadToEndAsync(cancellationToken);
-
-            await process.WaitForExitAsync(cancellationToken).ConfigureAwait(false);
-
-            string output = await outputTask.ConfigureAwait(false);
-            string error = await errorTask.ConfigureAwait(false);
-
-            if (!string.IsNullOrEmpty(error))
-            {
-                output += $"\nStderr:\n{error}";
-            }
-
-            if (process.ExitCode != 0)
-            {
-                output += $"\nScript exited with code {process.ExitCode}";
-            }
-
-            return string.IsNullOrEmpty(output) ? "(no output)" : output.Trim();
-        }
-        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-        {
-            // Kill the process on cancellation to avoid leaving orphaned subprocesses.
-            process?.Kill(entireProcessTree: true);
-            throw;
-        }
-        catch (OperationCanceledException)
-        {
-            throw;
-        }
-        catch (Exception ex)
-        {
-            return $"Error: Failed to execute script '{script.Name}': {ex.Message}";
-        }
-        finally
-        {
-            process?.Dispose();
-        }
-    }
-
-    /// <summary>
-    /// Normalizes a parameter key to a consistent --flag format.
-    /// Models may return keys with or without leading dashes (e.g., "value" vs "--value").
-    /// </summary>
-    private static string NormalizeKey(string key) => "--" + key.TrimStart('-');
-}

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Program.cs

@@ -73,28 +73,16 @@ foreach (ClientResult result in getConversationItemsResults.GetRawPages())
     using JsonDocument getConversationItemsResultAsJson = JsonDocument.Parse(result.GetRawResponse().Content.ToString());
     foreach (JsonElement element in getConversationItemsResultAsJson.RootElement.GetProperty("data").EnumerateArray())
     {
-        // Skip non-message items (e.g. tool calls, reasoning) that lack a "role" property
-        if (!element.TryGetProperty("role"u8, out var roleElement))
-        {
-            continue;
-        }
-
         string messageId = element.GetProperty("id"u8).ToString();
-        string messageRole = roleElement.ToString();
+        string messageRole = element.GetProperty("role"u8).ToString();
         Console.WriteLine($"    Message ID: {messageId}");
         Console.WriteLine($"    Message Role: {messageRole}");
 
-        if (element.TryGetProperty("content"u8, out var contentElement))
+        foreach (var content in element.GetProperty("content").EnumerateArray())
         {
-            foreach (var content in contentElement.EnumerateArray())
-            {
-                if (content.TryGetProperty("text"u8, out var textElement))
-                {
-                    Console.WriteLine($"    Message Text: {textElement}");
-                }
-            }
+            string messageContentText = content.GetProperty("text"u8).ToString();
+            Console.WriteLine($"    Message Text: {messageContentText}");
         }
-
         Console.WriteLine();
     }
 }

dotnet/samples/02-agents/Agents/Agent_Step08_UsingImages/Agent_Step08_UsingImages.csproj

@@ -16,11 +16,5 @@
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
-
-  <ItemGroup>
-    <None Update="Assets\walkway.jpg">
-      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
   
 </Project>

dotnet/samples/02-agents/Agents/Agent_Step08_UsingImages/Program.cs

@@ -22,7 +22,7 @@ var agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential(
 
 ChatMessage message = new(ChatRole.User, [
     new TextContent("What do you see in this image?"),
-    await DataContent.LoadFromAsync("Assets/walkway.jpg"),
+    new UriContent("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", "image/jpeg")
 ]);
 
 var session = await agent.CreateSessionAsync();

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj

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

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Program.cs

@@ -1,226 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how the ChatClientAgent persists chat history after each individual
-// call to the AI service.
-// 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.
-//
-// The sample runs two multi-turn conversations: one using non-streaming (RunAsync) and one
-// using streaming (RunStreamingAsync), to demonstrate correct behavior in both modes.
-
-using System.ComponentModel;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Responses;
-
-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 store = Environment.GetEnvironmentVariable("AZURE_OPENAI_RESPONSES_STORE") ?? "false";
-
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AzureOpenAIClient openAIClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-// Define multiple tools so the model makes several tool calls in a single run.
-[Description("Get the current weather for a city.")]
-static string GetWeather([Description("The city name.")] string city) =>
-    city.ToUpperInvariant() switch
-    {
-        "SEATTLE" => "Seattle: 55°F, cloudy with light rain.",
-        "NEW YORK" => "New York: 72°F, sunny and warm.",
-        "LONDON" => "London: 48°F, overcast with fog.",
-        "DUBLIN" => "Dublin: 43°F, overcast with fog.",
-        _ => $"{city}: weather data not available."
-    };
-
-[Description("Get the current time in a city.")]
-static string GetTime([Description("The city name.")] string city) =>
-    city.ToUpperInvariant() switch
-    {
-        "SEATTLE" => "Seattle: 9:00 AM PST",
-        "NEW YORK" => "New York: 12:00 PM EST",
-        "LONDON" => "London: 5:00 PM GMT",
-        "DUBLIN" => "Dublin: 5:00 PM GMT",
-        _ => $"{city}: time data not available."
-    };
-
-// Create the agent — per-service-call persistence is the default behavior.
-// 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) ?
-    openAIClient.GetResponsesClient().AsIChatClient(deploymentName) :
-    openAIClient.GetResponsesClient().AsIChatClientWithStoredOutputDisabled(deploymentName);
-AIAgent agent = chatClient.AsAIAgent(
-    new ChatClientAgentOptions
-    {
-        Name = "WeatherAssistant",
-        ChatOptions = new()
-        {
-            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
-            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime)]
-        },
-    });
-
-await RunNonStreamingAsync();
-await RunStreamingAsync();
-
-async Task RunNonStreamingAsync()
-{
-    int lastChatHistorySize = 0;
-    string lastConversationId = string.Empty;
-
-    Console.ForegroundColor = ConsoleColor.Yellow;
-    Console.WriteLine("\n=== Non-Streaming Mode ===");
-    Console.ResetColor();
-
-    AgentSession session = await agent.CreateSessionAsync();
-
-    // First turn — ask about multiple cities so the model calls tools.
-    const string Prompt = "What's the weather and time in Seattle, New York, and London?";
-    PrintUserMessage(Prompt);
-
-    var response = await agent.RunAsync(Prompt, session);
-    PrintAgentResponse(response.Text);
-    PrintChatHistory(session, "After run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Second turn — follow-up to verify chat history is correct.
-    const string FollowUp1 = "And Dublin?";
-    PrintUserMessage(FollowUp1);
-
-    response = await agent.RunAsync(FollowUp1, session);
-    PrintAgentResponse(response.Text);
-    PrintChatHistory(session, "After second run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Third turn — follow-up to verify chat history is correct.
-    const string FollowUp2 = "Which city is the warmest?";
-    PrintUserMessage(FollowUp2);
-
-    response = await agent.RunAsync(FollowUp2, session);
-    PrintAgentResponse(response.Text);
-    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
-}
-
-async Task RunStreamingAsync()
-{
-    int lastChatHistorySize = 0;
-    string lastConversationId = string.Empty;
-
-    Console.ForegroundColor = ConsoleColor.Yellow;
-    Console.WriteLine("\n=== Streaming Mode ===");
-    Console.ResetColor();
-
-    AgentSession session = await agent.CreateSessionAsync();
-
-    // First turn — ask about multiple cities so the model calls tools.
-    const string Prompt = "What's the weather and time in Seattle, New York, and London?";
-    PrintUserMessage(Prompt);
-
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-
-    await foreach (var update in agent.RunStreamingAsync(Prompt, session))
-    {
-        Console.Write(update);
-
-        // During streaming we should be able to see updates to the chat history
-        // before the full run completes, as each service call is made and persisted.
-        PrintChatHistory(session, "During run", ref lastChatHistorySize, ref lastConversationId);
-    }
-
-    Console.WriteLine();
-    PrintChatHistory(session, "After run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Second turn — follow-up to verify chat history is correct.
-    const string FollowUp1 = "And Dublin?";
-    PrintUserMessage(FollowUp1);
-
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-
-    await foreach (var update in agent.RunStreamingAsync(FollowUp1, session))
-    {
-        Console.Write(update);
-
-        // During streaming we should be able to see updates to the chat history
-        // before the full run completes, as each service call is made and persisted.
-        PrintChatHistory(session, "During second run", ref lastChatHistorySize, ref lastConversationId);
-    }
-
-    Console.WriteLine();
-    PrintChatHistory(session, "After second run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Third turn — follow-up to verify chat history is correct.
-    const string FollowUp2 = "Which city is the warmest?";
-    PrintUserMessage(FollowUp2);
-
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-
-    await foreach (var update in agent.RunStreamingAsync(FollowUp2, session))
-    {
-        Console.Write(update);
-
-        // During streaming we should be able to see updates to the chat history
-        // before the full run completes, as each service call is made and persisted.
-        PrintChatHistory(session, "During third run", ref lastChatHistorySize, ref lastConversationId);
-    }
-
-    Console.WriteLine();
-    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
-}
-
-void PrintUserMessage(string message)
-{
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[User] ");
-    Console.ResetColor();
-    Console.WriteLine(message);
-}
-
-void PrintAgentResponse(string? text)
-{
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-    Console.WriteLine(text);
-}
-
-// Helper to print the current chat history from the session.
-void PrintChatHistory(AgentSession session, string label, ref int lastChatHistorySize, ref string lastConversationId)
-{
-    if (session.TryGetInMemoryChatHistory(out var history) && history.Count != lastChatHistorySize)
-    {
-        Console.ForegroundColor = ConsoleColor.DarkGray;
-        Console.WriteLine($"\n  [{label} — Chat history: {history.Count} message(s)]");
-        foreach (var msg in history)
-        {
-            var preview = msg.Text?.Length > 80 ? msg.Text[..80] + "…" : msg.Text;
-            var contentTypes = string.Join(", ", msg.Contents.Select(c => c.GetType().Name));
-            Console.WriteLine($"    {msg.Role,-12} | {(string.IsNullOrWhiteSpace(preview) ? $"[{contentTypes}]" : preview)}");
-        }
-
-        Console.ResetColor();
-
-        lastChatHistorySize = history.Count;
-    }
-
-    if (session is ChatClientAgentSession ccaSession && ccaSession.ConversationId is not null && ccaSession.ConversationId != lastConversationId)
-    {
-        Console.ForegroundColor = ConsoleColor.DarkGray;
-        Console.WriteLine($"  [{label} — Conversation ID: {ccaSession.ConversationId}]");
-        Console.ResetColor();
-        lastConversationId = ccaSession.ConversationId;
-    }
-}

dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/README.md

@@ -1,63 +0,0 @@
-# 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.
-
-## 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:
-
-- A `ChatHistoryPersistingChatClient` decorator is automatically inserted into the chat client pipeline
-- 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.
-
-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
-- **Observability** — you can inspect the chat history while the agent is still running (e.g., during streaming)
-- **Long-running tool loops** — agents with many sequential tool calls benefit from incremental persistence
-
-## How It Works
-
-The sample asks the agent about the weather and time in three cities. The model calls the `GetWeather` and `GetTime` tools for each city, resulting in multiple service calls within a single `RunStreamingAsync` invocation. After the run completes, the sample prints the full chat history to show all the intermediate messages that were persisted along the way.
-
-### Pipeline Architecture
-
-```
-ChatClientAgent
-  └─ FunctionInvokingChatClient    (handles tool call loop)
-       └─ ChatHistoryPersistingChatClient  (persists after each service call)
-            └─ Leaf IChatClient            (Azure OpenAI)
-```
-
-## Prerequisites
-
-- .NET 10 SDK or later
-- Azure OpenAI service endpoint and model deployment
-- Azure CLI installed and authenticated
-
-**Note**: This sample uses `DefaultAzureCredential`. Sign in with `az login` before running. For production, prefer a specific credential such as `ManagedIdentityCredential`. For more information, see the [Azure CLI authentication documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-## Environment Variables
-
-```powershell
-$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"  # Required
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"                       # Optional, defaults to gpt-4o-mini
-```
-
-## Running the Sample
-
-```powershell
-cd dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing
-dotnet run
-```
-
-## Expected Behavior
-
-The sample runs two conversation turns:
-
-1. **First turn** — asks about weather and time in three cities. The model calls `GetWeather` and `GetTime` tools (potentially in parallel or sequentially), then provides a summary. The chat history dump after the run shows all the intermediate tool call and result messages.
-
-2. **Second turn** — asks a follow-up question ("Which city is the warmest?") that uses the persisted conversation context. The chat history dump shows the full accumulated conversation.
-
-The chat history printout uses `session.TryGetInMemoryChatHistory()` to inspect the in-memory storage.

dotnet/samples/02-agents/Agents/README.md

@@ -45,7 +45,6 @@ Before you begin, ensure you have the following prerequisites:
 |[Declarative agent](./Agent_Step16_Declarative/)|This sample demonstrates how to declaratively define an agent.|
 |[Providing additional AI Context to an agent using multiple AIContextProviders](./Agent_Step17_AdditionalAIContext/)|This sample demonstrates how to inject additional AI context into a ChatClientAgent using multiple custom AIContextProvider components that are attached to the agent.|
 |[Using compaction pipeline with an agent](./Agent_Step18_CompactionPipeline/)|This sample demonstrates how to use a compaction pipeline to efficiently limit the size of the conversation history for an agent.|
-|[In-function-loop checkpointing](./Agent_Step19_InFunctionLoopCheckpointing/)|This sample demonstrates how to persist chat history after each service call during a tool-calling loop, enabling crash recovery and mid-run observability.|
 
 ## Running the samples from the console
 

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step10_UsingImages/Program.cs

@@ -24,7 +24,7 @@ AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: VisionName, model
 
 ChatMessage message = new(ChatRole.User, [
     new TextContent("What do you see in this image?"),
-    await DataContent.LoadFromAsync("Assets/walkway.jpg"),
+    await DataContent.LoadFromAsync("assets/walkway.jpg"),
 ]);
 
 AgentSession session = await agent.CreateSessionAsync();

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -9,7 +9,7 @@ using Microsoft.Extensions.AI;
 namespace WorkflowAsAnAgentSample;
 
 /// <summary>
-/// This sample introduces the concept of workflows as agents, where a workflow can be
+/// This sample introduces the concepts workflows as agents, where a workflow can be
 /// treated as an <see cref="AIAgent"/>. This allows you to interact with a workflow
 /// as if it were a single agent.
 ///
@@ -18,14 +18,6 @@ namespace WorkflowAsAnAgentSample;
 ///
 /// You will interact with the workflow in an interactive loop, sending messages and receiving
 /// streaming responses from the workflow as if it were an agent who responds in both languages.
-///
-/// This sample also demonstrates <see cref="IResettableExecutor"/>, which is required
-/// for stateful executors that are shared across multiple workflow runs. Each iteration
-/// of the interactive loop triggers a new workflow run against the same workflow instance.
-/// Between runs, the framework automatically calls <see cref="IResettableExecutor.ResetAsync"/>
-/// on shared executors so that accumulated state (e.g., collected messages) is cleared
-/// before the next run begins. See <c>WorkflowFactory.ConcurrentAggregationExecutor</c>
-/// for the implementation.
 /// </summary>
 /// <remarks>
 /// Pre-requisites:
@@ -47,10 +39,7 @@ public static class Program
         var agent = workflow.AsAIAgent("workflow-agent", "Workflow Agent");
         var session = await agent.CreateSessionAsync();
 
-        // Start an interactive loop to interact with the workflow as if it were an agent.
-        // Each iteration runs the workflow again on the same workflow instance. Between runs,
-        // the framework calls IResettableExecutor.ResetAsync() on shared stateful executors
-        // (like ConcurrentAggregationExecutor) to clear accumulated state from the previous run.
+        // Start an interactive loop to interact with the workflow as if it were an agent
         while (true)
         {
             Console.WriteLine();

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs

@@ -10,14 +10,6 @@ internal static class WorkflowFactory
 {
     /// <summary>
     /// Creates a workflow that uses two language agents to process input concurrently.
-    ///
-    /// In this workflow, the <c>Start</c> <see cref="ChatForwardingExecutor"/> and the
-    /// <see cref="ConcurrentAggregationExecutor"/> are provided as shared instances, meaning
-    /// the same executor objects are reused across multiple workflow runs. The language agents
-    /// (French and English) are created via a factory and instantiated per workflow run.
-    /// Stateful shared executors must implement <see cref="IResettableExecutor"/> so the
-    /// framework can clear their state between runs. Framework-provided executors like
-    /// <see cref="ChatForwardingExecutor"/> already implement this interface.
     /// </summary>
     /// <param name="chatClient">The chat client to use for the agents</param>
     /// <returns>A workflow that processes input using two language agents</returns>
@@ -48,16 +40,6 @@ internal static class WorkflowFactory
 
     /// <summary>
     /// Executor that aggregates the results from the concurrent agents.
-    ///
-    /// This executor is stateful — it accumulates messages in <see cref="_messages"/>
-    /// as they arrive from each agent. Because it is provided as a shared instance
-    /// (not via a factory), the same object is reused across workflow runs. Implementing
-    /// <see cref="IResettableExecutor"/> allows the framework to call <see cref="ResetAsync"/>
-    /// between runs, clearing accumulated state so each run starts fresh.
-    ///
-    /// Without <see cref="IResettableExecutor"/>, attempting to reuse a workflow containing
-    /// shared executor instances that do not implement this interface would throw an
-    /// <see cref="InvalidOperationException"/>.
     /// </summary>
     [YieldsOutput(typeof(string))]
     private sealed class ConcurrentAggregationExecutor() :
@@ -83,11 +65,7 @@ internal static class WorkflowFactory
             }
         }
 
-        /// <summary>
-        /// Resets the executor state between workflow runs by clearing accumulated messages.
-        /// The framework calls this automatically when a workflow run completes, before the
-        /// workflow can be used for another run.
-        /// </summary>
+        /// <inheritdoc/>
         public ValueTask ResetAsync()
         {
             this._messages.Clear();

dotnet/samples/04-hosting/DurableAgents/AzureFunctions/06_LongRunningTools/FunctionTriggers.cs

@@ -35,15 +35,13 @@ public static class FunctionTriggers
         int iterationCount = 0;
         while (iterationCount++ < input.MaxReviewAttempts)
         {
-            // NOTE: CustomStatus has a 16 KB UTF-16 limit in Durable Functions.
-            // Only include short metadata here - the full content is passed via activity inputs/outputs.
             context.SetCustomStatus(
                 new
                 {
                     message = "Requesting human feedback.",
                     approvalTimeoutHours = input.ApprovalTimeoutHours,
                     iterationCount,
-                    contentTitle = content.Title,
+                    content
                 });
 
             // Step 2: Notify user to review the content
@@ -65,6 +63,7 @@ public static class FunctionTriggers
                     {
                         message = $"Human approval timed out after {input.ApprovalTimeoutHours} hour(s). Treating as rejection.",
                         iterationCount,
+                        content
                     });
                 throw new TimeoutException($"Human approval timed out after {input.ApprovalTimeoutHours} hour(s).");
             }
@@ -74,7 +73,7 @@ public static class FunctionTriggers
                 context.SetCustomStatus(new
                 {
                     message = "Content approved by human reviewer. Publishing content...",
-                    contentTitle = content.Title,
+                    content
                 });
 
                 // Step 4: Publish the approved content
@@ -84,7 +83,7 @@ public static class FunctionTriggers
                 {
                     message = $"Content published successfully at {context.CurrentUtcDateTime:s}",
                     humanFeedback = humanResponse,
-                    contentTitle = content.Title,
+                    content
                 });
                 return new { content = content.Content };
             }
@@ -93,7 +92,7 @@ public static class FunctionTriggers
             {
                 message = "Content rejected by human reviewer. Incorporating feedback and regenerating...",
                 humanFeedback = humanResponse,
-                contentTitle = content.Title,
+                content
             });
 
             // Incorporate human feedback and regenerate

dotnet/samples/04-hosting/DurableAgents/ConsoleApps/06_LongRunningTools/Program.cs

@@ -77,15 +77,13 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
     int iterationCount = 0;
     while (iterationCount++ < input.MaxReviewAttempts)
     {
-        // NOTE: CustomStatus has a 16 KB UTF-16 limit in Durable Functions.
-        // Only include short metadata here - the full content is passed via activity inputs/outputs.
         context.SetCustomStatus(
             new
             {
                 message = "Requesting human feedback.",
                 approvalTimeoutHours = input.ApprovalTimeoutHours,
                 iterationCount,
-                contentTitle = content.Title,
+                content
             });
 
         // Step 2: Notify user to review the content
@@ -107,6 +105,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
                 {
                     message = $"Human approval timed out after {input.ApprovalTimeoutHours} hour(s). Treating as rejection.",
                     iterationCount,
+                    content
                 });
             throw new TimeoutException($"Human approval timed out after {input.ApprovalTimeoutHours} hour(s).");
         }
@@ -116,7 +115,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
             context.SetCustomStatus(new
             {
                 message = "Content approved by human reviewer. Publishing content...",
-                contentTitle = content.Title,
+                content
             });
 
             // Step 4: Publish the approved content
@@ -126,7 +125,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
             {
                 message = $"Content published successfully at {context.CurrentUtcDateTime:s}",
                 humanFeedback = humanResponse,
-                contentTitle = content.Title,
+                content
             });
             return new { content = content.Content };
         }
@@ -135,7 +134,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
         {
             message = "Content rejected by human reviewer. Incorporating feedback and regenerating...",
             humanFeedback = humanResponse,
-            contentTitle = content.Title,
+            content
         });
 
         // Incorporate human feedback and regenerate

dotnet/samples/04-hosting/DurableAgents/ConsoleApps/07_ReliableStreaming/Program.cs

@@ -285,7 +285,6 @@ async Task ReadStreamTask(string conversationId, string? cursor, CancellationTok
         if (chunk.Text != null)
         {
             Console.Write(chunk.Text);
-            Console.Out.Flush();
         }
 
         // Always update lastCursor to track the latest entry ID, even if text is null

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/04_WorkflowMcpTool.csproj

@@ -1,35 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
-    <OutputType>Exe</OutputType>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <!-- The Functions build tools don't like namespaces that start with a number -->
-    <AssemblyName>WorkflowMcpTool</AssemblyName>
-    <RootNamespace>WorkflowMcpTool</RootNamespace>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <FrameworkReference Include="Microsoft.AspNetCore.App" />
-  </ItemGroup>
-
-  <!-- Azure Functions packages -->
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
-  </ItemGroup>
-
-  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
-  <!--
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
-  </ItemGroup>
-  -->
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
-  </ItemGroup>
-</Project>

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/Executors.cs

@@ -1,59 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI.Workflows;
-
-namespace WorkflowMcpTool;
-
-internal sealed class TranslateText() : Executor<string, TranslationResult>("TranslateText")
-{
-    public override ValueTask<TranslationResult> HandleAsync(
-        string message,
-        IWorkflowContext context,
-        CancellationToken cancellationToken = default)
-    {
-        Console.WriteLine($"[Activity] TranslateText: '{message}'");
-        return ValueTask.FromResult(new TranslationResult(message, message.ToUpperInvariant()));
-    }
-}
-
-internal sealed class FormatOutput() : Executor<TranslationResult, string>("FormatOutput")
-{
-    public override ValueTask<string> HandleAsync(
-        TranslationResult message,
-        IWorkflowContext context,
-        CancellationToken cancellationToken = default)
-    {
-        Console.WriteLine("[Activity] FormatOutput: Formatting result");
-        return ValueTask.FromResult($"Original: {message.Original} => Translated: {message.Translated}");
-    }
-}
-
-internal sealed class LookupOrder() : Executor<string, OrderInfo>("LookupOrder")
-{
-    public override ValueTask<OrderInfo> HandleAsync(
-        string message,
-        IWorkflowContext context,
-        CancellationToken cancellationToken = default)
-    {
-        Console.WriteLine($"[Activity] LookupOrder: '{message}'");
-        return ValueTask.FromResult(new OrderInfo(message, "Alice Johnson", "Wireless Headphones", Quantity: 2, UnitPrice: 49.99m));
-    }
-}
-
-internal sealed class EnrichOrder() : Executor<OrderInfo, OrderSummary>("EnrichOrder")
-{
-    public override ValueTask<OrderSummary> HandleAsync(
-        OrderInfo message,
-        IWorkflowContext context,
-        CancellationToken cancellationToken = default)
-    {
-        Console.WriteLine($"[Activity] EnrichOrder: '{message.OrderId}'");
-        return ValueTask.FromResult(new OrderSummary(message, TotalPrice: message.Quantity * message.UnitPrice, Status: "Confirmed"));
-    }
-}
-
-internal sealed record TranslationResult(string Original, string Translated);
-
-internal sealed record OrderInfo(string OrderId, string CustomerName, string Product, int Quantity, decimal UnitPrice);
-
-internal sealed record OrderSummary(OrderInfo Order, decimal TotalPrice, string Status);

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/Program.cs

@@ -1,44 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to expose a durable workflow as an MCP (Model Context Protocol) tool.
-// When using AddWorkflow with exposeMcpToolTrigger: true, the Functions host will automatically
-// generate a remote MCP endpoint for the app at /runtime/webhooks/mcp with a workflow-specific
-// tool name. MCP-compatible clients can then invoke the workflow as a tool.
-
-using Microsoft.Agents.AI.Hosting.AzureFunctions;
-using Microsoft.Agents.AI.Workflows;
-using Microsoft.Azure.Functions.Worker.Builder;
-using Microsoft.Extensions.Hosting;
-using WorkflowMcpTool;
-
-// Define executors
-TranslateText translateText = new();
-FormatOutput formatOutput = new();
-LookupOrder lookupOrder = new();
-EnrichOrder enrichOrder = new();
-
-// Build a simple workflow: TranslateText -> FormatOutput
-Workflow translateWorkflow = new WorkflowBuilder(translateText)
-    .WithName("Translate")
-    .WithDescription("Translate text to uppercase and format the result")
-    .AddEdge(translateText, formatOutput)
-    .Build();
-
-// Build a workflow that returns a POCO: LookupOrder -> EnrichOrder
-Workflow orderLookupWorkflow = new WorkflowBuilder(lookupOrder)
-    .WithName("OrderLookup")
-    .WithDescription("Look up an order by ID and return enriched order details")
-    .AddEdge(lookupOrder, enrichOrder)
-    .Build();
-
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableWorkflows(workflows =>
-    {
-        // Expose both workflows as MCP tool triggers.
-        workflows.AddWorkflow(translateWorkflow, exposeStatusEndpoint: false, exposeMcpToolTrigger: true);
-        workflows.AddWorkflow(orderLookupWorkflow, exposeStatusEndpoint: false, exposeMcpToolTrigger: true);
-    })
-    .Build();
-app.Run();

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/README.md

@@ -1,81 +0,0 @@
-# Workflow as MCP Tool Sample
-
-This sample demonstrates how to expose durable workflows as [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, enabling MCP-compatible clients to invoke workflows directly.
-
-## Key Concepts Demonstrated
-
-- **Workflow as MCP Tool**: Expose workflows as callable MCP tools using `exposeMcpToolTrigger: true`
-- **MCP Server Hosting**: The Azure Functions host automatically generates a remote MCP endpoint at `/runtime/webhooks/mcp`
-- **String and POCO Results**: Shows workflows returning both plain strings and structured JSON objects
-
-## Sample Architecture
-
-The sample creates two workflows exposed as MCP tools:
-
-### Translate Workflow (returns a string)
-
-| Executor | Input | Output | Description |
-|----------|-------|--------|-------------|
-| **TranslateText** | `string` | `TranslationResult` | Converts input text to uppercase |
-| **FormatOutput** | `TranslationResult` | `string` | Formats the result into a readable string |
-
-### OrderLookup Workflow (returns a POCO)
-
-| Executor | Input | Output | Description |
-|----------|-------|--------|-------------|
-| **LookupOrder** | `string` | `OrderInfo` | Looks up an order by ID |
-| **EnrichOrder** | `OrderInfo` | `OrderSummary` | Adds computed fields (total price, status) |
-
-## Environment Setup
-
-See the [README.md](../../README.md) file in the parent directory for complete setup instructions, including:
-
-- Prerequisites installation
-- Durable Task Scheduler setup
-- Storage emulator configuration
-
-For this sample, you'll also need [Node.js](https://nodejs.org/en/download) to use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
-
-## Running the Sample
-
-1. **Start the Function App**:
-
-   ```bash
-   cd dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool
-   func start
-   ```
-
-2. **Note the MCP Server Endpoint**: When the app starts, you'll see the MCP server endpoint in the terminal output:
-
-   ```text
-   MCP server endpoint:  http://localhost:7071/runtime/webhooks/mcp
-   ```
-
-## Invoking Workflows via MCP Inspector
-
-1. Install and run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
-
-   ```bash
-   npx @modelcontextprotocol/inspector
-   ```
-
-2. Connect to the MCP server endpoint:
-   - For **Transport Type**, select **"Streamable HTTP"**
-   - For **URL**, enter `http://localhost:7071/runtime/webhooks/mcp`
-   - Click the **Connect** button
-
-3. Click the **List Tools** button. You should see two tools: `Translate` and `OrderLookup`.
-
-4. Test the **Translate** tool (returns a plain string):
-   - Select the `Translate` tool
-   - Set `hello world` as the `input` parameter
-   - Click **Run Tool**
-   - Expected result: `Original: hello world => Translated: HELLO WORLD`
-
-5. Test the **OrderLookup** tool (returns a JSON object):
-   - Select the `OrderLookup` tool
-   - Set `ORD-2025-42` as the `input` parameter
-   - Click **Run Tool**
-   - Expected result: A JSON object containing order details such as `OrderId`, `CustomerName`, `Product`, `TotalPrice`, and `Status`
-
-You'll see the workflow executor activities logged in the terminal where you ran `func start`.

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/host.json

@@ -1,20 +0,0 @@
-{
-  "version": "2.0",
-  "logging": {
-    "logLevel": {
-      "Microsoft.Agents.AI.DurableTask": "Information",
-      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
-      "DurableTask": "Information",
-      "Microsoft.DurableTask": "Information"
-    }
-  },
-  "extensions": {
-    "durableTask": {
-      "hubName": "default",
-      "storageProvider": {
-        "type": "AzureManaged",
-        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
-      }
-    }
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/local.settings.json

@@ -1,8 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/05_WorkflowAndAgents.csproj

@@ -1,42 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
-    <OutputType>Exe</OutputType>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <!-- The Functions build tools don't like namespaces that start with a number -->
-    <AssemblyName>WorkflowAndAgents</AssemblyName>
-    <RootNamespace>WorkflowAndAgents</RootNamespace>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <FrameworkReference Include="Microsoft.AspNetCore.App" />
-  </ItemGroup>
-
-  <!-- Azure Functions packages -->
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-
-  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
-  <!--
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
-    <PackageReference Include="Microsoft.Agents.AI.OpenAI" />
-  </ItemGroup>
-  -->
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-</Project>

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/Executors.cs

@@ -1,31 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI.Workflows;
-
-namespace WorkflowAndAgents;
-
-internal sealed class TranslateText() : Executor<string, TranslationResult>("TranslateText")
-{
-    public override ValueTask<TranslationResult> HandleAsync(
-        string message,
-        IWorkflowContext context,
-        CancellationToken cancellationToken = default)
-    {
-        Console.WriteLine($"[Activity] TranslateText: '{message}'");
-        return ValueTask.FromResult(new TranslationResult(message, message.ToUpperInvariant()));
-    }
-}
-
-internal sealed class FormatOutput() : Executor<TranslationResult, string>("FormatOutput")
-{
-    public override ValueTask<string> HandleAsync(
-        TranslationResult message,
-        IWorkflowContext context,
-        CancellationToken cancellationToken = default)
-    {
-        Console.WriteLine("[Activity] FormatOutput: Formatting result");
-        return ValueTask.FromResult($"Original: {message.Original} => Translated: {message.Translated}");
-    }
-}
-
-internal sealed record TranslationResult(string Original, string Translated);

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/Program.cs

@@ -1,64 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates using ConfigureDurableOptions to register BOTH agents AND workflows
-// in a single Azure Functions app. It uses a workflow to translate text and a standalone AI agent
-// accessible via HTTP and MCP tool triggers.
-
-#pragma warning disable IDE0002 // Simplify Member Access
-
-using Azure;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Hosting.AzureFunctions;
-using Microsoft.Agents.AI.Workflows;
-using Microsoft.Azure.Functions.Worker.Builder;
-using Microsoft.Extensions.Hosting;
-using OpenAI.Chat;
-using WorkflowAndAgents;
-
-// Get the Azure OpenAI endpoint and deployment name from environment variables.
-string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
-
-// Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
-string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
-AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
-    ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
-
-ChatClient chatClient = client.GetChatClient(deploymentName);
-
-// Define a standalone AI agent
-AIAgent assistant = chatClient.AsAIAgent(
-    "You are a helpful assistant. Answer questions clearly and concisely.",
-    "Assistant",
-    description: "A general-purpose helpful assistant.");
-
-// Define workflow executors
-TranslateText translateText = new();
-FormatOutput formatOutput = new();
-
-// Build a workflow: TranslateText -> FormatOutput
-Workflow translateWorkflow = new WorkflowBuilder(translateText)
-    .WithName("Translate")
-    .WithDescription("Translate text to uppercase and format the result")
-    .AddEdge(translateText, formatOutput)
-    .Build();
-
-// Use ConfigureDurableOptions to register both agents and workflows together
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableOptions(options =>
-    {
-        // Register the standalone agent with HTTP and MCP tool triggers
-        options.Agents.AddAIAgent(assistant, enableHttpTrigger: true, enableMcpToolTrigger: true);
-
-        // Register the workflow with an HTTP endpoint and MCP tool trigger
-        options.Workflows.AddWorkflow(translateWorkflow, exposeStatusEndpoint: false, exposeMcpToolTrigger: true);
-    })
-    .Build();
-app.Run();

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/README.md

@@ -1,76 +0,0 @@
-# Workflow and Agents Sample
-
-This sample demonstrates how to use `ConfigureDurableOptions` to register **both** AI agents **and** workflows in a single Azure Functions app. This is the recommended approach when your application needs both standalone agents and orchestrated workflows.
-
-## Key Concepts Demonstrated
-
-- **Unified Configuration**: Use `ConfigureDurableOptions` to register agents and workflows together
-- **Standalone Agent**: An AI agent accessible via HTTP and MCP tool triggers
-- **Workflow**: A simple text translation workflow also exposed as an MCP tool
-- **Mixed Triggers**: Both agents and workflows coexist in the same Functions host
-
-## Sample Architecture
-
-### Standalone Agent
-
-| Agent | Description |
-|-------|-------------|
-| **Assistant** | A general-purpose AI assistant accessible via HTTP (`/agents/Assistant/run`) and as an MCP tool |
-
-### Translate Workflow
-
-| Executor | Input | Output | Description |
-|----------|-------|--------|-------------|
-| **TranslateText** | `string` | `TranslationResult` | Converts input text to uppercase |
-| **FormatOutput** | `TranslationResult` | `string` | Formats the result into a readable string |
-
-## Environment Setup
-
-See the [README.md](../../README.md) file in the parent directory for complete setup instructions, including:
-
-- Prerequisites installation
-- Durable Task Scheduler setup
-- Storage emulator configuration
-
-This sample also requires Azure OpenAI credentials. Set the following in `local.settings.json`:
-
-- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint URL
-- `AZURE_OPENAI_DEPLOYMENT_NAME`: Your chat model deployment name
-- `AZURE_OPENAI_API_KEY` (optional): If not set, Azure CLI credential is used
-
-## Running the Sample
-
-1. **Start the Function App**:
-
-   ```bash
-   cd dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents
-   func start
-   ```
-
-2. **Expected Functions**: When the app starts, you should see functions for both the agent and the workflow:
-
-   - `dafx-Assistant` (entity trigger for the agent)
-   - `http-Assistant` (HTTP trigger for the agent)
-   - `mcptool-Assistant` (MCP tool trigger for the agent)
-   - `wf-Translate` (orchestration trigger for the workflow)
-   - `mcptool-wf-Translate` (MCP tool trigger for the workflow)
-
-## Invoking the Agent via HTTP
-
-```bash
-curl -X POST http://localhost:7071/agents/Assistant/run \
-  -H "Content-Type: application/json" \
-  -d '{"query": "What is the capital of France?"}'
-```
-
-## Invoking via MCP Inspector
-
-1. Install and run the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
-
-   ```bash
-   npx @modelcontextprotocol/inspector
-   ```
-
-2. Connect to `http://localhost:7071/runtime/webhooks/mcp` using **Streamable HTTP** transport.
-
-3. Click **List Tools** to see both the `Assistant` agent tool and the `Translate` workflow tool.

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/host.json

@@ -1,20 +0,0 @@
-{
-  "version": "2.0",
-  "logging": {
-    "logLevel": {
-      "Microsoft.Agents.AI.DurableTask": "Information",
-      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
-      "DurableTask": "Information",
-      "Microsoft.DurableTask": "Information"
-    }
-  },
-  "extensions": {
-    "durableTask": {
-      "hubName": "default",
-      "storageProvider": {
-        "type": "AzureManaged",
-        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
-      }
-    }
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/local.settings.json

@@ -1,10 +0,0 @@
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
-    "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
-    "AZURE_OPENAI_DEPLOYMENT_NAME": "<AZURE_OPENAI_DEPLOYMENT_NAME>"
-  }
-}

dotnet/samples/04-hosting/DurableWorkflows/README.md

@@ -48,4 +48,3 @@ $env:DURABLE_TASK_SCHEDULER_CONNECTION_STRING = "AccountEndpoint=http://localhos
 | [01_SequentialWorkflow](AzureFunctions/01_SequentialWorkflow/) | Sequential workflow hosted in Azure Functions |
 | [02_ConcurrentWorkflow](AzureFunctions/02_ConcurrentWorkflow/) | Concurrent workflow hosted in Azure Functions |
 | [03_WorkflowHITL](AzureFunctions/03_WorkflowHITL/) | Human-in-the-loop workflow hosted in Azure Functions |
-| [04_WorkflowMcpTool](AzureFunctions/04_WorkflowMcpTool/) | Workflow exposed as an MCP tool |

dotnet/samples/05-end-to-end/A2AClientServer/A2AServer/HostAgentFactory.cs

@@ -59,7 +59,7 @@ internal static class HostAgentFactory
             PushNotifications = false,
         };
 
-        var invoiceQuery = new A2A.AgentSkill()
+        var invoiceQuery = new AgentSkill()
         {
             Id = "id_invoice_agent",
             Name = "InvoiceQuery",
@@ -91,7 +91,7 @@ internal static class HostAgentFactory
             PushNotifications = false,
         };
 
-        var policyQuery = new A2A.AgentSkill()
+        var policyQuery = new AgentSkill()
         {
             Id = "id_policy_agent",
             Name = "PolicyAgent",
@@ -123,7 +123,7 @@ internal static class HostAgentFactory
             PushNotifications = false,
         };
 
-        var logisticsQuery = new A2A.AgentSkill()
+        var logisticsQuery = new AgentSkill()
         {
             Id = "id_logistics_agent",
             Name = "LogisticsQuery",

dotnet/src/Microsoft.Agents.AI.AzureAI/ProjectResponsesClientExtensions.cs

@@ -1,60 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
-using Microsoft.Shared.Diagnostics;
-using OpenAI.Responses;
-
-namespace Azure.AI.Extensions.OpenAI;
-
-/// <summary>
-/// Provides extension methods for <see cref="ProjectResponsesClient"/>
-/// to simplify the creation of AI agents that work with Azure AI services.
-/// </summary>
-[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
-public static class ProjectResponsesClientExtensions
-{
-    /// <summary>
-    /// Gets an <see cref="IChatClient"/> for use with this <see cref="ProjectResponsesClient"/> that does not store responses for later retrieval.
-    /// </summary>
-    /// <remarks>
-    /// This corresponds to setting the "store" property in the JSON representation to false.
-    /// </remarks>
-    /// <param name="responseClient">The client.</param>
-    /// <param name="deploymentName">Optional deployment name (model) to use for requests.</param>
-    /// <param name="includeReasoningEncryptedContent">
-    /// Includes an encrypted version of reasoning tokens in reasoning item outputs.
-    /// This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly
-    /// (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program).
-    /// Defaults to <see langword="true"/>.
-    /// </param>
-    /// <returns>An <see cref="IChatClient"/> that can be used to converse via the <see cref="ProjectResponsesClient"/> that does not store responses for later retrieval.</returns>
-    /// <exception cref="ArgumentNullException"><paramref name="responseClient"/> is <see langword="null"/>.</exception>
-    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-    public static IChatClient AsIChatClientWithStoredOutputDisabled(this ProjectResponsesClient responseClient, string? deploymentName = null, bool includeReasoningEncryptedContent = true)
-    {
-        return Throw.IfNull(responseClient)
-            .AsIChatClient(deploymentName)
-            .AsBuilder()
-            .ConfigureOptions(x =>
-            {
-                var previousFactory = x.RawRepresentationFactory;
-                x.RawRepresentationFactory = state =>
-                {
-                    var responseOptions = previousFactory?.Invoke(state) as CreateResponseOptions ?? new CreateResponseOptions();
-
-                    responseOptions.StoredOutputEnabled = false;
-
-                    if (includeReasoningEncryptedContent &&
-                        !responseOptions.IncludedProperties.Contains(IncludedResponseProperty.ReasoningEncryptedContent))
-                    {
-                        responseOptions.IncludedProperties.Add(IncludedResponseProperty.ReasoningEncryptedContent);
-                    }
-
-                    return responseOptions;
-                };
-            })
-            .Build();
-    }
-}

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctionExecutor.cs

@@ -167,20 +167,6 @@ internal sealed class BuiltInFunctionExecutor : IFunctionExecutor
             return;
         }
 
-        if (context.FunctionDefinition.EntryPoint == BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint)
-        {
-            if (mcpToolInvocationContext is null)
-            {
-                throw new InvalidOperationException($"MCP tool invocation context binding is missing for the invocation {context.InvocationId}.");
-            }
-
-            context.GetInvocationResult().Value = await BuiltInFunctions.RunWorkflowMcpToolAsync(
-                mcpToolInvocationContext,
-                durableTaskClient,
-                context);
-            return;
-        }
-
         throw new InvalidOperationException($"Unsupported function entry point '{context.FunctionDefinition.EntryPoint}' for invocation {context.InvocationId}.");
     }
 

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctions.cs

@@ -29,7 +29,6 @@ internal static class BuiltInFunctions
     internal static readonly string InvokeWorkflowActivityFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(InvokeWorkflowActivityAsync)}";
     internal static readonly string GetWorkflowStatusHttpFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(GetWorkflowStatusAsync)}";
     internal static readonly string RespondToWorkflowHttpFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RespondToWorkflowAsync)}";
-    internal static readonly string RunWorkflowMcpToolFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RunWorkflowMcpToolAsync)}";
 
 #pragma warning disable IL3000 // Avoid accessing Assembly file path when publishing as a single file - Azure Functions does not use single-file publishing
     internal static readonly string ScriptFile = Path.GetFileName(typeof(BuiltInFunctions).Assembly.Location);
@@ -379,55 +378,6 @@ internal static class BuiltInFunctions
         return agentResponse.Text;
     }
 
-    /// <summary>
-    /// Runs a workflow via MCP tool trigger.
-    /// Extracts the <c>input</c> argument, schedules a new orchestration, waits for completion, and returns the output.
-    /// </summary>
-    public static async Task<string?> RunWorkflowMcpToolAsync(
-        [McpToolTrigger("BuiltInWorkflowMcpTool")] ToolInvocationContext context,
-        [DurableClient] DurableTaskClient client,
-        FunctionContext functionContext)
-    {
-        if (context.Arguments is null)
-        {
-            throw new ArgumentException("MCP Tool invocation is missing required arguments.");
-        }
-
-        if (!context.Arguments.TryGetValue("input", out object? inputObj) || inputObj is not string input)
-        {
-            throw new ArgumentException("MCP Tool invocation is missing required 'input' argument of type string.");
-        }
-
-        string workflowName = context.Name;
-        string orchestrationFunctionName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflowName);
-
-        DurableWorkflowInput<string> orchestrationInput = new() { Input = input };
-        string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(orchestrationFunctionName, orchestrationInput);
-
-        OrchestrationMetadata? metadata = await client.WaitForInstanceCompletionAsync(
-            instanceId,
-            getInputsAndOutputs: true,
-            cancellation: functionContext.CancellationToken);
-
-        if (metadata is null)
-        {
-            throw new InvalidOperationException($"Workflow orchestration '{instanceId}' returned no metadata.");
-        }
-
-        if (metadata.RuntimeStatus is OrchestrationRuntimeStatus.Failed)
-        {
-            string errorMessage = metadata.FailureDetails?.ErrorMessage ?? "Unknown error";
-            throw new InvalidOperationException($"Workflow orchestration '{instanceId}' failed: {errorMessage}");
-        }
-
-        if (metadata.RuntimeStatus is not OrchestrationRuntimeStatus.Completed)
-        {
-            throw new InvalidOperationException($"Workflow orchestration '{instanceId}' ended with unexpected status '{metadata.RuntimeStatus}'.");
-        }
-
-        return metadata.ReadOutputAs<DurableWorkflowResult>()?.Result;
-    }
-
     /// <summary>
     /// Creates an error response with the specified status code and error message.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/CHANGELOG.md

@@ -2,7 +2,6 @@
 
 ## [Unreleased]
 
-- Added MCP tool trigger support for durable workflows ([#4768](https://github.com/microsoft/agent-framework/pull/4768))
 - Added Azure Functions hosting support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))
 
 ## v1.0.0-preview.251219.1

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/DefaultFunctionsAgentOptionsProvider.cs

@@ -6,8 +6,7 @@ namespace Microsoft.Agents.AI.Hosting.AzureFunctions;
 
 /// <summary>
 /// Provides access to agent-specific options for functions agents by name.
-/// Returns <see langword="false"/> when no explicit options have been configured for an agent,
-/// which distinguishes standalone agents from those auto-registered by workflows.
+/// Returns default options (HTTP trigger enabled, MCP tool disabled) when no explicit options were configured.
 /// </summary>
 internal sealed class DefaultFunctionsAgentOptionsProvider(IReadOnlyDictionary<string, FunctionsAgentOptions> functionsAgentOptions)
     : IFunctionsAgentOptionsProvider
@@ -15,19 +14,32 @@ internal sealed class DefaultFunctionsAgentOptionsProvider(IReadOnlyDictionary<s
     private readonly IReadOnlyDictionary<string, FunctionsAgentOptions> _functionsAgentOptions =
         functionsAgentOptions ?? throw new ArgumentNullException(nameof(functionsAgentOptions));
 
+    // Default options. HTTP trigger enabled, MCP tool disabled.
+    private static readonly FunctionsAgentOptions s_defaultOptions = new()
+    {
+        HttpTrigger = { IsEnabled = true },
+        McpToolTrigger = { IsEnabled = false }
+    };
+
     /// <summary>
     /// Attempts to retrieve the options associated with the specified agent name.
-    /// Returns <see langword="false"/> when no options have been explicitly configured for the agent.
+    /// If not found, a default options instance (with HTTP trigger enabled) is returned.
     /// </summary>
     /// <param name="agentName">The name of the agent whose options are to be retrieved. Cannot be null or empty.</param>
-    /// <param name="options">
-    /// When this method returns <see langword="true"/>, contains the options for the specified agent;
-    /// otherwise, <see langword="null"/>.
-    /// </param>
-    /// <returns><see langword="true"/> if options were found for the agent; otherwise, <see langword="false"/>.</returns>
+    /// <param name="options">The options for the specified agent. Will never be null.</param>
+    /// <returns>Always true. Returns configured options if present; otherwise default fallback options.</returns>
     public bool TryGet(string agentName, [NotNullWhen(true)] out FunctionsAgentOptions? options)
     {
         ArgumentException.ThrowIfNullOrEmpty(agentName);
-        return this._functionsAgentOptions.TryGetValue(agentName, out options);
+
+        if (this._functionsAgentOptions.TryGetValue(agentName, out FunctionsAgentOptions? existing))
+        {
+            options = existing;
+            return true;
+        }
+
+        // If not defined, return default options.
+        options = s_defaultOptions;
+        return true;
     }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/DurableAgentFunctionMetadataTransformer.cs

@@ -6,13 +6,9 @@ using Microsoft.Extensions.Logging;
 namespace Microsoft.Agents.AI.Hosting.AzureFunctions;
 
 /// <summary>
-/// Transforms function metadata by registering durable agent functions for each explicitly configured agent.
+/// Transforms function metadata by registering durable agent functions for each configured agent.
 /// </summary>
-/// <remarks>
-/// This transformer adds entity, HTTP, and MCP tool trigger functions for agents that have
-/// explicit <see cref="FunctionsAgentOptions"/>. Agents auto-registered by workflows
-/// (which lack explicit options) are handled by <see cref="DurableWorkflowsFunctionMetadataTransformer"/>.
-/// </remarks>
+/// <remarks>This transformer adds both entity trigger and HTTP trigger functions for every agent registered in the application.</remarks>
 internal sealed class DurableAgentFunctionMetadataTransformer : IFunctionMetadataTransformer
 {
     private readonly ILogger<DurableAgentFunctionMetadataTransformer> _logger;
@@ -42,27 +38,24 @@ internal sealed class DurableAgentFunctionMetadataTransformer : IFunctionMetadat
         {
             string agentName = kvp.Key;
 
-            // Only generate triggers for agents with explicit Functions agent options.
-            // Agents auto-registered by workflows are handled by DurableWorkflowsFunctionMetadataTransformer.
-            if (!this._functionsAgentOptionsProvider.TryGet(agentName, out FunctionsAgentOptions? agentTriggerOptions))
-            {
-                continue;
-            }
-
             this._logger.LogRegisteringTriggerForAgent(agentName, "entity");
+
             original.Add(FunctionMetadataFactory.CreateEntityTrigger(agentName));
 
-            if (agentTriggerOptions.HttpTrigger.IsEnabled)
+            if (this._functionsAgentOptionsProvider.TryGet(agentName, out FunctionsAgentOptions? agentTriggerOptions))
             {
-                this._logger.LogRegisteringTriggerForAgent(agentName, "http");
-                original.Add(FunctionMetadataFactory.CreateHttpTrigger(agentName, $"agents/{agentName}/run", BuiltInFunctions.RunAgentHttpFunctionEntryPoint));
-            }
+                if (agentTriggerOptions.HttpTrigger.IsEnabled)
+                {
+                    this._logger.LogRegisteringTriggerForAgent(agentName, "http");
+                    original.Add(FunctionMetadataFactory.CreateHttpTrigger(agentName, $"agents/{agentName}/run", BuiltInFunctions.RunAgentHttpFunctionEntryPoint));
+                }
 
-            if (agentTriggerOptions.McpToolTrigger.IsEnabled)
-            {
-                AIAgent agent = kvp.Value(this._serviceProvider);
-                this._logger.LogRegisteringTriggerForAgent(agentName, "mcpTool");
-                original.Add(CreateMcpToolTrigger(agentName, agent.Description));
+                if (agentTriggerOptions.McpToolTrigger.IsEnabled)
+                {
+                    AIAgent agent = kvp.Value(this._serviceProvider);
+                    this._logger.LogRegisteringTriggerForAgent(agentName, "mcpTool");
+                    original.Add(CreateMcpToolTrigger(agentName, agent.Description));
+                }
             }
         }
     }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/DurableAgentsOptionsExtensions.cs

@@ -134,17 +134,4 @@ public static class DurableAgentsOptionsExtensions
     {
         return new Dictionary<string, FunctionsAgentOptions>(s_agentOptions, StringComparer.OrdinalIgnoreCase);
     }
-
-    /// <summary>
-    /// Ensures every agent in <paramref name="agentNames"/> has an entry in the
-    /// options registry. Agents that already have explicit options are left untouched.
-    /// New entries receive the default configuration (HTTP trigger enabled, MCP tool disabled).
-    /// </summary>
-    internal static void EnsureDefaultOptionsForAll(IEnumerable<string> agentNames)
-    {
-        foreach (string name in agentNames)
-        {
-            s_agentOptions.TryAdd(name, new FunctionsAgentOptions { HttpTrigger = { IsEnabled = true } });
-        }
-    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/FunctionMetadataFactory.cs

@@ -1,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System.Text.Json.Nodes;
 using Microsoft.Agents.AI.DurableTask;
 using Microsoft.Azure.Functions.Worker.Core.FunctionMetadata;
 
@@ -99,65 +98,4 @@ internal static class FunctionMetadataFactory
             ScriptFile = BuiltInFunctions.ScriptFile,
         };
     }
-
-    /// <summary>
-    /// Creates function metadata for an MCP tool trigger function that starts a workflow.
-    /// </summary>
-    /// <param name="workflowName">The name of the workflow to expose as an MCP tool.</param>
-    /// <param name="description">An optional description for the MCP tool. If null, a default description is generated.</param>
-    /// <returns>A <see cref="DefaultFunctionMetadata"/> configured for an MCP tool trigger.</returns>
-    internal static DefaultFunctionMetadata CreateWorkflowMcpToolTrigger(
-        string workflowName,
-        string? description)
-    {
-        var functionName = $"{BuiltInFunctions.McpToolPrefix}{workflowName}";
-        var toolDescription = description ?? $"Run the {workflowName} workflow";
-
-        var toolProperties = new JsonArray(new JsonObject
-        {
-            ["propertyName"] = "input",
-            ["propertyType"] = "string",
-            ["description"] = "The input to the workflow.",
-            ["isRequired"] = true,
-            ["isArray"] = false,
-        });
-
-        var triggerBinding = new JsonObject
-        {
-            ["name"] = "context",
-            ["type"] = "mcpToolTrigger",
-            ["direction"] = "In",
-            ["toolName"] = workflowName,
-            ["description"] = toolDescription,
-            ["toolProperties"] = toolProperties.ToJsonString(),
-        };
-
-        var inputBinding = new JsonObject
-        {
-            ["name"] = "input",
-            ["type"] = "mcpToolProperty",
-            ["direction"] = "In",
-            ["propertyName"] = "input",
-            ["description"] = "The input to the workflow",
-            ["isRequired"] = true,
-            ["dataType"] = "String",
-            ["propertyType"] = "string",
-        };
-
-        var clientBinding = new JsonObject
-        {
-            ["name"] = "client",
-            ["type"] = "durableClient",
-            ["direction"] = "In",
-        };
-
-        return new DefaultFunctionMetadata
-        {
-            Name = functionName,
-            Language = "dotnet-isolated",
-            RawBindings = [triggerBinding.ToJsonString(), inputBinding.ToJsonString(), clientBinding.ToJsonString()],
-            EntryPoint = BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint,
-            ScriptFile = BuiltInFunctions.ScriptFile,
-        };
-    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/FunctionsApplicationBuilderExtensions.cs

@@ -27,16 +27,9 @@ public static class FunctionsApplicationBuilderExtensions
     {
         ArgumentNullException.ThrowIfNull(configure);
 
-        // Create/get shared options BEFORE the DurableTask library call so it can find them.
-        FunctionsDurableOptions sharedOptions = GetOrCreateSharedOptions(builder.Services);
-
         // The main agent services registration is done in Microsoft.DurableTask.Agents.
         builder.Services.ConfigureDurableAgents(configure);
 
-        // Ensure all agents registered through this path have default FunctionsAgentOptions.
-        // This distinguishes them from agents auto-registered by workflows.
-        DurableAgentsOptionsExtensions.EnsureDefaultOptionsForAll(sharedOptions.Agents.GetAgentFactories().Keys);
-
         builder.Services.TryAddSingleton<IFunctionsAgentOptionsProvider>(_ =>
             new DefaultFunctionsAgentOptionsProvider(DurableAgentsOptionsExtensions.GetAgentOptionsSnapshot()));
 
@@ -74,13 +67,6 @@ public static class FunctionsApplicationBuilderExtensions
 
         builder.Services.ConfigureDurableOptions(configure);
 
-        if (DurableAgentsOptionsExtensions.GetAgentOptionsSnapshot().Count > 0)
-        {
-            builder.Services.TryAddSingleton<IFunctionsAgentOptionsProvider>(_ =>
-                new DefaultFunctionsAgentOptionsProvider(DurableAgentsOptionsExtensions.GetAgentOptionsSnapshot()));
-            builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IFunctionMetadataTransformer, DurableAgentFunctionMetadataTransformer>());
-        }
-
         if (sharedOptions.Workflows.Workflows.Count > 0)
         {
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IFunctionMetadataTransformer, DurableWorkflowsFunctionMetadataTransformer>());
@@ -116,14 +102,12 @@ public static class FunctionsApplicationBuilderExtensions
 
         builder.UseWhen<BuiltInFunctionExecutionMiddleware>(static context =>
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunAgentHttpFunctionEntryPoint, StringComparison.Ordinal) ||
-            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunAgentMcpToolFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunAgentEntityFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunWorkflowOrchestrationHttpFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunWorkflowOrchestrationFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.InvokeWorkflowActivityFunctionEntryPoint, StringComparison.Ordinal) ||
             string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.GetWorkflowStatusHttpFunctionEntryPoint, StringComparison.Ordinal) ||
-            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RespondToWorkflowHttpFunctionEntryPoint, StringComparison.Ordinal) ||
-            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RunWorkflowMcpToolFunctionEntryPoint, StringComparison.Ordinal)
+            string.Equals(context.FunctionDefinition.EntryPoint, BuiltInFunctions.RespondToWorkflowHttpFunctionEntryPoint, StringComparison.Ordinal)
         );
         builder.Services.TryAddSingleton<BuiltInFunctionExecutor>();
     }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/FunctionsDurableOptions.cs

@@ -10,7 +10,6 @@ namespace Microsoft.Agents.AI.Hosting.AzureFunctions;
 internal sealed class FunctionsDurableOptions : DurableOptions
 {
     private readonly HashSet<string> _statusEndpointWorkflows = new(StringComparer.OrdinalIgnoreCase);
-    private readonly HashSet<string> _mcpToolTriggerWorkflows = new(StringComparer.OrdinalIgnoreCase);
 
     /// <summary>
     /// Enables the status HTTP endpoint for the specified workflow.
@@ -27,20 +26,4 @@ internal sealed class FunctionsDurableOptions : DurableOptions
     {
         return this._statusEndpointWorkflows.Contains(workflowName);
     }
-
-    /// <summary>
-    /// Enables the MCP tool trigger for the specified workflow.
-    /// </summary>
-    internal void EnableMcpToolTrigger(string workflowName)
-    {
-        this._mcpToolTriggerWorkflows.Add(workflowName);
-    }
-
-    /// <summary>
-    /// Returns whether the MCP tool trigger is enabled for the specified workflow.
-    /// </summary>
-    internal bool IsMcpToolTriggerEnabled(string workflowName)
-    {
-        return this._mcpToolTriggerWorkflows.Contains(workflowName);
-    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/Workflows/DurableWorkflowOptionsExtensions.cs

@@ -27,31 +27,4 @@ public static class DurableWorkflowOptionsExtensions
             functionsOptions.EnableStatusEndpoint(workflow.Name!);
         }
     }
-
-    /// <summary>
-    /// Adds a workflow and configures whether to expose a status HTTP endpoint and/or an MCP tool trigger.
-    /// </summary>
-    /// <param name="options">The workflow options to add the workflow to.</param>
-    /// <param name="workflow">The workflow instance to add.</param>
-    /// <param name="exposeStatusEndpoint">If <see langword="true"/>, a GET endpoint is generated at <c>workflows/{name}/status/{runId}</c>.</param>
-    /// <param name="exposeMcpToolTrigger">If <see langword="true"/>, an MCP tool trigger is generated for the workflow.</param>
-    public static void AddWorkflow(this DurableWorkflowOptions options, Workflow workflow, bool exposeStatusEndpoint, bool exposeMcpToolTrigger)
-    {
-        ArgumentNullException.ThrowIfNull(options);
-
-        options.AddWorkflow(workflow);
-
-        if (options.ParentOptions is FunctionsDurableOptions functionsOptions)
-        {
-            if (exposeStatusEndpoint)
-            {
-                functionsOptions.EnableStatusEndpoint(workflow.Name!);
-            }
-
-            if (exposeMcpToolTrigger)
-            {
-                functionsOptions.EnableMcpToolTrigger(workflow.Name!);
-            }
-        }
-    }
 }

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/Workflows/DurableWorkflowsFunctionMetadataTransformer.cs

@@ -50,11 +50,8 @@ internal sealed class DurableWorkflowsFunctionMetadataTransformer : IFunctionMet
         int initialCount = original.Count;
         this._logger.LogTransformingFunctionMetadata(initialCount);
 
-        // Seed with existing function names to avoid duplicates across transformers
-        // (e.g., when DurableAgentFunctionMetadataTransformer already registered entity triggers).
-        HashSet<string> registeredFunctions = new(
-            original.Select(f => f.Name!),
-            StringComparer.OrdinalIgnoreCase);
+        // Track registered function names to avoid duplicates when workflows share executors.
+        HashSet<string> registeredFunctions = [];
 
         DurableWorkflowOptions workflowOptions = this._options.Workflows;
         foreach (var workflow in workflowOptions.Workflows)
@@ -116,17 +113,6 @@ internal sealed class DurableWorkflowsFunctionMetadataTransformer : IFunctionMet
                 }
             }
 
-            // Register an MCP tool trigger if opted in via AddWorkflow(exposeMcpToolTrigger: true).
-            if (this._options.IsMcpToolTriggerEnabled(workflow.Key))
-            {
-                string mcpToolFunctionName = $"{BuiltInFunctions.McpToolPrefix}{workflow.Key}";
-                if (registeredFunctions.Add(mcpToolFunctionName))
-                {
-                    this._logger.LogRegisteringWorkflowTrigger(workflow.Key, mcpToolFunctionName, "mcpTool");
-                    original.Add(FunctionMetadataFactory.CreateWorkflowMcpToolTrigger(workflow.Key, workflow.Value.Description));
-                }
-            }
-
             // Register activity or entity functions for each executor in the workflow.
             // ReflectExecutors() returns all executors across the graph; no need to manually traverse edges.
             foreach (KeyValuePair<string, ExecutorBinding> entry in workflow.Value.ReflectExecutors())

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/ChatCompletions/Models/ChatCompletionRequestMessage.cs

@@ -39,16 +39,14 @@ internal abstract record ChatCompletionRequestMessage
     /// <exception cref="InvalidOperationException">Thrown when the content is neither text nor AI contents.</exception>
     public virtual ChatMessage ToChatMessage()
     {
-        var role = new ChatRole(this.Role);
-
         if (this.Content.IsText)
         {
-            return new(role, this.Content.Text);
+            return new(ChatRole.User, this.Content.Text);
         }
         else if (this.Content.IsContents)
         {
             var aiContents = this.Content.Contents.Select(MessageContentPartConverter.ToAIContent).Where(c => c is not null).ToList();
-            return new ChatMessage(role, aiContents!);
+            return new ChatMessage(ChatRole.User, aiContents!);
         }
 
         throw new InvalidOperationException("MessageContent has no value");
@@ -167,11 +165,9 @@ internal sealed record FunctionMessage : ChatCompletionRequestMessage
     /// <exception cref="InvalidOperationException">Thrown when the content is not text.</exception>
     public override ChatMessage ToChatMessage()
     {
-        var role = new ChatRole(this.Role);
-
         if (this.Content.IsText)
         {
-            return new(role, this.Content.Text);
+            return new(ChatRole.User, this.Content.Text);
         }
 
         throw new InvalidOperationException("FunctionMessage Content must be text");

dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIResponseClientExtensions.cs

@@ -105,7 +105,7 @@ public static class OpenAIResponseClientExtensions
     /// This corresponds to setting the "store" property in the JSON representation to false.
     /// </remarks>
     /// <param name="responseClient">The client.</param>
-    /// <param name="model">Optional default model ID to use for requests.</param>
+    /// <param name="model">Optional default model ID to use for requests. Required when using a plain <see cref="ResponsesClient"/> (not via Azure OpenAI).</param>
     /// <param name="includeReasoningEncryptedContent">
     /// Includes an encrypted version of reasoning tokens in reasoning item outputs.
     /// This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Generation/SourceBuilder.cs

@@ -38,7 +38,6 @@ internal static class SourceBuilder
         sb.AppendLine("using System.Collections.Generic;");
         sb.AppendLine("using Microsoft.Agents.AI.Workflows;");
         sb.AppendLine();
-        sb.AppendLine("using RouteBuilder = Microsoft.Agents.AI.Workflows.RouteBuilder;");
 
         // Namespace
         if (!string.IsNullOrWhiteSpace(info.Namespace))

dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs

@@ -145,7 +145,7 @@ public static partial class AgentWorkflowBuilder
         return builder.Build();
     }
 
-    /// <summary>Creates a new <see cref="HandoffWorkflowBuilder"/> using <paramref name="initialAgent"/> as the starting agent in the workflow.</summary>
+    /// <summary>Creates a new <see cref="HandoffsWorkflowBuilder"/> using <paramref name="initialAgent"/> as the starting agent in the workflow.</summary>
     /// <param name="initialAgent">The agent that will receive inputs provided to the workflow.</param>
     /// <returns>The builder for creating a workflow based on handoffs.</returns>
     /// <remarks>
@@ -154,7 +154,7 @@ public static partial class AgentWorkflowBuilder
     /// The <see cref="AIAgent"/> must be capable of understanding those <see cref="AgentRunOptions"/> provided. If the agent
     /// ignores the tools or is otherwise unable to advertize them to the underlying provider, handoffs will not occur.
     /// </remarks>
-    public static HandoffWorkflowBuilder CreateHandoffBuilderWith(AIAgent initialAgent)
+    public static HandoffsWorkflowBuilder CreateHandoffBuilderWith(AIAgent initialAgent)
     {
         Throw.IfNull(initialAgent);
         return new(initialAgent);

dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/FileSystemJsonCheckpointStore.cs

@@ -5,14 +5,11 @@ using System.Collections.Generic;
 using System.IO;
 using System.Text;
 using System.Text.Json;
-using System.Text.Json.Serialization.Metadata;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace Microsoft.Agents.AI.Workflows.Checkpointing;
 
-internal record CheckpointFileIndexEntry(CheckpointInfo CheckpointInfo, string FileName);
-
 /// <summary>
 /// Provides a file system-based implementation of a JSON checkpoint store that persists checkpoint data and index
 /// information to disk using JSON files.
@@ -31,8 +28,6 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
     internal DirectoryInfo Directory { get; }
     internal HashSet<CheckpointInfo> CheckpointIndex { get; }
 
-    private static JsonTypeInfo<CheckpointFileIndexEntry> EntryTypeInfo => WorkflowsJsonUtilities.JsonContext.Default.CheckpointFileIndexEntry;
-
     /// <summary>
     /// Initializes a new instance of the <see cref="FileSystemJsonCheckpointStore"/> class that uses the specified directory
     /// </summary>
@@ -69,11 +64,9 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
             using StreamReader reader = new(this._indexFile, encoding: Encoding.UTF8, detectEncodingFromByteOrderMarks: false, BufferSize, leaveOpen: true);
             while (reader.ReadLine() is string line)
             {
-                if (JsonSerializer.Deserialize(line, EntryTypeInfo) is { } entry)
+                if (JsonSerializer.Deserialize(line, KeyTypeInfo) is { } info)
                 {
-                    // We never actually use the file names from the index entries since they can be derived from the CheckpointInfo, but it is useful to
-                    // have the UrlEncoded file names in the index file for human readability
-                    this.CheckpointIndex.Add(entry.CheckpointInfo);
+                    this.CheckpointIndex.Add(info);
                 }
             }
         }
@@ -100,14 +93,8 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
         }
     }
 
-    internal string GetFileNameForCheckpoint(string sessionId, CheckpointInfo key)
-    {
-        string protoPath = $"{sessionId}_{key.CheckpointId}.json";
-
-        // Escape the protoPath to ensure it is a valid file name, especially if sessionId or CheckpointId contain path separators, etc.
-        return Uri.EscapeDataString(protoPath) // This takes care of most of the invalid path characters
-                  .Replace(".", "%2E");        // This takes care of escaping the root folder, since EscapeDataString does not escape dots
-    }
+    private string GetFileNameForCheckpoint(string sessionId, CheckpointInfo key)
+        => Path.Combine(this.Directory.FullName, $"{sessionId}_{key.CheckpointId}.json");
 
     private CheckpointInfo GetUnusedCheckpointInfo(string sessionId)
     {
@@ -129,16 +116,13 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
 
         CheckpointInfo key = this.GetUnusedCheckpointInfo(sessionId);
         string fileName = this.GetFileNameForCheckpoint(sessionId, key);
-        string filePath = Path.Combine(this.Directory.FullName, fileName);
-
         try
         {
-            using Stream checkpointStream = File.Open(filePath, FileMode.Create, FileAccess.Write, FileShare.None);
+            using Stream checkpointStream = File.Open(fileName, FileMode.Create, FileAccess.Write, FileShare.None);
             using Utf8JsonWriter jsonWriter = new(checkpointStream, new JsonWriterOptions() { Indented = false });
             value.WriteTo(jsonWriter);
 
-            CheckpointFileIndexEntry entry = new(key, fileName);
-            JsonSerializer.Serialize(this._indexFile!, entry, EntryTypeInfo);
+            JsonSerializer.Serialize(this._indexFile!, key, KeyTypeInfo);
             byte[] bytes = Encoding.UTF8.GetBytes(Environment.NewLine);
             await this._indexFile!.WriteAsync(bytes, 0, bytes.Length, CancellationToken.None).ConfigureAwait(false);
             await this._indexFile!.FlushAsync(CancellationToken.None).ConfigureAwait(false);
@@ -152,7 +136,7 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
             try
             {
                 // try to clean up after ourselves
-                File.Delete(filePath);
+                File.Delete(fileName);
             }
             catch { }
 
@@ -165,7 +149,6 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
     {
         this.CheckDisposed();
         string fileName = this.GetFileNameForCheckpoint(sessionId, key);
-        string filePath = Path.Combine(this.Directory.FullName, fileName);
 
         if (!this.CheckpointIndex.Contains(key) ||
             !File.Exists(fileName))
@@ -173,7 +156,7 @@ public sealed class FileSystemJsonCheckpointStore : JsonCheckpointStore, IDispos
             throw new KeyNotFoundException($"Checkpoint '{key.CheckpointId}' not found in store at '{this.Directory.FullName}'.");
         }
 
-        using FileStream checkpointFileStream = File.Open(filePath, FileMode.Open, FileAccess.Read, FileShare.Read);
+        using FileStream checkpointFileStream = File.Open(fileName, FileMode.Open, FileAccess.Read, FileShare.Read);
         using JsonDocument document = await JsonDocument.ParseAsync(checkpointFileStream).ConfigureAwait(false);
 
         return document.RootElement.Clone();

dotnet/src/Microsoft.Agents.AI.Workflows/Config.cs

@@ -6,7 +6,7 @@ namespace Microsoft.Agents.AI.Workflows;
 /// Represents a configuration for an object with a string identifier. For example, <see cref="IIdentified"/> object.
 /// </summary>
 /// <param name="id">A unique identifier for the configurable object.</param>
-public class ExecutorConfig(string id)
+public class Config(string id)
 {
     /// <summary>
     /// Gets a unique identifier for the configurable object.
@@ -23,7 +23,7 @@ public class ExecutorConfig(string id)
 /// <typeparam name="TOptions">The type of options for the configurable object.</typeparam>
 /// <param name="id">A unique identifier for the configurable object.</param>
 /// <param name="options">The options for the configurable object.</param>
-public class ExecutorConfig<TOptions>(string id, TOptions? options = default) : ExecutorConfig(id)
+public class Config<TOptions>(string id, TOptions? options = default) : Config(id)
 {
     /// <summary>
     /// Gets the options for the configured object.

dotnet/src/Microsoft.Agents.AI.Workflows/ConfigurationExtensions.cs

@@ -3,9 +3,9 @@
 namespace Microsoft.Agents.AI.Workflows;
 
 /// <summary>
-/// Provides extension methods for creating <see cref="Configured{TSubject}"/> objects
+/// Provides extensions methods for creating <see cref="Configured{TSubject}"/> objects
 /// </summary>
-internal static class ConfigurationExtensions
+public static class ConfigurationExtensions
 {
     /// <summary>
     /// Creates a new configuration that treats the subject as its base type, allowing configuration to be applied at

dotnet/src/Microsoft.Agents.AI.Workflows/Configured.cs

@@ -8,7 +8,7 @@ namespace Microsoft.Agents.AI.Workflows;
 /// <summary>
 /// Provides methods for creating <see cref="Configured{TSubject}"/> instances.
 /// </summary>
-internal static class Configured
+public static class Configured
 {
     /// <summary>
     /// Creates a <see cref="Configured{TSubject}"/> instance from an existing subject instance.
@@ -50,10 +50,10 @@ internal static class Configured
 /// A representation of a preconfigured, lazy-instantiatable instance of <typeparamref name="TSubject"/>.
 /// </summary>
 /// <typeparam name="TSubject">The type of the preconfigured subject.</typeparam>
-/// <param name="factoryAsync">A factory to instantiate the subject when desired.</param>
+/// <param name="factoryAsync">A factory to intantiate the subject when desired.</param>
 /// <param name="id">The unique identifier for the configured subject.</param>
 /// <param name="raw"></param>
-internal class Configured<TSubject>(Func<ExecutorConfig, string, ValueTask<TSubject>> factoryAsync, string id, object? raw = null)
+public class Configured<TSubject>(Func<Config, string, ValueTask<TSubject>> factoryAsync, string id, object? raw = null)
 {
     /// <summary>
     /// Gets the raw representation of the configured object, if any.
@@ -66,14 +66,14 @@ internal class Configured<TSubject>(Func<ExecutorConfig, string, ValueTask<TSubj
     public string Id => id;
 
     /// <summary>
-    /// Gets the factory function to create an instance of <typeparamref name="TSubject"/> given a <see cref="ExecutorConfig"/>.
+    /// Gets the factory function to create an instance of <typeparamref name="TSubject"/> given a <see cref="Config"/>.
     /// </summary>
-    public Func<ExecutorConfig, string, ValueTask<TSubject>> FactoryAsync => factoryAsync;
+    public Func<Config, string, ValueTask<TSubject>> FactoryAsync => factoryAsync;
 
     /// <summary>
     /// The configuration for this configured instance.
     /// </summary>
-    public ExecutorConfig Configuration => new(this.Id);
+    public Config Configuration => new(this.Id);
 
     /// <summary>
     /// Gets a "partially" applied factory function that only requires no parameters to create an instance of
@@ -87,11 +87,11 @@ internal class Configured<TSubject>(Func<ExecutorConfig, string, ValueTask<TSubj
 /// </summary>
 /// <typeparam name="TSubject">The type of the preconfigured subject.</typeparam>
 /// <typeparam name="TOptions">The type of configuration options for the preconfigured subject.</typeparam>
-/// <param name="factoryAsync">A factory to instantiate the subject when desired.</param>
+/// <param name="factoryAsync">A factory to intantiate the subject when desired.</param>
 /// <param name="id">The unique identifier for the configured subject.</param>
 /// <param name="options">Additional configuration options for the subject.</param>
 /// <param name="raw"></param>
-internal class Configured<TSubject, TOptions>(Func<ExecutorConfig<TOptions>, string, ValueTask<TSubject>> factoryAsync, string id, TOptions? options = default, object? raw = null)
+public class Configured<TSubject, TOptions>(Func<Config<TOptions>, string, ValueTask<TSubject>> factoryAsync, string id, TOptions? options = default, object? raw = null)
 {
     /// <summary>
     /// The raw representation of the configured object, if any.
@@ -109,14 +109,14 @@ internal class Configured<TSubject, TOptions>(Func<ExecutorConfig<TOptions>, str
     public TOptions? Options => options;
 
     /// <summary>
-    /// Gets the factory function to create an instance of <typeparamref name="TSubject"/> given a <see cref="ExecutorConfig{TOptions}"/>.
+    /// Gets the factory function to create an instance of <typeparamref name="TSubject"/> given a <see cref="Config{TOptions}"/>.
     /// </summary>
-    public Func<ExecutorConfig<TOptions>, string, ValueTask<TSubject>> FactoryAsync => factoryAsync;
+    public Func<Config<TOptions>, string, ValueTask<TSubject>> FactoryAsync => factoryAsync;
 
     /// <summary>
     /// The configuration for this configured instance.
     /// </summary>
-    public ExecutorConfig<TOptions> Configuration => new(this.Id, this.Options);
+    public Config<TOptions> Configuration => new(this.Id, this.Options);
 
     /// <summary>
     /// Gets a "partially" applied factory function that only requires no parameters to create an instance of
@@ -124,11 +124,11 @@ internal class Configured<TSubject, TOptions>(Func<ExecutorConfig<TOptions>, str
     /// </summary>
     internal Func<string, ValueTask<TSubject>> BoundFactoryAsync => (sessionId) => this.CreateValidatingMemoizedFactory()(this.Configuration, sessionId);
 
-    private Func<ExecutorConfig, string, ValueTask<TSubject>> CreateValidatingMemoizedFactory()
+    private Func<Config, string, ValueTask<TSubject>> CreateValidatingMemoizedFactory()
     {
         return FactoryAsync;
 
-        async ValueTask<TSubject> FactoryAsync(ExecutorConfig configuration, string sessionId)
+        async ValueTask<TSubject> FactoryAsync(Config configuration, string sessionId)
         {
             if (this.Id != configuration.Id)
             {

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/AsyncRunHandle.cs

@@ -53,9 +53,6 @@ internal sealed class AsyncRunHandle : ICheckpointingHandle, IAsyncDisposable
     public ValueTask<RunStatus> GetStatusAsync(CancellationToken cancellationToken = default)
         => this._eventStream.GetStatusAsync(cancellationToken);
 
-    internal bool TryGetResponsePortExecutorId(string portId, out string? executorId)
-        => this._stepRunner.TryGetResponsePortExecutorId(portId, out executorId);
-
     public async IAsyncEnumerable<WorkflowEvent> TakeEventStreamAsync(bool blockOnPendingRequest, [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         //Debug.Assert(breakOnHalt);

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/EdgeMap.cs

@@ -3,7 +3,6 @@
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
@@ -96,18 +95,6 @@ internal sealed class EdgeMap
         return portRunner.ChaseEdgeAsync(new MessageEnvelope(response, ExecutorIdentity.None), this._stepTracer, cancellationToken);
     }
 
-    internal bool TryGetResponsePortExecutorId(string portId, [NotNullWhen(true)] out string? executorId)
-    {
-        if (this._portEdgeRunners.TryGetValue(portId, out ResponseEdgeRunner? portRunner))
-        {
-            executorId = portRunner.ExecutorId;
-            return true;
-        }
-
-        executorId = null;
-        return false;
-    }
-
     internal async ValueTask<Dictionary<EdgeId, PortableValue>> ExportStateAsync()
     {
         Dictionary<EdgeId, PortableValue> exportedStates = [];

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/ISuperStepRunner.cs

@@ -19,7 +19,6 @@ internal interface ISuperStepRunner
     bool HasUnprocessedMessages { get; }
 
     ValueTask EnqueueResponseAsync(ExternalResponse response, CancellationToken cancellationToken = default);
-    bool TryGetResponsePortExecutorId(string portId, out string? executorId);
 
     ValueTask<bool> IsValidInputTypeAsync<T>(CancellationToken cancellationToken = default);
     ValueTask<bool> EnqueueMessageAsync<T>(T message, CancellationToken cancellationToken = default);

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/StateManager.cs

@@ -106,7 +106,8 @@ internal sealed class StateManager
         if (typeof(T) == typeof(object))
         {
             // Reading as object will break across serialize/deserialize boundaries, e.g. checkpointing, distributed runtime, etc.
-            throw new NotSupportedException("Reading state as 'object' is not supported. Use 'PortableValue' instead for variants.");
+            // Disabled pending upstream updates for this change; see https://github.com/microsoft/agent-framework/issues/1369
+            //throw new NotSupportedException("Reading state as 'object' is not supported. Use 'PortableValue' instead for variants.");
         }
 
         Throw.IfNullOrEmpty(key);

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorBindingExtensions.cs

@@ -113,7 +113,7 @@ public static class ExecutorBindingExtensions
     /// <param name="id">An id for the executor to be instantiated.</param>
     /// <param name="options">An optional parameter specifying the options.</param>
     /// <returns>An <see cref="ExecutorBinding"/> instance that resolves to the result of the factory call when messages get sent to it.</returns>
-    public static ExecutorBinding BindExecutor<TExecutor, TOptions>(this Func<ExecutorConfig<TOptions>, string, ValueTask<TExecutor>> factoryAsync, string id, TOptions? options = null)
+    public static ExecutorBinding BindExecutor<TExecutor, TOptions>(this Func<Config<TOptions>, string, ValueTask<TExecutor>> factoryAsync, string id, TOptions? options = null)
         where TExecutor : Executor
         where TOptions : ExecutorOptions
     {
@@ -139,7 +139,7 @@ public static class ExecutorBindingExtensions
     /// <returns>An <see cref="ExecutorBinding"/> instance that resolves to the result of the factory call when messages get sent to it.</returns>
     [Obsolete("Use BindExecutor() instead")]
     [EditorBrowsable(EditorBrowsableState.Never)]
-    public static ExecutorBinding ConfigureFactory<TExecutor, TOptions>(this Func<ExecutorConfig<TOptions>, string, ValueTask<TExecutor>> factoryAsync, string id, TOptions? options = null)
+    public static ExecutorBinding ConfigureFactory<TExecutor, TOptions>(this Func<Config<TOptions>, string, ValueTask<TExecutor>> factoryAsync, string id, TOptions? options = null)
         where TExecutor : Executor
         where TOptions : ExecutorOptions
         => factoryAsync.BindExecutor(id, options);

dotnet/src/Microsoft.Agents.AI.Workflows/HandoffsWorkflowBuilder.cs

@@ -1,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System;
 using System.Collections.Generic;
 using System.Linq;
 using Microsoft.Agents.AI.Workflows.Specialized;
@@ -9,42 +8,22 @@ using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI.Workflows;
 
-/// <inheritdoc/>
-[Obsolete("Prefer HandoffWorkflowBuilder (no 's') instead, which has the same API but the preferred name. This will be removed in a future release before GA.")]
-public sealed class HandoffsWorkflowBuilder(AIAgent initialAgent) : HandoffWorkflowBuilderCore<HandoffsWorkflowBuilder>(initialAgent)
-{
-}
-
-/// <inheritdoc/>
-public sealed class HandoffWorkflowBuilder(AIAgent initialAgent) : HandoffWorkflowBuilderCore<HandoffWorkflowBuilder>(initialAgent)
-{
-}
-
 /// <summary>
 /// Provides a builder for specifying the handoff relationships between agents and building the resulting workflow.
 /// </summary>
-public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkflowBuilderCore<TBuilder>
+public sealed class HandoffsWorkflowBuilder
 {
-    /// <summary>
-    /// The prefix for function calls that trigger handoffs to other agents; the full name is then `{FunctionPrefix}&lt;agent_id&gt;`,
-    /// where `&lt;agent_id&gt;` is the ID of the target agent to hand off to.
-    /// </summary>
-    public const string FunctionPrefix = "handoff_to_";
-
+    internal const string FunctionPrefix = "handoff_to_";
     private readonly AIAgent _initialAgent;
     private readonly Dictionary<AIAgent, HashSet<HandoffTarget>> _targets = [];
     private readonly HashSet<AIAgent> _allAgents = new(AIAgentIDEqualityComparer.Instance);
-
-    private bool _emitAgentResponseEvents;
-    private bool _emitAgentResponseUpdateEvents;
     private HandoffToolCallFilteringBehavior _toolCallFilteringBehavior = HandoffToolCallFilteringBehavior.HandoffOnly;
-    private bool _returnToPrevious;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HandoffsWorkflowBuilder"/> class with no handoff relationships.
     /// </summary>
     /// <param name="initialAgent">The first agent to be invoked (prior to any handoff).</param>
-    internal HandoffWorkflowBuilderCore(AIAgent initialAgent)
+    internal HandoffsWorkflowBuilder(AIAgent initialAgent)
     {
         this._initialAgent = initialAgent;
         this._allAgents.Add(initialAgent);
@@ -68,41 +47,14 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
               """;
 
     /// <summary>
-    /// Sets instructions to provide to each agent that has handoffs about how and when to perform them.
+    /// Sets additional instructions to provide to an agent that has handoffs about how and when to
+    /// perform them.
     /// </summary>
-    /// <remarks>
-    /// In the vast majority of cases, the <see cref="DefaultHandoffInstructions"/> will be sufficient, and there will be no need to customize.
-    /// If you do provide alternate instructions, remember to explain the mechanics of the handoff function tool call, using see
-    /// <see cref="FunctionPrefix"/> constant.
-    /// </remarks>
     /// <param name="instructions">The instructions to provide, or <see langword="null"/> to restore the default instructions.</param>
-    public TBuilder WithHandoffInstructions(string? instructions)
+    public HandoffsWorkflowBuilder WithHandoffInstructions(string? instructions)
     {
         this.HandoffInstructions = instructions ?? DefaultHandoffInstructions;
-        return (TBuilder)this;
-    }
-
-    /// <summary>
-    /// Sets a value indicating whether agent streaming update events should be emitted during execution.
-    /// If <see langword="null"/>, the value will be taken from the <see cref="TurnToken"/>
-    /// </summary>
-    /// <param name="emitAgentResponseUpdateEvents"></param>
-    /// <returns></returns>
-    public TBuilder EmitAgentResponseUpdateEvents(bool emitAgentResponseUpdateEvents = true)
-    {
-        this._emitAgentResponseUpdateEvents = emitAgentResponseUpdateEvents;
-        return (TBuilder)this;
-    }
-
-    /// <summary>
-    /// Sets a value indicating whether aggregated agent response events should be emitted during execution.
-    /// </summary>
-    /// <param name="emitAgentResponseEvents"></param>
-    /// <returns></returns>
-    public TBuilder EmitAgentResponseEvents(bool emitAgentResponseEvents = true)
-    {
-        this._emitAgentResponseEvents = emitAgentResponseEvents;
-        return (TBuilder)this;
+        return this;
     }
 
     /// <summary>
@@ -110,21 +62,10 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
     /// <see cref="ChatMessage"/>s flowing through the handoff workflow. Defaults to <see cref="HandoffToolCallFilteringBehavior.HandoffOnly"/>.
     /// </summary>
     /// <param name="behavior">The filtering behavior to apply.</param>
-    public TBuilder WithToolCallFilteringBehavior(HandoffToolCallFilteringBehavior behavior)
+    public HandoffsWorkflowBuilder WithToolCallFilteringBehavior(HandoffToolCallFilteringBehavior behavior)
     {
         this._toolCallFilteringBehavior = behavior;
-        return (TBuilder)this;
-    }
-
-    /// <summary>
-    /// Configures the workflow so that subsequent user turns route directly back to the specialist agent
-    /// that handled the previous turn, rather than always routing through the initial (coordinator) agent.
-    /// </summary>
-    /// <returns>The updated <see cref="HandoffsWorkflowBuilder"/> instance.</returns>
-    public TBuilder EnableReturnToPrevious()
-    {
-        this._returnToPrevious = true;
-        return (TBuilder)this;
+        return this;
     }
 
     /// <summary>
@@ -134,7 +75,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
     /// <param name="to">The target agents to add as handoff targets for the source agent.</param>
     /// <returns>The updated <see cref="HandoffsWorkflowBuilder"/> instance.</returns>
     /// <remarks>The handoff reason for each target in <paramref name="to"/> is derived from that agent's description or name.</remarks>
-    public TBuilder WithHandoffs(AIAgent from, IEnumerable<AIAgent> to)
+    public HandoffsWorkflowBuilder WithHandoffs(AIAgent from, IEnumerable<AIAgent> to)
     {
         Throw.IfNull(from);
         Throw.IfNull(to);
@@ -149,7 +90,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
             this.WithHandoff(from, target);
         }
 
-        return (TBuilder)this;
+        return this;
     }
 
     /// <summary>
@@ -162,7 +103,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
     /// If <see langword="null"/>, the reason is derived from <paramref name="to"/>'s description or name.
     /// </param>
     /// <returns>The updated <see cref="HandoffsWorkflowBuilder"/> instance.</returns>
-    public TBuilder WithHandoffs(IEnumerable<AIAgent> from, AIAgent to, string? handoffReason = null)
+    public HandoffsWorkflowBuilder WithHandoffs(IEnumerable<AIAgent> from, AIAgent to, string? handoffReason = null)
     {
         Throw.IfNull(from);
         Throw.IfNull(to);
@@ -177,7 +118,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
             this.WithHandoff(source, to, handoffReason);
         }
 
-        return (TBuilder)this;
+        return this;
     }
 
     /// <summary>
@@ -190,7 +131,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
     /// If <see langword="null"/>, the reason is derived from <paramref name="to"/>'s description or name.
     /// </param>
     /// <returns>The updated <see cref="HandoffsWorkflowBuilder"/> instance.</returns>
-    public TBuilder WithHandoff(AIAgent from, AIAgent to, string? handoffReason = null)
+    public HandoffsWorkflowBuilder WithHandoff(AIAgent from, AIAgent to, string? handoffReason = null)
     {
         Throw.IfNull(from);
         Throw.IfNull(to);
@@ -220,7 +161,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
             Throw.InvalidOperationException($"A handoff from agent '{from.Name ?? from.Id}' to agent '{to.Name ?? to.Id}' has already been registered.");
         }
 
-        return (TBuilder)this;
+        return this;
     }
 
     /// <summary>
@@ -230,40 +171,17 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
     /// <returns>The workflow built based on the handoffs in the builder.</returns>
     public Workflow Build()
     {
-        HandoffsStartExecutor start = new(this._returnToPrevious);
-        HandoffsEndExecutor end = new(this._returnToPrevious);
+        HandoffsStartExecutor start = new();
+        HandoffsEndExecutor end = new();
         WorkflowBuilder builder = new(start);
 
-        HandoffAgentExecutorOptions options = new(this.HandoffInstructions,
-                                                  this._emitAgentResponseEvents,
-                                                  this._emitAgentResponseUpdateEvents,
-                                                  this._toolCallFilteringBehavior);
+        HandoffAgentExecutorOptions options = new(this.HandoffInstructions, this._toolCallFilteringBehavior);
 
-        // Create an AgentExecutor for each agent.
+        // Create an AgentExecutor for each again.
         Dictionary<string, HandoffAgentExecutor> executors = this._allAgents.ToDictionary(a => a.Id, a => new HandoffAgentExecutor(a, options));
 
-        // Connect the start executor to the initial agent (or use dynamic routing when ReturnToPrevious is enabled).
-        if (this._returnToPrevious)
-        {
-            string initialAgentId = this._initialAgent.Id;
-            builder.AddSwitch(start, sb =>
-            {
-                foreach (var agent in this._allAgents)
-                {
-                    if (agent.Id != initialAgentId)
-                    {
-                        string agentId = agent.Id;
-                        sb.AddCase<HandoffState>(state => state?.CurrentAgentId == agentId, executors[agentId]);
-                    }
-                }
-
-                sb.WithDefault(executors[initialAgentId]);
-            });
-        }
-        else
-        {
-            builder.AddEdge(start, executors[this._initialAgent.Id]);
-        }
+        // Connect the start executor to the initial agent.
+        builder.AddEdge(start, executors[this._initialAgent.Id]);
 
         // Initialize each executor with its handoff targets to the other executors.
         foreach (var agent in this._allAgents)

dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunner.cs

@@ -160,8 +160,6 @@ internal sealed class InProcessRunner : ISuperStepRunner, ICheckpointingHandle
 
     bool ISuperStepRunner.HasUnservicedRequests => this.RunContext.HasUnservicedRequests;
     bool ISuperStepRunner.HasUnprocessedMessages => this.RunContext.NextStepHasActions;
-    bool ISuperStepRunner.TryGetResponsePortExecutorId(string portId, out string? executorId)
-        => this.RunContext.TryGetResponsePortExecutorId(portId, out executorId);
 
     public bool IsCheckpointingEnabled => this.RunContext.IsCheckpointingEnabled;
 

dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunnerContext.cs

@@ -296,9 +296,6 @@ internal sealed class InProcessRunnerContext : IRunnerContext
         return this._externalRequests.TryRemove(requestId, out _);
     }
 
-    internal bool TryGetResponsePortExecutorId(string portId, [NotNullWhen(true)] out string? executorId)
-        => this._edgeMap.TryGetResponsePortExecutorId(portId, out executorId);
-
     private IEventSink OutgoingEvents { get; }
 
     internal StateManager StateManager { get; } = new();

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/AIAgentHostExecutor.cs

@@ -12,15 +12,6 @@ namespace Microsoft.Agents.AI.Workflows.Specialized;
 
 internal record AIAgentHostState(JsonElement? ThreadState, bool? CurrentTurnEmitEvents);
 
-internal static class TurnExtensions
-{
-    public static bool ShouldEmitStreamingEvents(this TurnToken token, bool? agentSetting)
-        => token.EmitEvents ?? agentSetting ?? false;
-
-    public static bool ShouldEmitStreamingEvents(bool? turnTokenSetting, bool? agentSetting)
-        => turnTokenSetting ?? agentSetting ?? false;
-}
-
 internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
 {
     private readonly AIAgent _agent;
@@ -77,17 +68,10 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
             throw new InvalidOperationException($"No pending ToolApprovalRequest found with id '{response.RequestId}'.");
         }
 
-        // Merge the external response with any already-buffered regular messages so mixed-content
-        // resumes can be processed in one invocation.
-        return this.ProcessTurnMessagesAsync(async (pendingMessages, ctx, ct) =>
-        {
-            pendingMessages.Add(new ChatMessage(ChatRole.User, [response]));
+        List<ChatMessage> implicitTurnMessages = [new ChatMessage(ChatRole.User, [response])];
 
-            await this.ContinueTurnAsync(pendingMessages, ctx, this._currentTurnEmitEvents ?? false, ct).ConfigureAwait(false);
-
-            // Clear the buffered turn messages because they were consumed by ContinueTurnAsync.
-            return null;
-        }, context, cancellationToken);
+        // ContinueTurnAsync owns failing to emit a TurnToken if this response does not clear up all remaining outstanding requests.
+        return this.ContinueTurnAsync(implicitTurnMessages, context, this._currentTurnEmitEvents ?? false, cancellationToken);
     }
 
     private ValueTask HandleFunctionResultAsync(
@@ -100,19 +84,13 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
             throw new InvalidOperationException($"No pending FunctionCall found with id '{result.CallId}'.");
         }
 
-        // Merge the external response with any already-buffered regular messages so mixed-content
-        // resumes can be processed in one invocation.
-        return this.ProcessTurnMessagesAsync(async (pendingMessages, ctx, ct) =>
-        {
-            pendingMessages.Add(new ChatMessage(ChatRole.Tool, [result]));
-
-            await this.ContinueTurnAsync(pendingMessages, ctx, this._currentTurnEmitEvents ?? false, ct).ConfigureAwait(false);
-
-            // Clear the buffered turn messages because they were consumed by ContinueTurnAsync.
-            return null;
-        }, context, cancellationToken);
+        List<ChatMessage> implicitTurnMessages = [new ChatMessage(ChatRole.Tool, [result])];
+        return this.ContinueTurnAsync(implicitTurnMessages, context, this._currentTurnEmitEvents ?? false, cancellationToken);
     }
 
+    public bool ShouldEmitStreamingEvents(bool? emitEvents)
+        => emitEvents ?? this._options.EmitAgentUpdateEvents ?? false;
+
     private async ValueTask<AgentSession> EnsureSessionAsync(IWorkflowContext context, CancellationToken cancellationToken) =>
         this._session ??= await this._agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
 
@@ -181,10 +159,7 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
     }
 
     protected override ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
-        => this.ContinueTurnAsync(messages,
-                                  context,
-                                  TurnExtensions.ShouldEmitStreamingEvents(turnTokenSetting: emitEvents, this._options.EmitAgentUpdateEvents),
-                                  cancellationToken);
+        => this.ContinueTurnAsync(messages, context, this.ShouldEmitStreamingEvents(emitEvents), cancellationToken);
 
     private async ValueTask<AgentResponse> InvokeAgentAsync(IEnumerable<ChatMessage> messages, IWorkflowContext context, bool emitEvents, CancellationToken cancellationToken = default)
     {
@@ -223,7 +198,7 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
             ExtractUnservicedRequests(response.Messages.SelectMany(message => message.Contents));
         }
 
-        if (this._options.EmitAgentResponseEvents)
+        if (this._options.EmitAgentResponseEvents == true)
         {
             await context.YieldOutputAsync(response, cancellationToken).ConfigureAwait(false);
         }

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/AIContentExternalHandler.cs

@@ -16,12 +16,10 @@ internal sealed class AIContentExternalHandler<TRequestContent, TResponseContent
     where TResponseContent : AIContent
 {
     private readonly PortBinding? _portBinding;
-    private readonly string _portId;
     private ConcurrentDictionary<string, TRequestContent> _pendingRequests = new();
 
     public AIContentExternalHandler(ref ProtocolBuilder protocolBuilder, string portId, bool intercepted, Func<TResponseContent, IWorkflowContext, CancellationToken, ValueTask> handler)
     {
-        this._portId = portId;
         PortBinding? portBinding = null;
         protocolBuilder = protocolBuilder.ConfigureRoutes(routeBuilder => ConfigureRoutes(routeBuilder, out portBinding));
         this._portBinding = portBinding;
@@ -60,14 +58,12 @@ internal sealed class AIContentExternalHandler<TRequestContent, TResponseContent
     {
         if (!this._pendingRequests.TryAdd(id, requestContent))
         {
-            // Request is already pending; treat as an idempotent re-emission.
-            // Do not repost to the sink because request IDs must remain unique while pending.
-            return default;
+            throw new InvalidOperationException($"A pending request with ID '{id}' already exists.");
         }
 
         return this.IsIntercepted
              ? context.SendMessageAsync(requestContent, cancellationToken: cancellationToken)
-             : this._portBinding.PostRequestAsync(requestContent, this.CreateExternalRequestId(id), cancellationToken);
+             : this._portBinding.PostRequestAsync(requestContent, id, cancellationToken);
     }
 
     public bool MarkRequestAsHandled(string id)
@@ -78,8 +74,6 @@ internal sealed class AIContentExternalHandler<TRequestContent, TResponseContent
     [MemberNotNullWhen(false, nameof(_portBinding))]
     private bool IsIntercepted => this._portBinding == null;
 
-    private string CreateExternalRequestId(string requestId) => $"{this._portId.Length}:{this._portId}:{requestId}";
-
     private static string MakeKey(string id) => $"{id}_PendingRequests";
 
     public async ValueTask OnCheckpointingAsync(string id, IWorkflowContext context, CancellationToken cancellationToken = default)

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs

@@ -14,20 +14,14 @@ namespace Microsoft.Agents.AI.Workflows.Specialized;
 
 internal sealed class HandoffAgentExecutorOptions
 {
-    public HandoffAgentExecutorOptions(string? handoffInstructions, bool emitAgentResponseEvents, bool? emitAgentResponseUpdateEvents, HandoffToolCallFilteringBehavior toolCallFilteringBehavior)
+    public HandoffAgentExecutorOptions(string? handoffInstructions, HandoffToolCallFilteringBehavior toolCallFilteringBehavior)
     {
         this.HandoffInstructions = handoffInstructions;
-        this.EmitAgentResponseEvents = emitAgentResponseEvents;
-        this.EmitAgentResponseUpdateEvents = emitAgentResponseUpdateEvents;
         this.ToolCallFilteringBehavior = toolCallFilteringBehavior;
     }
 
     public string? HandoffInstructions { get; set; }
 
-    public bool EmitAgentResponseEvents { get; set; }
-
-    public bool? EmitAgentResponseUpdateEvents { get; set; }
-
     public HandoffToolCallFilteringBehavior ToolCallFilteringBehavior { get; set; } = HandoffToolCallFilteringBehavior.HandoffOnly;
 }
 
@@ -42,7 +36,7 @@ internal sealed class HandoffMessagesFilter
 
     internal static bool IsHandoffFunctionName(string name)
     {
-        return name.StartsWith(HandoffWorkflowBuilder.FunctionPrefix, StringComparison.Ordinal);
+        return name.StartsWith(HandoffsWorkflowBuilder.FunctionPrefix, StringComparison.Ordinal);
     }
 
     public IEnumerable<ChatMessage> FilterMessages(List<ChatMessage> messages)
@@ -173,7 +167,6 @@ internal sealed class HandoffAgentExecutor(
 
     private readonly AIAgent _agent = agent;
     private readonly HashSet<string> _handoffFunctionNames = [];
-    private readonly Dictionary<string, string> _handoffFunctionToAgentId = [];
     private ChatClientAgentRunOptions? _agentOptions;
 
     public void Initialize(
@@ -200,10 +193,9 @@ internal sealed class HandoffAgentExecutor(
                 foreach (HandoffTarget handoff in handoffs)
                 {
                     index++;
-                    var handoffFunc = AIFunctionFactory.CreateDeclaration($"{HandoffWorkflowBuilder.FunctionPrefix}{index}", handoff.Reason, s_handoffSchema);
+                    var handoffFunc = AIFunctionFactory.CreateDeclaration($"{HandoffsWorkflowBuilder.FunctionPrefix}{index}", handoff.Reason, s_handoffSchema);
 
                     this._handoffFunctionNames.Add(handoffFunc.Name);
-                    this._handoffFunctionToAgentId[handoffFunc.Name] = handoff.Target.Id;
 
                     this._agentOptions.ChatOptions.Tools.Add(handoffFunc);
 
@@ -258,27 +250,16 @@ internal sealed class HandoffAgentExecutor(
             }
         }
 
-        AgentResponse agentResponse = updates.ToAgentResponse();
-
-        if (options.EmitAgentResponseEvents)
-        {
-            await context.YieldOutputAsync(agentResponse, cancellationToken).ConfigureAwait(false);
-        }
-
-        allMessages.AddRange(agentResponse.Messages);
+        allMessages.AddRange(updates.ToAgentResponse().Messages);
 
         roleChanges.ResetUserToAssistantForChangedRoles();
 
-        string currentAgentId = requestedHandoff is not null && this._handoffFunctionToAgentId.TryGetValue(requestedHandoff, out string? targetAgentId)
-            ? targetAgentId
-            : this._agent.Id;
-
-        return new(message.TurnToken, requestedHandoff, allMessages, currentAgentId);
+        return new(message.TurnToken, requestedHandoff, allMessages);
 
         async Task AddUpdateAsync(AgentResponseUpdate update, CancellationToken cancellationToken)
         {
             updates.Add(update);
-            if (message.TurnToken.ShouldEmitStreamingEvents(options.EmitAgentResponseUpdateEvents))
+            if (message.TurnToken.EmitEvents is true)
             {
                 await context.YieldOutputAsync(update, cancellationToken).ConfigureAwait(false);
             }

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffState.cs

@@ -8,5 +8,4 @@ namespace Microsoft.Agents.AI.Workflows.Specialized;
 internal sealed record class HandoffState(
     TurnToken TurnToken,
     string? InvokedHandoff,
-    List<ChatMessage> Messages,
-    string? CurrentAgentId = null);
+    List<ChatMessage> Messages);

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffsEndExecutor.cs

@@ -1,35 +1,20 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Collections.Generic;
-using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.Workflows.Specialized;
 
 /// <summary>Executor used at the end of a handoff workflow to raise a final completed event.</summary>
-internal sealed class HandoffsEndExecutor(bool returnToPrevious) : Executor(ExecutorId, declareCrossRunShareable: true), IResettableExecutor
+internal sealed class HandoffsEndExecutor() : Executor(ExecutorId, declareCrossRunShareable: true), IResettableExecutor
 {
     public const string ExecutorId = "HandoffEnd";
 
     protected override ProtocolBuilder ConfigureProtocol(ProtocolBuilder protocolBuilder) =>
         protocolBuilder.ConfigureRoutes(routeBuilder => routeBuilder.AddHandler<HandoffState>((handoff, context, cancellationToken) =>
-                                            this.HandleAsync(handoff, context, cancellationToken)))
+                                            context.YieldOutputAsync(handoff.Messages, cancellationToken)))
                        .YieldsOutput<List<ChatMessage>>();
 
-    private async ValueTask HandleAsync(HandoffState handoff, IWorkflowContext context, CancellationToken cancellationToken)
-    {
-        if (returnToPrevious)
-        {
-            await context.QueueStateUpdateAsync<string?>(HandoffConstants.CurrentAgentTrackerKey,
-                                                         handoff.CurrentAgentId,
-                                                         HandoffConstants.CurrentAgentTrackerScope,
-                                                         cancellationToken)
-                         .ConfigureAwait(false);
-        }
-
-        await context.YieldOutputAsync(handoff.Messages, cancellationToken).ConfigureAwait(false);
-    }
-
     public ValueTask ResetAsync() => default;
 }

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffsStartExecutor.cs

@@ -7,14 +7,8 @@ using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.Workflows.Specialized;
 
-internal static class HandoffConstants
-{
-    internal const string CurrentAgentTrackerKey = "LastAgentId";
-    internal const string CurrentAgentTrackerScope = "HandoffOrchestration";
-}
-
 /// <summary>Executor used at the start of a handoffs workflow to accumulate messages and emit them as HandoffState upon receiving a turn token.</summary>
-internal sealed class HandoffsStartExecutor(bool returnToPrevious) : ChatProtocolExecutor(ExecutorId, DefaultOptions, declareCrossRunShareable: true), IResettableExecutor
+internal sealed class HandoffsStartExecutor() : ChatProtocolExecutor(ExecutorId, DefaultOptions, declareCrossRunShareable: true), IResettableExecutor
 {
     internal const string ExecutorId = "HandoffStart";
 
@@ -28,25 +22,7 @@ internal sealed class HandoffsStartExecutor(bool returnToPrevious) : ChatProtoco
         base.ConfigureProtocol(protocolBuilder).SendsMessage<HandoffState>();
 
     protected override ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
-    {
-        if (returnToPrevious)
-        {
-            return context.InvokeWithStateAsync(
-                async (string? currentAgentId, IWorkflowContext context, CancellationToken cancellationToken) =>
-                {
-                    HandoffState handoffState = new(new(emitEvents), null, messages, currentAgentId);
-                    await context.SendMessageAsync(handoffState, cancellationToken).ConfigureAwait(false);
-
-                    return currentAgentId;
-                },
-                HandoffConstants.CurrentAgentTrackerKey,
-                HandoffConstants.CurrentAgentTrackerScope,
-                cancellationToken);
-        }
-
-        HandoffState handoff = new(new(emitEvents), null, messages);
-        return context.SendMessageAsync(handoff, cancellationToken);
-    }
+        => context.SendMessageAsync(new HandoffState(new(emitEvents), null, messages), cancellationToken: cancellationToken);
 
     public new ValueTask ResetAsync() => base.ResetAsync();
 }

dotnet/src/Microsoft.Agents.AI.Workflows/StreamingRun.cs

@@ -60,9 +60,6 @@ public sealed class StreamingRun : CheckpointableRunBase, IAsyncDisposable
     internal ValueTask<bool> TrySendMessageUntypedAsync(object message, Type? declaredType = null)
         => this._runHandle.EnqueueMessageUntypedAsync(message, declaredType);
 
-    internal bool TryGetResponsePortExecutorId(string portId, out string? executorId)
-        => this._runHandle.TryGetResponsePortExecutorId(portId, out executorId);
-
     /// <summary>
     /// Asynchronously streams workflow events as they occur during workflow execution.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowChatHistoryProvider.cs

@@ -43,7 +43,7 @@ internal sealed class WorkflowChatHistoryProvider : ChatHistoryProvider
         => this._sessionState.GetOrInitializeState(session).Messages.AddRange(messages);
 
     protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        => new(this._sessionState.GetOrInitializeState(context.Session).Messages.AsReadOnly());
+        => new(this._sessionState.GetOrInitializeState(context.Session).Messages);
 
     protected override ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
     {
@@ -62,12 +62,6 @@ internal sealed class WorkflowChatHistoryProvider : ChatHistoryProvider
         }
     }
 
-    public IEnumerable<ChatMessage> GetAllMessages(AgentSession session)
-    {
-        var state = this._sessionState.GetOrInitializeState(session);
-        return state.Messages.AsReadOnly();
-    }
-
     public void UpdateBookmark(AgentSession session)
     {
         var state = this._sessionState.GetOrInitializeState(session);

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowHostAgent.cs

@@ -119,17 +119,13 @@ internal sealed class WorkflowHostAgent : AIAgent
         MessageMerger merger = new();
 
         await foreach (AgentResponseUpdate update in workflowSession.InvokeStageAsync(cancellationToken)
-                                                                     .ConfigureAwait(false)
-                                                                     .WithCancellation(cancellationToken))
+                                                                      .ConfigureAwait(false)
+                                                                      .WithCancellation(cancellationToken))
         {
             merger.AddUpdate(update);
         }
 
-        AgentResponse response = merger.ComputeMerged(workflowSession.LastResponseId!, this.Id, this.Name);
-        workflowSession.ChatHistoryProvider.AddMessages(workflowSession, response.Messages);
-        workflowSession.ChatHistoryProvider.UpdateBookmark(workflowSession);
-
-        return response;
+        return merger.ComputeMerged(workflowSession.LastResponseId!, this.Id, this.Name);
     }
 
     protected override async
@@ -142,18 +138,11 @@ internal sealed class WorkflowHostAgent : AIAgent
         await this.ValidateWorkflowAsync().ConfigureAwait(false);
 
         WorkflowSession workflowSession = await this.UpdateSessionAsync(messages, session, cancellationToken).ConfigureAwait(false);
-        MessageMerger merger = new();
-
         await foreach (AgentResponseUpdate update in workflowSession.InvokeStageAsync(cancellationToken)
                                                                       .ConfigureAwait(false)
                                                                       .WithCancellation(cancellationToken))
         {
-            merger.AddUpdate(update);
             yield return update;
         }
-
-        AgentResponse response = merger.ComputeMerged(workflowSession.LastResponseId!, this.Id, this.Name);
-        workflowSession.ChatHistoryProvider.AddMessages(workflowSession, response.Messages);
-        workflowSession.ChatHistoryProvider.UpdateBookmark(workflowSession);
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowSession.cs

@@ -25,25 +25,6 @@ internal sealed class WorkflowSession : AgentSession
 
     private InMemoryCheckpointManager? _inMemoryCheckpointManager;
 
-    /// <summary>
-    /// Tracks pending external requests by their workflow-facing request ID.
-    /// This mapping enables converting incoming response content back to <see cref="ExternalResponse"/>
-    /// when resuming a workflow from a checkpoint.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// Entries are added when a <see cref="RequestInfoEvent"/> is received during workflow execution,
-    /// and removed when a matching response is delivered via <see cref="SendMessagesWithResponseConversionAsync"/>.
-    /// </para>
-    /// <para>
-    /// The number of entries is bounded by the number of outstanding external requests in a single workflow run.
-    /// When a session is abandoned, all pending requests are released with the session object.
-    /// Request-level timeouts, if needed, should be implemented in the workflow definition itself
-    /// (e.g., using a timer racing against an external event).
-    /// </para>
-    /// </remarks>
-    private readonly Dictionary<string, ExternalRequest> _pendingRequests = [];
-
     internal static bool VerifyCheckpointingConfiguration(IWorkflowExecutionEnvironment executionEnvironment, [NotNullWhen(true)] out InProcessExecutionEnvironment? inProcEnv)
     {
         inProcEnv = null;
@@ -109,7 +90,6 @@ internal sealed class WorkflowSession : AgentSession
 
         this.LastCheckpoint = sessionState.LastCheckpoint;
         this.StateBag = sessionState.StateBag;
-        this._pendingRequests = sessionState.PendingRequests ?? [];
     }
 
     public CheckpointInfo? LastCheckpoint { get; set; }
@@ -121,8 +101,7 @@ internal sealed class WorkflowSession : AgentSession
             this.SessionId,
             this.LastCheckpoint,
             this._inMemoryCheckpointManager,
-            this.StateBag,
-            this._pendingRequests);
+            this.StateBag);
 
         return marshaller.Marshal(info);
     }
@@ -131,7 +110,7 @@ internal sealed class WorkflowSession : AgentSession
     {
         Throw.IfNullOrEmpty(parts);
 
-        return new(ChatRole.Assistant, parts)
+        AgentResponseUpdate update = new(ChatRole.Assistant, parts)
         {
             CreatedAt = DateTimeOffset.UtcNow,
             MessageId = Guid.NewGuid().ToString("N"),
@@ -139,22 +118,30 @@ internal sealed class WorkflowSession : AgentSession
             ResponseId = responseId,
             RawRepresentation = raw
         };
+
+        this.ChatHistoryProvider.AddMessages(this, update.ToChatMessage());
+
+        return update;
     }
 
     public AgentResponseUpdate CreateUpdate(string responseId, object raw, ChatMessage message)
     {
         Throw.IfNull(message);
 
-        return new(message.Role, message.Contents)
+        AgentResponseUpdate update = new(message.Role, message.Contents)
         {
             CreatedAt = message.CreatedAt ?? DateTimeOffset.UtcNow,
             MessageId = message.MessageId ?? Guid.NewGuid().ToString("N"),
             ResponseId = responseId,
             RawRepresentation = raw
         };
+
+        this.ChatHistoryProvider.AddMessages(this, update.ToChatMessage());
+
+        return update;
     }
 
-    private async ValueTask<ResumeRunResult> CreateOrResumeRunAsync(List<ChatMessage> messages, CancellationToken cancellationToken = default)
+    private async ValueTask<StreamingRun> CreateOrResumeRunAsync(List<ChatMessage> messages, CancellationToken cancellationToken = default)
     {
         // The workflow is validated to be a ChatProtocol workflow by the WorkflowHostAgent before creating the session,
         // and does not need to be checked again here.
@@ -167,258 +154,110 @@ internal sealed class WorkflowSession : AgentSession
                                                cancellationToken)
                             .ConfigureAwait(false);
 
-            // Process messages: convert response content to ExternalResponse, send regular messages as-is
-            ResumeDispatchInfo dispatchInfo = await this.SendMessagesWithResponseConversionAsync(run, messages).ConfigureAwait(false);
-            return new ResumeRunResult(run, dispatchInfo);
+            await run.TrySendMessageAsync(messages).ConfigureAwait(false);
+            return run;
         }
 
-        StreamingRun newRun = await this._executionEnvironment
+        return await this._executionEnvironment
                             .RunStreamingAsync(this._workflow,
                                          messages,
                                          this.SessionId,
                                          cancellationToken)
                             .ConfigureAwait(false);
-        return new ResumeRunResult(newRun);
     }
 
-    /// <summary>
-    /// Sends messages to the run, converting FunctionResultContent and UserInputResponseContent
-    /// to ExternalResponse when there's a matching pending request.
-    /// </summary>
-    /// <returns>
-    /// Structured information about how resume content was dispatched.
-    /// </returns>
-    private async ValueTask<ResumeDispatchInfo> SendMessagesWithResponseConversionAsync(StreamingRun run, List<ChatMessage> messages)
-    {
-        List<ChatMessage> regularMessages = [];
-        // Responses are deferred until after regular messages are queued so response handlers
-        // can merge buffered regular content in the same continuation turn.
-        List<(ExternalResponse Response, string RequestId)> externalResponses = [];
-        bool hasMatchedResponseForStartExecutor = false;
-
-        // Tracks content IDs already matched to pending requests within this invocation,
-        // preventing duplicate responses for the same ID from being sent to the workflow engine.
-        HashSet<string>? matchedContentIds = null;
-
-        foreach (ChatMessage message in messages)
-        {
-            List<AIContent> regularContents = [];
-
-            foreach (AIContent content in message.Contents)
-            {
-                string? contentId = GetResponseContentId(content);
-
-                // Skip duplicate response content for an already-matched content ID
-                if (contentId != null && matchedContentIds?.Contains(contentId) == true)
-                {
-                    continue;
-                }
-
-                if (contentId != null
-                    && this.TryGetPendingRequest(contentId) is ExternalRequest pendingRequest)
-                {
-                    // For intercepted/complex topologies the port may not be registered in the EdgeMap.
-                    // Treat unknown port as non-start-executor (conservative): TurnToken will still be sent.
-                    if (run.TryGetResponsePortExecutorId(pendingRequest.PortInfo.PortId, out string? responseExecutorId))
-                    {
-                        hasMatchedResponseForStartExecutor |= string.Equals(responseExecutorId, this._workflow.StartExecutorId, StringComparison.Ordinal);
-                    }
-
-                    AIContent normalizedResponseContent = NormalizeResponseContentForDelivery(content, pendingRequest);
-                    externalResponses.Add((pendingRequest.CreateResponse(normalizedResponseContent), pendingRequest.RequestId));
-                    (matchedContentIds ??= new(StringComparer.Ordinal)).Add(contentId);
-                }
-                else
-                {
-                    regularContents.Add(content);
-                }
-            }
-
-            if (regularContents.Count > 0)
-            {
-                ChatMessage cloned = message.Clone();
-                cloned.Contents = regularContents;
-                regularMessages.Add(cloned);
-            }
-        }
-
-        // Send regular messages first so response handlers can merge them with responses.
-        bool hasRegularMessages = regularMessages.Count > 0;
-        if (hasRegularMessages)
-        {
-            await run.TrySendMessageAsync(regularMessages).ConfigureAwait(false);
-        }
-
-        // Send external responses after regular messages.
-        bool hasMatchedExternalResponses = false;
-        foreach ((ExternalResponse response, string requestId) in externalResponses)
-        {
-            await run.SendResponseAsync(response).ConfigureAwait(false);
-            hasMatchedExternalResponses = true;
-            this.RemovePendingRequest(requestId);
-        }
-
-        return new ResumeDispatchInfo(
-            hasRegularMessages,
-            hasMatchedExternalResponses,
-            hasMatchedResponseForStartExecutor);
-    }
-
-    /// <summary>
-    /// Creates the workflow-facing request content surfaced in response updates.
-    /// </summary>
-    private static AIContent CreateRequestContentForDelivery(ExternalRequest request) => request switch
-    {
-        ExternalRequest externalRequest when externalRequest.TryGetDataAs(out FunctionCallContent? functionCallContent)
-            => CloneFunctionCallContent(functionCallContent, externalRequest.RequestId),
-        ExternalRequest externalRequest when externalRequest.TryGetDataAs(out ToolApprovalRequestContent? toolApprovalRequestContent)
-            => CloneToolApprovalRequestContent(toolApprovalRequestContent, externalRequest.RequestId),
-        ExternalRequest externalRequest
-            => externalRequest.ToFunctionCall(),
-    };
-
-    /// <summary>
-    /// Rewrites workflow-facing response content back to the original agent-owned content ID.
-    /// </summary>
-    private static AIContent NormalizeResponseContentForDelivery(AIContent content, ExternalRequest request) => content switch
-    {
-        FunctionResultContent functionResultContent when request.TryGetDataAs(out FunctionCallContent? functionCallContent)
-            => CloneFunctionResultContent(functionResultContent, functionCallContent.CallId),
-        ToolApprovalResponseContent toolApprovalResponseContent when request.TryGetDataAs(out ToolApprovalRequestContent? toolApprovalRequestContent)
-            => CloneToolApprovalResponseContent(toolApprovalResponseContent, toolApprovalRequestContent.RequestId),
-        _ => content,
-    };
-
-    /// <summary>
-    /// Gets the workflow-facing request ID from response content types.
-    /// </summary>
-    private static string? GetResponseContentId(AIContent content) => content switch
-    {
-        FunctionResultContent functionResultContent => functionResultContent.CallId,
-        ToolApprovalResponseContent toolApprovalResponseContent => toolApprovalResponseContent.RequestId,
-        _ => null
-    };
-
-    /// <summary>
-    /// Tries to get a pending request by workflow-facing request ID.
-    /// </summary>
-    private ExternalRequest? TryGetPendingRequest(string requestId) =>
-        this._pendingRequests.TryGetValue(requestId, out ExternalRequest? request) ? request : null;
-
-    /// <summary>
-    /// Adds a pending request indexed by workflow-facing request ID.
-    /// </summary>
-    private void AddPendingRequest(string requestId, ExternalRequest request) => this._pendingRequests[requestId] = request;
-
-    /// <summary>
-    /// Removes a pending request by workflow-facing request ID.
-    /// </summary>
-    private void RemovePendingRequest(string requestId) =>
-        this._pendingRequests.Remove(requestId);
-
     internal async
     IAsyncEnumerable<AgentResponseUpdate> InvokeStageAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
-        this.LastResponseId = Guid.NewGuid().ToString("N");
-        List<ChatMessage> messages = this.ChatHistoryProvider.GetFromBookmark(this).ToList();
+        try
+        {
+            this.LastResponseId = Guid.NewGuid().ToString("N");
+            List<ChatMessage> messages = this.ChatHistoryProvider.GetFromBookmark(this).ToList();
 
-        ResumeRunResult resumeResult =
-            await this.CreateOrResumeRunAsync(messages, cancellationToken).ConfigureAwait(false);
-
-#pragma warning disable CA2007 // Analyzer misfiring.
-        await using StreamingRun run = resumeResult.Run;
+#pragma warning disable CA2007 // Analyzer misfiring and not seeing .ConfigureAwait(false) below.
+            await using StreamingRun run =
+                await this.CreateOrResumeRunAsync(messages, cancellationToken).ConfigureAwait(false);
 #pragma warning restore CA2007
 
-        ResumeDispatchInfo dispatchInfo = resumeResult.DispatchInfo;
-
-        // Send a TurnToken to the start executor unless the only activity is an external
-        // response directed at the start executor itself (which self-emits a TurnToken via
-        // ContinueTurnAsync). Non-start executors (e.g., RequestInfoExecutor) do not emit
-        // TurnTokens after processing responses, so the session must always provide one.
-        bool shouldSendTurnToken =
-            !dispatchInfo.HasMatchedExternalResponses
-            || !dispatchInfo.HasMatchedResponseForStartExecutor;
-        if (shouldSendTurnToken)
-        {
             await run.TrySendMessageAsync(new TurnToken(emitEvents: true)).ConfigureAwait(false);
-        }
-        await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false, cancellationToken)
+            await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false, cancellationToken)
                                                .ConfigureAwait(false)
                                                .WithCancellation(cancellationToken))
-        {
-            switch (evt)
             {
-                case AgentResponseUpdateEvent agentUpdate:
-                    yield return agentUpdate.Update;
-                    break;
+                switch (evt)
+                {
+                    case AgentResponseUpdateEvent agentUpdate:
+                        yield return agentUpdate.Update;
+                        break;
 
-                case RequestInfoEvent requestInfo:
-                    AIContent requestContent = CreateRequestContentForDelivery(requestInfo.Request);
+                    case RequestInfoEvent requestInfo:
+                        FunctionCallContent fcContent = requestInfo.Request.ToFunctionCall();
+                        AgentResponseUpdate update = this.CreateUpdate(this.LastResponseId, evt, fcContent);
+                        yield return update;
+                        break;
 
-                    // Track the pending request so we can convert incoming responses back to ExternalResponse.
-                    // External callers respond using the workflow-facing request ID, which is always RequestId.
-                    this.AddPendingRequest(requestInfo.Request.RequestId, requestInfo.Request);
+                    case WorkflowErrorEvent workflowError:
+                        Exception? exception = workflowError.Exception;
+                        if (exception is TargetInvocationException tie && tie.InnerException != null)
+                        {
+                            exception = tie.InnerException;
+                        }
 
-                    AgentResponseUpdate update = this.CreateUpdate(this.LastResponseId, evt, requestContent);
-                    yield return update;
-                    break;
+                        if (exception != null)
+                        {
+                            string message = this._includeExceptionDetails
+                                           ? exception.Message
+                                           : "An error occurred while executing the workflow.";
 
-                case WorkflowErrorEvent workflowError:
-                    Exception? exception = workflowError.Exception;
-                    if (exception is TargetInvocationException tie && tie.InnerException != null)
-                    {
-                        exception = tie.InnerException;
-                    }
+                            ErrorContent errorContent = new(message);
+                            yield return this.CreateUpdate(this.LastResponseId, evt, errorContent);
+                        }
 
-                    if (exception != null)
-                    {
-                        string message = this._includeExceptionDetails
-                                       ? exception.Message
-                                       : "An error occurred while executing the workflow.";
+                        break;
 
-                        ErrorContent errorContent = new(message);
-                        yield return this.CreateUpdate(this.LastResponseId, evt, errorContent);
-                    }
-
-                    break;
-
-                case SuperStepCompletedEvent stepCompleted:
-                    this.LastCheckpoint = stepCompleted.CompletionInfo?.Checkpoint;
-                    goto default;
-
-                case WorkflowOutputEvent output:
-                    IEnumerable<ChatMessage>? updateMessages = output.Data switch
-                    {
-                        IEnumerable<ChatMessage> chatMessages => chatMessages,
-                        ChatMessage chatMessage => [chatMessage],
-                        _ => null
-                    };
-
-                    if (!this._includeWorkflowOutputsInResponse || updateMessages == null)
-                    {
+                    case SuperStepCompletedEvent stepCompleted:
+                        this.LastCheckpoint = stepCompleted.CompletionInfo?.Checkpoint;
                         goto default;
-                    }
 
-                    foreach (ChatMessage message in updateMessages)
-                    {
-                        yield return this.CreateUpdate(this.LastResponseId, evt, message);
-                    }
-                    break;
+                    case WorkflowOutputEvent output:
+                        IEnumerable<ChatMessage>? updateMessages = output.Data switch
+                        {
+                            IEnumerable<ChatMessage> chatMessages => chatMessages,
+                            ChatMessage chatMessage => [chatMessage],
+                            _ => null
+                        };
 
-                default:
-                    // Emit all other workflow events for observability (DevUI, logging, etc.)
-                    yield return new AgentResponseUpdate(ChatRole.Assistant, [])
-                    {
-                        CreatedAt = DateTimeOffset.UtcNow,
-                        MessageId = Guid.NewGuid().ToString("N"),
-                        Role = ChatRole.Assistant,
-                        ResponseId = this.LastResponseId,
-                        RawRepresentation = evt
-                    };
-                    break;
+                        if (!this._includeWorkflowOutputsInResponse || updateMessages == null)
+                        {
+                            goto default;
+                        }
+
+                        foreach (ChatMessage message in updateMessages)
+                        {
+                            yield return this.CreateUpdate(this.LastResponseId, evt, message);
+                        }
+                        break;
+
+                    default:
+                        // Emit all other workflow events for observability (DevUI, logging, etc.)
+                        yield return new AgentResponseUpdate(ChatRole.Assistant, [])
+                        {
+                            CreatedAt = DateTimeOffset.UtcNow,
+                            MessageId = Guid.NewGuid().ToString("N"),
+                            Role = ChatRole.Assistant,
+                            ResponseId = this.LastResponseId,
+                            RawRepresentation = evt
+                        };
+                        break;
+                }
             }
         }
+        finally
+        {
+            // Do we want to try to undo the step, and not update the bookmark?
+            this.ChatHistoryProvider.UpdateBookmark(this);
+        }
     }
 
     public string? LastResponseId { get; set; }
@@ -428,116 +267,15 @@ internal sealed class WorkflowSession : AgentSession
     /// <inheritdoc/>
     public WorkflowChatHistoryProvider ChatHistoryProvider { get; }
 
-    /// <summary>
-    /// Captures the outcome of creating or resuming a workflow run,
-    /// indicating what types of messages were sent during resume.
-    /// </summary>
-    private readonly struct ResumeRunResult
-    {
-        /// <summary>The streaming run that was created or resumed.</summary>
-        public StreamingRun Run { get; }
-
-        /// <summary>How resume-time content was dispatched into the workflow runtime.</summary>
-        public ResumeDispatchInfo DispatchInfo { get; }
-
-        public ResumeRunResult(StreamingRun run, ResumeDispatchInfo dispatchInfo = default)
-        {
-            this.Run = Throw.IfNull(run);
-            this.DispatchInfo = dispatchInfo;
-        }
-    }
-
-    /// <summary>
-    /// Captures how resumed input was split across regular-message and external-response delivery paths.
-    /// </summary>
-    private readonly struct ResumeDispatchInfo
-    {
-        public ResumeDispatchInfo(bool hasRegularMessages, bool hasMatchedExternalResponses, bool hasMatchedResponseForStartExecutor)
-        {
-            this.HasRegularMessages = hasRegularMessages;
-            this.HasMatchedExternalResponses = hasMatchedExternalResponses;
-            this.HasMatchedResponseForStartExecutor = hasMatchedResponseForStartExecutor;
-        }
-
-        public bool HasRegularMessages { get; }
-
-        public bool HasMatchedExternalResponses { get; }
-
-        public bool HasMatchedResponseForStartExecutor { get; }
-    }
-
-    /// <summary>
-    /// Clones a <see cref="FunctionCallContent"/> with a workflow-facing call ID.
-    /// </summary>
-    private static FunctionCallContent CloneFunctionCallContent(FunctionCallContent content, string callId)
-    {
-        FunctionCallContent clone = new(callId, content.Name, content.Arguments)
-        {
-            Exception = content.Exception,
-            InformationalOnly = content.InformationalOnly,
-        };
-
-        return CopyContentMetadata(content, clone);
-    }
-
-    /// <summary>
-    /// Clones a <see cref="FunctionResultContent"/> with an agent-owned call ID.
-    /// </summary>
-    private static FunctionResultContent CloneFunctionResultContent(FunctionResultContent content, string callId)
-    {
-        FunctionResultContent clone = new(callId, content.Result)
-        {
-            Exception = content.Exception,
-        };
-
-        return CopyContentMetadata(content, clone);
-    }
-
-    /// <summary>
-    /// Clones a <see cref="ToolApprovalRequestContent"/> with a workflow-facing request ID.
-    /// </summary>
-    private static ToolApprovalRequestContent CloneToolApprovalRequestContent(ToolApprovalRequestContent content, string id)
-    {
-        ToolApprovalRequestContent clone = new(id, content.ToolCall);
-        return CopyContentMetadata(content, clone);
-    }
-
-    /// <summary>
-    /// Clones a <see cref="ToolApprovalResponseContent"/> with an agent-owned request ID.
-    /// </summary>
-    private static ToolApprovalResponseContent CloneToolApprovalResponseContent(ToolApprovalResponseContent content, string id)
-    {
-        ToolApprovalResponseContent clone = new(id, content.Approved, content.ToolCall)
-        {
-            Reason = content.Reason,
-        };
-
-        return CopyContentMetadata(content, clone);
-    }
-
-    /// <summary>
-    /// Copies shared <see cref="AIContent"/> metadata to a cloned content instance.
-    /// </summary>
-    private static TContent CopyContentMetadata<TContent>(AIContent source, TContent target)
-        where TContent : AIContent
-    {
-        target.AdditionalProperties = source.AdditionalProperties;
-        target.Annotations = source.Annotations;
-        target.RawRepresentation = source.RawRepresentation;
-        return target;
-    }
-
     internal sealed class SessionState(
         string sessionId,
         CheckpointInfo? lastCheckpoint,
         InMemoryCheckpointManager? checkpointManager = null,
-        AgentSessionStateBag? stateBag = null,
-        Dictionary<string, ExternalRequest>? pendingRequests = null)
+        AgentSessionStateBag? stateBag = null)
     {
         public string SessionId { get; } = sessionId;
         public CheckpointInfo? LastCheckpoint { get; } = lastCheckpoint;
         public InMemoryCheckpointManager? CheckpointManager { get; } = checkpointManager;
         public AgentSessionStateBag StateBag { get; } = stateBag ?? new();
-        public Dictionary<string, ExternalRequest>? PendingRequests { get; } = pendingRequests;
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowsJsonUtilities.cs

@@ -71,7 +71,6 @@ internal static partial class WorkflowsJsonUtilities
     [JsonSerializable(typeof(PortableValue))]
     [JsonSerializable(typeof(PortableMessageEnvelope))]
     [JsonSerializable(typeof(InMemoryCheckpointManager))]
-    [JsonSerializable(typeof(CheckpointFileIndexEntry))]
 
     // Runtime State Types
     [JsonSerializable(typeof(ScopeKey))]

dotnet/src/Microsoft.Agents.AI/AIContextProviderDecorators/AIContextProviderChatClient.cs

@@ -161,8 +161,6 @@ internal sealed class AIContextProviderChatClient : DelegatingChatClient
         }
 
         // Materialize the accumulated context back into messages and options.
-        // Clone options to avoid mutating the caller's instance across calls.
-        options = options?.Clone();
         var enrichedMessages = aiContext.Messages ?? [];
 
         var tools = aiContext.Tools as IList<AITool> ?? aiContext.Tools?.ToList();

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs

@@ -138,9 +138,6 @@ public sealed partial class ChatClientAgent : AIAgent
         this._aiContextProviderStateKeys = ValidateAndCollectStateKeys(this._agentOptions?.AIContextProviders, this.ChatHistoryProvider);
 
         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();
     }
 
     /// <summary>
@@ -214,14 +211,12 @@ public sealed partial class ChatClientAgent : AIAgent
          ChatClientAgentContinuationToken? _) =
             await this.PrepareSessionAndMessagesAsync(session, inputMessages, options, cancellationToken).ConfigureAwait(false);
 
-        // Update the run context with the resolved session so any downstream classes
-        // always have a valid session, even when the caller passed null.
-        EnsureRunContextHasSession(safeSession);
-
         var chatClient = this.ChatClient;
+
         chatClient = ApplyRunOptionsTransformations(options, chatClient);
 
         var loggingAgentName = this.GetLoggingAgentName();
+
         this._logger.LogAgentChatClientInvokingAgent(nameof(RunAsync), this.Id, loggingAgentName, this._chatClientType);
 
         // Call the IChatClient and notify the AIContextProvider of any failures.
@@ -232,7 +227,8 @@ public sealed partial class ChatClientAgent : AIAgent
         }
         catch (Exception ex)
         {
-            await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, inputMessagesForChatClient, chatOptions, cancellationToken).ConfigureAwait(false);
+            await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, inputMessagesForChatClient, chatOptions, cancellationToken).ConfigureAwait(false);
+            await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, inputMessagesForChatClient, cancellationToken).ConfigureAwait(false);
             throw;
         }
 
@@ -240,8 +236,7 @@ public sealed partial class ChatClientAgent : AIAgent
 
         // We can derive the type of supported session from whether we have a conversation id,
         // so let's update it and set the conversation id for the service session case.
-        var forceEndOfRunPersistence = chatOptions?.ContinuationToken is not null || chatOptions?.AllowBackgroundResponses is true;
-        this.UpdateSessionConversationIdAtEndOfRun(safeSession, chatResponse.ConversationId, cancellationToken, forceUpdate: forceEndOfRunPersistence);
+        this.UpdateSessionConversationId(safeSession, chatResponse.ConversationId, cancellationToken);
 
         // Ensure that the author name is set for each message in the response.
         foreach (ChatMessage chatResponseMessage in chatResponse.Messages)
@@ -249,10 +244,11 @@ public sealed partial class ChatClientAgent : AIAgent
             chatResponseMessage.AuthorName ??= this.Name;
         }
 
-        // Notify providers of all new messages unless persistence is handled per-service-call by the decorator.
-        // When background responses are allowed, force notification since per-service-call persistence
-        // is unreliable (the caller may stop consuming the stream before the decorator can persist).
-        await this.NotifyProvidersOfNewMessagesAtEndOfRunAsync(safeSession, inputMessagesForChatClient, chatResponse.Messages, chatOptions, cancellationToken, forceNotify: forceEndOfRunPersistence).ConfigureAwait(false);
+        // Only notify the session of new messages if the chatResponse was successful to avoid inconsistent message state in the session.
+        await this.NotifyChatHistoryProviderOfNewMessagesAsync(safeSession, inputMessagesForChatClient, chatResponse.Messages, chatOptions, cancellationToken).ConfigureAwait(false);
+
+        // Notify the AIContextProvider of all new messages.
+        await this.NotifyAIContextProviderOfSuccessAsync(safeSession, inputMessagesForChatClient, chatResponse.Messages, cancellationToken).ConfigureAwait(false);
 
         return new AgentResponse(chatResponse)
         {
@@ -300,10 +296,6 @@ public sealed partial class ChatClientAgent : AIAgent
          ChatClientAgentContinuationToken? continuationToken) =
             await this.PrepareSessionAndMessagesAsync(session, inputMessages, options, cancellationToken).ConfigureAwait(false);
 
-        // Update the run context with the resolved session so any downstream classes
-        // always have a valid session, even when the caller passed null.
-        EnsureRunContextHasSession(safeSession);
-
         var chatClient = this.ChatClient;
 
         chatClient = ApplyRunOptionsTransformations(options, chatClient);
@@ -323,7 +315,8 @@ public sealed partial class ChatClientAgent : AIAgent
         }
         catch (Exception ex)
         {
-            await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
+            await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
+            await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), cancellationToken).ConfigureAwait(false);
             throw;
         }
 
@@ -337,7 +330,8 @@ public sealed partial class ChatClientAgent : AIAgent
         }
         catch (Exception ex)
         {
-            await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
+            await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
+            await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), cancellationToken).ConfigureAwait(false);
             throw;
         }
 
@@ -359,31 +353,27 @@ public sealed partial class ChatClientAgent : AIAgent
 
             try
             {
-                // Re-ensure the run context has the resolved session before each MoveNextAsync.
-                // The base class RunStreamingAsync restores the original context (potentially with
-                // null session) after each yield, so we must re-establish it for the decorator.
-                EnsureRunContextHasSession(safeSession);
                 hasUpdates = await responseUpdatesEnumerator.MoveNextAsync().ConfigureAwait(false);
             }
             catch (Exception ex)
             {
-                await this.NotifyProvidersOfFailureAtEndOfRunAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
+                await this.NotifyChatHistoryProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), chatOptions, cancellationToken).ConfigureAwait(false);
+                await this.NotifyAIContextProviderOfFailureAsync(safeSession, ex, GetInputMessages(inputMessagesForChatClient, continuationToken), cancellationToken).ConfigureAwait(false);
                 throw;
             }
         }
 
         var chatResponse = responseUpdates.ToChatResponse();
 
-        var forceEndOfRunPersistence = continuationToken is not null || chatOptions?.AllowBackgroundResponses is true;
-
         // We can derive the type of supported session from whether we have a conversation id,
         // so let's update it and set the conversation id for the service session case.
-        this.UpdateSessionConversationIdAtEndOfRun(safeSession, chatResponse.ConversationId, cancellationToken, forceUpdate: forceEndOfRunPersistence);
+        this.UpdateSessionConversationId(safeSession, chatResponse.ConversationId, cancellationToken);
 
-        // Notify providers of all new messages unless persistence is handled per-service-call by the decorator.
-        // When resuming from a continuation token or using background responses, force notification
-        // to send the combined data (per-service-call persistence is unreliable for these scenarios).
-        await this.NotifyProvidersOfNewMessagesAtEndOfRunAsync(safeSession, GetInputMessages(inputMessagesForChatClient, continuationToken), chatResponse.Messages, chatOptions, cancellationToken, forceNotify: forceEndOfRunPersistence).ConfigureAwait(false);
+        // To avoid inconsistent state we only notify the session of the input messages if no error occurs after the initial request.
+        await this.NotifyChatHistoryProviderOfNewMessagesAsync(safeSession, GetInputMessages(inputMessagesForChatClient, continuationToken), chatResponse.Messages, chatOptions, cancellationToken).ConfigureAwait(false);
+
+        // Notify the AIContextProvider of all new messages.
+        await this.NotifyAIContextProviderOfSuccessAsync(safeSession, GetInputMessages(inputMessagesForChatClient, continuationToken), chatResponse.Messages, cancellationToken).ConfigureAwait(false);
     }
 
     /// <inheritdoc/>
@@ -451,29 +441,17 @@ public sealed partial class ChatClientAgent : AIAgent
     #region Private
 
     /// <summary>
-    /// Notifies the <see cref="ChatHistoryProvider"/> and all <see cref="AIContextProviders"/> of successfully completed messages.
+    /// Notify the <see cref="AIContextProvider"/> when an agent run succeeded, if there is an <see cref="AIContextProvider"/>.
     /// </summary>
-    /// <remarks>
-    /// This method is also called by <see cref="ChatHistoryPersistingChatClient"/> to persist messages per-service-call.
-    /// </remarks>
-    internal async Task NotifyProvidersOfNewMessagesAsync(
+    private async Task NotifyAIContextProviderOfSuccessAsync(
         ChatClientAgentSession session,
-        IEnumerable<ChatMessage> requestMessages,
+        IEnumerable<ChatMessage> inputMessages,
         IEnumerable<ChatMessage> responseMessages,
-        ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
-        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, session);
-
-        if (chatHistoryProvider is not null)
-        {
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, responseMessages);
-            await chatHistoryProvider.InvokedAsync(invokedContext, cancellationToken).ConfigureAwait(false);
-        }
-
         if (this.AIContextProviders is { Count: > 0 } contextProviders)
         {
-            AIContextProvider.InvokedContext invokedContext = new(this, session, requestMessages, responseMessages);
+            AIContextProvider.InvokedContext invokedContext = new(this, session, inputMessages, responseMessages);
 
             foreach (var contextProvider in contextProviders)
             {
@@ -483,29 +461,17 @@ public sealed partial class ChatClientAgent : AIAgent
     }
 
     /// <summary>
-    /// Notifies the <see cref="ChatHistoryProvider"/> and all <see cref="AIContextProviders"/> of a failure during a service call.
+    /// Notify the <see cref="AIContextProvider"/> of any failure during an agent run, if there is an <see cref="AIContextProvider"/>.
     /// </summary>
-    /// <remarks>
-    /// This method is also called by <see cref="ChatHistoryPersistingChatClient"/> to report failures per-service-call.
-    /// </remarks>
-    internal async Task NotifyProvidersOfFailureAsync(
+    private async Task NotifyAIContextProviderOfFailureAsync(
         ChatClientAgentSession session,
         Exception ex,
-        IEnumerable<ChatMessage> requestMessages,
-        ChatOptions? chatOptions,
+        IEnumerable<ChatMessage> inputMessages,
         CancellationToken cancellationToken)
     {
-        ChatHistoryProvider? chatHistoryProvider = this.ResolveChatHistoryProvider(chatOptions, session);
-
-        if (chatHistoryProvider is not null)
-        {
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, ex);
-            await chatHistoryProvider.InvokedAsync(invokedContext, cancellationToken).ConfigureAwait(false);
-        }
-
         if (this.AIContextProviders is { Count: > 0 } contextProviders)
         {
-            AIContextProvider.InvokedContext invokedContext = new(this, session, requestMessages, ex);
+            AIContextProvider.InvokedContext invokedContext = new(this, session, inputMessages, ex);
 
             foreach (var contextProvider in contextProviders)
             {
@@ -701,12 +667,6 @@ 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))
-        {
-            var warningAgentName = this.GetLoggingAgentName();
-            this._logger.LogAgentChatClientBackgroundResponseFallback(this.Id, warningAgentName);
-        }
-
         session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
         if (session is not ChatClientAgentSession typedSession)
         {
@@ -788,20 +748,13 @@ 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);
-
         // 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();
 
         return (typedSession, chatOptions, messagesList, continuationToken);
     }
 
-    internal void UpdateSessionConversationId(ChatClientAgentSession session, string? responseConversationId, CancellationToken cancellationToken)
+    private void UpdateSessionConversationId(ChatClientAgentSession session, string? responseConversationId, CancellationToken cancellationToken)
     {
         if (string.IsNullOrWhiteSpace(responseConversationId) && !string.IsNullOrWhiteSpace(session.ConversationId))
         {
@@ -845,182 +798,45 @@ public sealed partial class ChatClientAgent : AIAgent
         }
     }
 
-    /// <summary>
-    /// 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"/>
-    /// (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)
-        {
-            return;
-        }
-
-        this.UpdateSessionConversationId(session, responseConversationId, cancellationToken);
-    }
-
-    /// <summary>
-    /// 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 <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.
-    /// </remarks>
-    private Task NotifyProvidersOfNewMessagesAtEndOfRunAsync(
-        ChatClientAgentSession session,
-        IEnumerable<ChatMessage> requestMessages,
-        IEnumerable<ChatMessage> responseMessages,
-        ChatOptions? chatOptions,
-        CancellationToken cancellationToken,
-        bool forceNotify = false)
-    {
-        if (!forceNotify && this.PersistsChatHistoryPerServiceCall)
-        {
-            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);
-    }
-
-    /// <summary>
-    /// 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
-    /// 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>
-    private Task NotifyProvidersOfFailureAtEndOfRunAsync(
+    private Task NotifyChatHistoryProviderOfFailureAsync(
         ChatClientAgentSession session,
         Exception ex,
         IEnumerable<ChatMessage> requestMessages,
         ChatOptions? chatOptions,
         CancellationToken cancellationToken)
     {
-        if (this.PersistsChatHistoryPerServiceCall)
+        ChatHistoryProvider? provider = this.ResolveChatHistoryProvider(chatOptions, session);
+
+        // Only notify the provider if we have one.
+        // If we don't have one, it means that the chat history is service managed and the underlying service is responsible for storing messages.
+        if (provider is not null)
         {
-            return Task.CompletedTask;
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, ex);
+
+            return provider.InvokedAsync(invokedContext, cancellationToken).AsTask();
         }
 
-        return this.NotifyProvidersOfFailureAsync(session, ex, requestMessages, chatOptions, cancellationToken);
+        return Task.CompletedTask;
     }
 
-    /// <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.
-    /// </summary>
-    private bool PersistsChatHistoryPerServiceCall
+    private Task NotifyChatHistoryProviderOfNewMessagesAsync(
+        ChatClientAgentSession session,
+        IEnumerable<ChatMessage> requestMessages,
+        IEnumerable<ChatMessage> responseMessages,
+        ChatOptions? chatOptions,
+        CancellationToken cancellationToken)
     {
-        get
-        {
-            var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
-            return persistingClient?.MarkOnly == false;
-        }
-    }
+        ChatHistoryProvider? provider = this.ResolveChatHistoryProvider(chatOptions, session);
 
-    /// <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))
+        // Only notify the provider if we have one.
+        // If we don't have one, it means that the chat history is service managed and the underlying service is responsible for storing messages.
+        if (provider is not null)
         {
-            chatOptions ??= new ChatOptions();
-            chatOptions.ConversationId = ChatHistoryPersistingChatClient.LocalHistoryConversationId;
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, requestMessages, responseMessages);
+            return provider.InvokedAsync(invokedContext, cancellationToken).AsTask();
         }
 
-        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>
-    /// <remarks>
-    /// 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.
-    /// The original agent from the context is preserved to maintain the top-of-stack agent in
-    /// decorated agent scenarios.
-    /// </remarks>
-    private static void EnsureRunContextHasSession(ChatClientAgentSession safeSession)
-    {
-        var context = CurrentRunContext;
-        if (context is not null && context.Session != safeSession)
-        {
-            CurrentRunContext = new(context.Agent, safeSession, context.RequestMessages, context.RunOptions);
-        }
-    }
-
-    /// <summary>
-    /// Checks for potential misconfiguration when using a custom chat client stack and logs warnings.
-    /// </summary>
-    private void WarnOnMissingPersistingClient()
-    {
-        if (this._agentOptions?.UseProvidedChatClientAsIs is not true)
-        {
-            return;
-        }
-
-        if (this._agentOptions?.PersistChatHistoryAtEndOfRun is not true)
-        {
-            return;
-        }
-
-        var persistingClient = this.ChatClient.GetService<ChatHistoryPersistingChatClient>();
-        if (persistingClient is null && this._logger.IsEnabled(LogLevel.Warning))
-        {
-            var loggingAgentName = this.GetLoggingAgentName();
-            this._logger.LogAgentChatClientMissingPersistingClient(
-                this.Id,
-                loggingAgentName);
-        }
+        return Task.CompletedTask;
     }
 
     private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions, ChatClientAgentSession session)

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentLogMessages.cs

@@ -69,32 +69,4 @@ internal static partial class ChatClientAgentLogMessages
         string chatHistoryProviderName,
         string agentId,
         string agentName);
-
-    /// <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.
-    /// </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.")]
-    public static partial void LogAgentChatClientMissingPersistingClient(
-        this ILogger logger,
-        string agentId,
-        string agentName);
-
-    /// <summary>
-    /// Logs a warning when per-service-call persistence falls back to end-of-run persistence
-    /// because the run involves background responses (continuation token resumption or
-    /// <c>AllowBackgroundResponses</c>). Per-service-call persistence is
-    /// unreliable in these scenarios because the caller may stop consuming the stream before
-    /// the decorator's post-stream persistence code can execute.
-    /// </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.")]
-    public static partial void LogAgentChatClientBackgroundResponseFallback(
-        this ILogger logger,
-        string agentId,
-        string agentName);
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs

@@ -1,9 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Agents.AI;
 
@@ -91,56 +89,6 @@ public sealed class ChatClientAgentOptions
     /// </value>
     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.
-    /// </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.
-    /// </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"/>
-    /// 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; }
-
     /// <summary>
     /// Creates a new instance of <see cref="ChatClientAgentOptions"/> with the same values as this instance.
     /// </summary>
@@ -157,6 +105,5 @@ public sealed class ChatClientAgentOptions
             ClearOnChatHistoryProviderConflict = this.ClearOnChatHistoryProviderConflict,
             WarnOnChatHistoryProviderConflict = this.WarnOnChatHistoryProviderConflict,
             ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,
-            PersistChatHistoryAtEndOfRun = this.PersistChatHistoryAtEndOfRun,
         };
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientBuilderExtensions.cs

@@ -2,10 +2,8 @@
 
 using System;
 using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.Logging;
-using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -84,46 +82,4 @@ public static class ChatClientBuilderExtensions
             options: options,
             loggerFactory: loggerFactory,
             services: services);
-
-    /// <summary>
-    /// Adds a <see cref="ChatHistoryPersistingChatClient"/> 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.
-    /// </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.
-    /// </para>
-    /// <para>
-    /// This decorator only works within the context of a running <see cref="ChatClientAgent"/> and will throw an
-    /// exception if used in any other stack.
-    /// </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)
-    {
-        return builder.Use(innerClient => new ChatHistoryPersistingChatClient(innerClient, markOnly));
-    }
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientExtensions.cs

@@ -63,15 +63,6 @@ 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));
-
         var agentChatClient = chatBuilder.Build(services);
 
         if (options?.ChatOptions?.Tools is { Count: > 0 })

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatHistoryPersistingChatClient.cs

@@ -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;
-    }
-}

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs

@@ -1,58 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
-
-namespace Microsoft.Agents.AI;
-
-/// <summary>
-/// Abstract base class for all agent skills.
-/// </summary>
-/// <remarks>
-/// <para>
-/// A skill represents a domain-specific capability with instructions, resources, and scripts.
-/// Concrete implementations include <see cref="AgentFileSkill"/> (filesystem-backed).
-/// </para>
-/// <para>
-/// Skill metadata follows the <see href="https://agentskills.io/specification">Agent Skills specification</see>.
-/// </para>
-/// </remarks>
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public abstract class AgentSkill
-{
-    /// <summary>
-    /// Gets the frontmatter metadata for this skill.
-    /// </summary>
-    /// <remarks>
-    /// Contains the L1 discovery metadata (name, description, license, compatibility, etc.)
-    /// as defined by the <see href="https://agentskills.io/specification">Agent Skills specification</see>.
-    /// </remarks>
-    public abstract AgentSkillFrontmatter Frontmatter { get; }
-
-    /// <summary>
-    /// Gets the full skill content.
-    /// </summary>
-    /// <remarks>
-    /// For file-based skills this is the raw SKILL.md file content.
-    /// </remarks>
-    public abstract string Content { get; }
-
-    /// <summary>
-    /// Gets the resources associated with this skill, or <see langword="null"/> if none.
-    /// </summary>
-    /// <remarks>
-    /// The default implementation returns <see langword="null"/>.
-    /// Override this property in derived classes to provide skill-specific resources.
-    /// </remarks>
-    public virtual IReadOnlyList<AgentSkillResource>? Resources => null;
-
-    /// <summary>
-    /// Gets the scripts associated with this skill, or <see langword="null"/> if none.
-    /// </summary>
-    /// <remarks>
-    /// The default implementation returns <see langword="null"/>.
-    /// Override this property in derived classes to provide skill-specific scripts.
-    /// </remarks>
-    public virtual IReadOnlyList<AgentSkillScript>? Scripts => null;
-}

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillFrontmatter.cs

@@ -1,196 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Diagnostics.CodeAnalysis;
-using System.Text.RegularExpressions;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
-
-namespace Microsoft.Agents.AI;
-
-/// <summary>
-/// Represents the YAML frontmatter metadata parsed from a SKILL.md file.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Frontmatter is the L1 (discovery) layer of the
-/// <see href="https://agentskills.io/specification">Agent Skills specification</see>.
-/// It contains the minimal metadata needed to advertise a skill in the system prompt
-/// without loading the full skill content.
-/// </para>
-/// <para>
-/// The constructor validates the name and description against specification rules
-/// and throws <see cref="ArgumentException"/> if either value is invalid.
-/// </para>
-/// </remarks>
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class AgentSkillFrontmatter
-{
-    /// <summary>
-    /// Maximum allowed length for the skill name.
-    /// </summary>
-    internal const int MaxNameLength = 64;
-
-    /// <summary>
-    /// Maximum allowed length for the skill description.
-    /// </summary>
-    internal const int MaxDescriptionLength = 1024;
-
-    /// <summary>
-    /// Maximum allowed length for the compatibility field.
-    /// </summary>
-    internal const int MaxCompatibilityLength = 500;
-
-    // Validates skill names per the Agent Skills specification (https://agentskills.io/specification#frontmatter):
-    // lowercase letters, numbers, and hyphens only; must not start or end with a hyphen; must not contain consecutive hyphens.
-    private static readonly Regex s_validNameRegex = new("^[a-z0-9]([a-z0-9]*-[a-z0-9])*[a-z0-9]*$", RegexOptions.Compiled);
-
-    private string? _compatibility;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AgentSkillFrontmatter"/> class.
-    /// </summary>
-    /// <param name="name">Skill name in kebab-case.</param>
-    /// <param name="description">Skill description for discovery.</param>
-    /// <param name="compatibility">Optional compatibility information (max 500 chars).</param>
-    /// <exception cref="ArgumentException">
-    /// Thrown when <paramref name="name"/>, <paramref name="description"/>, or <paramref name="compatibility"/> violates the
-    /// <see href="https://agentskills.io/specification">Agent Skills specification</see> rules.
-    /// </exception>
-    public AgentSkillFrontmatter(string name, string description, string? compatibility = null)
-    {
-        if (!ValidateName(name, out string? reason) ||
-            !ValidateDescription(description, out reason) ||
-            !ValidateCompatibility(compatibility, out reason))
-        {
-            throw new ArgumentException(reason);
-        }
-
-        this.Name = name;
-        this.Description = description;
-        this._compatibility = compatibility;
-    }
-
-    /// <summary>
-    /// Gets the skill name. Lowercase letters, numbers, and hyphens only; no leading, trailing, or consecutive hyphens.
-    /// </summary>
-    public string Name { get; }
-
-    /// <summary>
-    /// Gets the skill description. Used for discovery in the system prompt.
-    /// </summary>
-    public string Description { get; }
-
-    /// <summary>
-    /// Gets or sets an optional license name or reference.
-    /// </summary>
-    public string? License { get; set; }
-
-    /// <summary>
-    /// Gets or sets optional compatibility information (max 500 chars).
-    /// </summary>
-    /// <exception cref="ArgumentException">
-    /// Thrown when the value exceeds <see cref="MaxCompatibilityLength"/> characters.
-    /// </exception>
-    public string? Compatibility
-    {
-        get => this._compatibility;
-        set
-        {
-            if (!ValidateCompatibility(value, out string? reason))
-            {
-                throw new ArgumentException(reason);
-            }
-
-            this._compatibility = value;
-        }
-    }
-
-    /// <summary>
-    /// Gets or sets optional space-delimited list of pre-approved tools.
-    /// </summary>
-    public string? AllowedTools { get; set; }
-
-    /// <summary>
-    /// Gets or sets the arbitrary key-value metadata for this skill.
-    /// </summary>
-    public AdditionalPropertiesDictionary? Metadata { get; set; }
-
-    /// <summary>
-    /// Validates a skill name against specification rules.
-    /// </summary>
-    /// <param name="name">The skill name to validate (may be <see langword="null"/>).</param>
-    /// <param name="reason">When validation fails, contains a human-readable description of the failure.</param>
-    /// <returns><see langword="true"/> if the name is valid; otherwise, <see langword="false"/>.</returns>
-    public static bool ValidateName(
-        string? name,
-        [NotNullWhen(false)] out string? reason)
-    {
-        if (string.IsNullOrWhiteSpace(name))
-        {
-            reason = "Skill name is required.";
-            return false;
-        }
-
-        if (name.Length > MaxNameLength)
-        {
-            reason = $"Skill name must be {MaxNameLength} characters or fewer.";
-            return false;
-        }
-
-        if (!s_validNameRegex.IsMatch(name))
-        {
-            reason = "Skill name must use only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen or contain consecutive hyphens.";
-            return false;
-        }
-
-        reason = null;
-        return true;
-    }
-
-    /// <summary>
-    /// Validates a skill description against specification rules.
-    /// </summary>
-    /// <param name="description">The skill description to validate (may be <see langword="null"/>).</param>
-    /// <param name="reason">When validation fails, contains a human-readable description of the failure.</param>
-    /// <returns><see langword="true"/> if the description is valid; otherwise, <see langword="false"/>.</returns>
-    public static bool ValidateDescription(
-        string? description,
-        [NotNullWhen(false)] out string? reason)
-    {
-        if (string.IsNullOrWhiteSpace(description))
-        {
-            reason = "Skill description is required.";
-            return false;
-        }
-
-        if (description.Length > MaxDescriptionLength)
-        {
-            reason = $"Skill description must be {MaxDescriptionLength} characters or fewer.";
-            return false;
-        }
-
-        reason = null;
-        return true;
-    }
-
-    /// <summary>
-    /// Validates an optional skill compatibility value against specification rules.
-    /// </summary>
-    /// <param name="compatibility">The optional compatibility value to validate (may be <see langword="null"/>).</param>
-    /// <param name="reason">When validation fails, contains a human-readable description of the failure.</param>
-    /// <returns><see langword="true"/> if the value is valid; otherwise, <see langword="false"/>.</returns>
-    public static bool ValidateCompatibility(
-        string? compatibility,
-        [NotNullWhen(false)] out string? reason)
-    {
-        if (compatibility?.Length > MaxCompatibilityLength)
-        {
-            reason = $"Skill compatibility must be {MaxCompatibilityLength} characters or fewer.";
-            return false;
-        }
-
-        reason = null;
-        return true;
-    }
-}

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillResource.cs

@@ -1,46 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Diagnostics.CodeAnalysis;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Shared.DiagnosticIds;
-using Microsoft.Shared.Diagnostics;
-
-namespace Microsoft.Agents.AI;
-
-/// <summary>
-/// Abstract base class for skill resources. A resource provides supplementary content (references, assets) to a skill.
-/// </summary>
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public abstract class AgentSkillResource
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AgentSkillResource"/> class.
-    /// </summary>
-    /// <param name="name">The resource name (e.g., relative path or identifier).</param>
-    /// <param name="description">An optional description of the resource.</param>
-    protected AgentSkillResource(string name, string? description = null)
-    {
-        this.Name = Throw.IfNullOrWhitespace(name);
-        this.Description = description;
-    }
-
-    /// <summary>
-    /// Gets the resource name.
-    /// </summary>
-    public string Name { get; }
-
-    /// <summary>
-    /// Gets the optional resource description.
-    /// </summary>
-    public string? Description { get; }
-
-    /// <summary>
-    /// Reads the resource content asynchronously.
-    /// </summary>
-    /// <param name="serviceProvider">Optional service provider for dependency injection.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The resource content.</returns>
-    public abstract Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default);
-}